Refactor Proj context handling behind a Context type

Introduce an internal Context enum (Owned/Shared) plus a reference-counted
SharedContext and a per-thread SHARED_CONTEXT thread-local. Proj.ctx becomes
a Context; helpers take it by value and Context's Drop destroys Owned contexts
(replacing the explicit proj_context_destroy in Proj::drop). Move ctx() out of
define_info_methods! into per-type accessors.

Note: every constructor still produces Context::Owned. The
Shared variant and thread_local_context() are wired up in the next commit: the work is split in order to allow more precise identification of leaks / memory corruption


Signed-off-by: Stephan Hügel <shugel@tcd.ie>

Author: urschrei

src/proj.rs

@@ -31,6 +31,7 @@ use std::ffi::CStr;
 use std::ffi::CString;
 use std::mem::MaybeUninit;
 use std::path::Path;
+use std::rc::Rc;
 use thiserror::Error;
 
 pub trait CoordinateType: Float + Copy + PartialOrd + Debug {}
@@ -207,11 +208,75 @@ fn area_set_bbox(parea: *mut proj_sys::PJ_AREA, new_area: Option<Area>) {
     }
 }
 
+/// A PROJ context (`PJ_CONTEXT`) owned or borrowed by a [`Proj`].
+///
+/// `Owned` contexts are created (or cloned) for a single `Proj` and destroyed when it is dropped.
+/// `Shared` contexts are the per-thread context returned by [`thread_local_context`]; the context
+/// is reference counted so that it outlives every `Proj` that uses it, regardless of the order in
+/// which the thread-local and any surviving `Proj` instances are dropped at thread exit.
+enum Context {
+    Owned(*mut PJ_CONTEXT),
+    // Wired into Proj::new/new_known_crs in a follow-up commit.
+    #[allow(dead_code)]
+    Shared(Rc<SharedContext>),
+}
+
+impl Context {
+    fn as_ptr(&self) -> *mut PJ_CONTEXT {
+        match self {
+            Context::Owned(ctx) => *ctx,
+            Context::Shared(shared) => shared.ctx,
+        }
+    }
+}
+
+impl Drop for Context {
+    fn drop(&mut self) {
+        // `Owned` contexts are destroyed here; `Shared` contexts are destroyed by
+        // `SharedContext::drop` once the last reference (thread-local or `Proj`) is gone.
+        if let Context::Owned(ctx) = *self {
+            unsafe { proj_context_destroy(ctx) };
+        }
+    }
+}
+
+/// The per-thread PROJ context, reference counted so it can be shared between every [`Proj`]
+/// created on the thread via [`Proj::new`] and [`Proj::new_known_crs`].
+struct SharedContext {
+    ctx: *mut PJ_CONTEXT,
+}
+
+impl Drop for SharedContext {
+    fn drop(&mut self) {
+        // Must only destroy the context: this runs during thread-local teardown, so it must not
+        // re-enter the `SHARED_CONTEXT` thread-local. We deliberately do not call proj_cleanup()
+        // (see the note in `Drop for Proj`).
+        unsafe { proj_context_destroy(self.ctx) };
+    }
+}
+
+thread_local! {
+    /// One PROJ context per thread, reused by `Proj::new`/`Proj::new_known_crs`. Creating a fresh
+    /// context per object opens a new connection to the PROJ database with cold caches, which
+    /// dominates `Proj` construction time (see https://github.com/georust/proj/issues/256).
+    static SHARED_CONTEXT: Rc<SharedContext> =
+        Rc::new(SharedContext { ctx: unsafe { proj_context_create() } });
+}
+
+/// Return a reference-counted handle to the calling thread's shared PROJ context.
+#[allow(dead_code)] // wired into Proj::new/new_known_crs in a follow-up commit
+fn thread_local_context() -> Context {
+    Context::Shared(SHARED_CONTEXT.with(Rc::clone))
+}
+
 /// called by Proj::new and ProjBuilder::transform_new_crs
-fn transform_string(ctx: *mut PJ_CONTEXT, definition: &str) -> Result<Proj, ProjCreateError> {
+fn transform_string(ctx: Context, definition: &str) -> Result<Proj, ProjCreateError> {
+    let ctx_ptr = ctx.as_ptr();
     let c_definition = CString::new(definition).map_err(ProjCreateError::ArgumentNulError)?;
-    let ptr = result_from_create(ctx, unsafe { proj_create(ctx, c_definition.as_ptr()) })
-        .map_err(|e| ProjCreateError::ProjError(e.message(ctx)))?;
+    let ptr = result_from_create(ctx_ptr, unsafe {
+        proj_create(ctx_ptr, c_definition.as_ptr())
+    })
+    .map_err(|e| ProjCreateError::ProjError(e.message(ctx_ptr)))?;
     Ok(Proj {
         c_proj: ptr,
         ctx,
@@ -221,23 +286,24 @@ fn transform_string(ctx: *mut PJ_CONTEXT, definition: &str) -> Result<Proj, Proj
 
 /// Called by new_known_crs and proj_known_crs
 fn transform_epsg(
-    ctx: *mut PJ_CONTEXT,
+    ctx: Context,
     from: &str,
     to: &str,
     area: Option<Area>,
 ) -> Result<Proj, ProjCreateError> {
+    let ctx_ptr = ctx.as_ptr();
     let from_c = CString::new(from).map_err(ProjCreateError::ArgumentNulError)?;
     let to_c = CString::new(to).map_err(ProjCreateError::ArgumentNulError)?;
     let proj_area = unsafe { proj_area_create() };
     area_set_bbox(proj_area, area);
-    let ptr = result_from_create(ctx, unsafe {
-        proj_create_crs_to_crs(ctx, from_c.as_ptr(), to_c.as_ptr(), proj_area)
+    let ptr = result_from_create(ctx_ptr, unsafe {
+        proj_create_crs_to_crs(ctx_ptr, from_c.as_ptr(), to_c.as_ptr(), proj_area)
     })
-    .map_err(|e| ProjCreateError::ProjError(e.message(ctx)))?;
+    .map_err(|e| ProjCreateError::ProjError(e.message(ctx_ptr)))?;
     // Normalise input and output order to Lon, Lat / Easting Northing by inserting
     // An axis swap operation if necessary
     let normalised = unsafe {
-        let normalised = proj_normalize_for_visualization(ctx, ptr);
+        let normalised = proj_normalize_for_visualization(ctx_ptr, ptr);
         // deallocate stale PJ pointer
         proj_destroy(ptr);
         normalised
@@ -251,12 +317,13 @@ fn transform_epsg(
 
 // called by Proj and ProjBuilder
 fn crs_to_crs_from_pj(
-    ctx: *mut PJ_CONTEXT,
+    ctx: Context,
     source_crs: &Proj,
     target_crs: &Proj,
     area: Option<Area>,
     options: Option<Vec<&str>>,
 ) -> Result<Proj, ProjCreateError> {
+    let ctx_ptr = ctx.as_ptr();
     let proj_area = unsafe { proj_area_create() };
     area_set_bbox(proj_area, area);
 
@@ -269,16 +336,16 @@ fn crs_to_crs_from_pj(
         }
     }
 
-    let ptr = result_from_create(ctx, unsafe {
+    let ptr = result_from_create(ctx_ptr, unsafe {
         proj_create_crs_to_crs_from_pj(
-            ctx,
+            ctx_ptr,
             source_crs.c_proj,
             target_crs.c_proj,
             proj_area,
             proj_options.as_ptr(),
         )
     })
-    .map_err(|e| ProjCreateError::ProjError(e.message(ctx)))?;
+    .map_err(|e| ProjCreateError::ProjError(e.message(ctx_ptr)))?;
 
     Ok(Proj {
         c_proj: ptr,
@@ -289,10 +356,6 @@ fn crs_to_crs_from_pj(
 
 macro_rules! define_info_methods {
     () => {
-        fn ctx(&self) -> *mut PJ_CONTEXT {
-            self.ctx
-        }
-
         /// Return information about the current instance of the PROJ libary.
         ///
         /// See: <https://proj.org/development/reference/datatypes.html#c.PJ_INFO>
@@ -338,6 +401,10 @@ macro_rules! define_info_methods {
 impl ProjBuilder {
     define_info_methods!();
 
+    fn ctx(&self) -> *mut PJ_CONTEXT {
+        self.ctx
+    }
+
     /// Enable or disable network access for [resource file download](https://proj.org/resource_files.html#where-are-proj-resource-files-looked-for).
     ///
     /// # Safety
@@ -460,7 +527,7 @@ impl ProjBuilder {
     /// This method contains unsafe code.
     pub fn proj(mut self, definition: &str) -> Result<Proj, ProjCreateError> {
         let ctx = unsafe { std::mem::replace(&mut self.ctx, proj_context_create()) };
-        transform_string(ctx, definition)
+        transform_string(Context::Owned(ctx), definition)
     }
 
     /// Try to create a transformation object that is a pipeline between two known coordinate reference systems.
@@ -507,7 +574,7 @@ impl ProjBuilder {
         area: Option<Area>,
     ) -> Result<Proj, ProjCreateError> {
         let ctx = unsafe { std::mem::replace(&mut self.ctx, proj_context_create()) };
-        transform_epsg(ctx, from, to, area)
+        transform_epsg(Context::Owned(ctx), from, to, area)
     }
     /// Builder version of [`create_crs_to_crs_from_pj()`](fn@Proj::create_crs_to_crs_from_pj())
     pub fn proj_create_crs_to_crs_from_pj(
@@ -518,7 +585,7 @@ impl ProjBuilder {
         options: Option<Vec<&str>>,
     ) -> Result<Proj, ProjCreateError> {
         let ctx = unsafe { std::mem::replace(&mut self.ctx, proj_context_create()) };
-        crs_to_crs_from_pj(ctx, source_crs, target_crs, area, options)
+        crs_to_crs_from_pj(Context::Owned(ctx), source_crs, target_crs, area, options)
     }
 }
 
@@ -553,10 +620,15 @@ impl Default for ProjBuilder {
 /// ```
 pub struct Proj {
     c_proj: *mut PJconsts,
-    ctx: *mut PJ_CONTEXT,
+    ctx: Context,
     area: Option<*mut PJ_AREA>,
 }
 
+// `Proj` is intentionally neither `Send` nor `Sync` (enforced by its raw pointers and the `Rc`
+// inside `Context`). A PROJ context must not be used concurrently from more than one thread, and
+// the shared per-thread context is reference counted with a non-atomic `Rc`. Do not add
+// `unsafe impl Send`/`Sync`: create a separate `Proj` per thread instead (as pyproj does).
+
 impl Proj {
     /// Create a coordinate metadata object to be used in coordinate operations.
     ///
@@ -580,7 +652,7 @@ impl Proj {
     /// This method contains unsafe code.
     pub fn coordinate_metadata_create(&self, epoch: f64) -> Result<Proj, ProjCreateError> {
         // Clone the context to avoid double-free in Drop implementations
-        let cloned_ctx = unsafe { proj_context_clone(self.ctx) };
+        let cloned_ctx = unsafe { proj_context_clone(self.ctx()) };
 
         let ptr = result_from_create(cloned_ctx, unsafe {
             proj_coordinate_metadata_create(cloned_ctx, self.c_proj, epoch)
@@ -589,7 +661,7 @@ impl Proj {
 
         Ok(Proj {
             c_proj: ptr,
-            ctx: cloned_ctx,
+            ctx: Context::Owned(cloned_ctx),
             area: None,
         })
     }
@@ -605,7 +677,7 @@ impl Proj {
     /// # Safety
     /// This method contains unsafe code.
     pub fn coordinate_metadata_get_epoch(&self) -> f64 {
-        unsafe { proj_coordinate_metadata_get_epoch(self.ctx, self.c_proj) }
+        unsafe { proj_coordinate_metadata_get_epoch(self.ctx(), self.c_proj) }
     }
 
     /// Try to create a new transformation object
@@ -646,7 +718,7 @@ impl Proj {
     // and vice versa, or using PJ_XY for conversion operations
     pub fn new(definition: &str) -> Result<Proj, ProjCreateError> {
         let ctx = unsafe { proj_context_create() };
-        transform_string(ctx, definition)
+        transform_string(Context::Owned(ctx), definition)
     }
 
     /// Try to create a new transformation object that is a pipeline between two known coordinate reference systems.
@@ -702,7 +774,7 @@ impl Proj {
         area: Option<Area>,
     ) -> Result<Proj, ProjCreateError> {
         let ctx = unsafe { proj_context_create() };
-        transform_epsg(ctx, from, to, area)
+        transform_epsg(Context::Owned(ctx), from, to, area)
     }
 
     /// Create a transformation object that is a pipeline _between_ two known coordinate reference systems.
@@ -756,8 +828,8 @@ impl Proj {
         options: Option<Vec<&str>>,
     ) -> Result<Proj, ProjCreateError> {
         // Clone the context to avoid double-free in Drop implementations
-        let ctx = unsafe { proj_context_clone(self.ctx) };
-        crs_to_crs_from_pj(ctx, self, target_crs, area, options)
+        let ctx = unsafe { proj_context_clone(self.ctx()) };
+        crs_to_crs_from_pj(Context::Owned(ctx), self, target_crs, area, options)
     }
 
     /// Set the bounding box of the area of use
@@ -786,6 +858,10 @@ impl Proj {
 
     define_info_methods!();
 
+    fn ctx(&self) -> *mut PJ_CONTEXT {
+        self.ctx.as_ptr()
+    }
+
     /// Returns the area of use of a projection
     ///
     /// When multiple usages are available, the first one will be returned.
@@ -801,7 +877,7 @@ impl Proj {
         let mut out_area_name = MaybeUninit::uninit();
         let res = unsafe {
             proj_get_area_of_use(
-                self.ctx,
+                self.ctx(),
                 self.c_proj,
                 out_west_lon_degree.as_mut_ptr(),
                 out_south_lat_degree.as_mut_ptr(),
@@ -1144,7 +1220,7 @@ impl Proj {
         unsafe {
             proj_errno_reset(self.c_proj);
             let _success = proj_trans_bounds(
-                self.ctx,
+                self.ctx(),
                 self.c_proj,
                 PJ_DIRECTION_PJ_FWD,
                 left.to_f64().ok_or(ProjError::FloatConversion)?,
@@ -1266,7 +1342,7 @@ impl Proj {
             proj_options.push(format!("SCHEMA={schema}"))?;
         }
         unsafe {
-            let out_ptr = proj_as_projjson(self.ctx, self.c_proj, proj_options.as_ptr());
+            let out_ptr = proj_as_projjson(self.ctx(), self.c_proj, proj_options.as_ptr());
             if out_ptr.is_null() {
                 Err(ProjError::ExportToJson)
             } else {
@@ -1339,7 +1415,7 @@ impl Proj {
         };
 
         unsafe {
-            let wkt = proj_as_wkt(self.ctx, self.c_proj, wkt_type, proj_options.as_ptr());
+            let wkt = proj_as_wkt(self.ctx(), self.c_proj, wkt_type, proj_options.as_ptr());
             Ok(_string(wkt)?)
         }
     }
@@ -1457,13 +1533,15 @@ impl Drop for Proj {
             if let Some(area) = self.area {
                 proj_area_destroy(area)
             }
+            // Destroy the PJ before the context: PROJ objects reference their creating context,
+            // so it must outlive them. `self.ctx` (a `Context`) is a field, so it is dropped
+            // after this explicit body runs, which destroys the context in the right order.
             proj_destroy(self.c_proj);
-            proj_context_destroy(self.ctx);
-            // We deliberately do not call proj_cleanup() here. It frees PROJ's
-            // process-global resources (the grid and +init file caches), so calling
-            // it whenever a single object is dropped clears caches that the next
-            // object would otherwise reuse, forcing reloads from disk. PROJ intends
-            // it to be called once before process termination, not per object.
+            // We deliberately do not call proj_cleanup() here. It frees PROJ's process-global
+            // resources (the grid and +init file caches), so calling it whenever a single object
+            // is dropped clears caches that the next object would otherwise reuse, forcing
+            // reloads from disk. PROJ intends it to be called once before process termination,
+            // not per object.
         }
     }
 }