Reuse a per-thread context in Proj::new/new_known_crs

Proj::new and Proj::new_known_crs now borrow the per-thread shared context
instead of creating (and destroying) a fresh PROJ context each call, mirroring
pyproj's one-context-per-thread model. This drops Proj::new to
~1us per instance. ProjBuilder and the clone-based constructors continue to own
their own contexts.

Adds tests for per-thread reuse, per-thread isolation, ProjBuilder context
independence, and that dropping a Proj does not free the shared context.


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

Author: urschrei

CHANGES.md

@@ -8,6 +8,9 @@
   the lifetime of the process, substantially speeding up repeated creation of
   transformation objects (https://github.com/georust/proj/issues/256).
 - Add Proj::equivalent_to() method to assess whether two Proj instances are the same
+- `Proj::new` and `Proj::new_known_crs` now reuse one PROJ context per thread
+  instead of creating a new one per call, reducing construction time from
+  ~300us to ~1us per object (https://github.com/georust/proj/issues/256).
 - Refactored options logic
 
 # 0.31.0 - 2025-08-29

src/context.rs

@@ -54,8 +54,6 @@ impl Drop for Context {
 /// exit.
 pub(crate) enum ProjContext {
     Owned(Context),
-    // Wired into Proj::new/new_known_crs in a follow-up commit.
-    #[allow(dead_code)]
     Shared(Rc<Context>),
 }
 
@@ -89,7 +87,6 @@ thread_local! {
 }
 
 /// 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
 pub(crate) fn thread_local_context() -> ProjContext {
     ProjContext::Shared(SHARED_CONTEXT.with(Rc::clone))
 }

src/lib.rs

@@ -150,6 +150,18 @@
 //! resources actually loaded and so do not grow without bound: the cost is memory residency for
 //! the lifetime of the process, not additional disk usage.
 //!
+//! ## Threading
+//!
+//! Each PROJ context (`PJ_CONTEXT`) is tied to a single thread and must not be used concurrently
+//! from more than one thread. `Proj` is therefore deliberately neither `Send` nor `Sync`; to
+//! transform coordinates on several threads, create a `Proj` on each thread.
+//!
+//! [`Proj::new`] and [`Proj::new_known_crs`] reuse one context per thread rather than creating a
+//! new one for every object. This keeps the connection to the PROJ database and its caches warm,
+//! so constructing many transformation objects on a thread is considerably cheaper than it would
+//! otherwise be. [`ProjBuilder`] keeps its own context, since it is used to configure
+//! context-specific state such as network access and search paths.
+//!
 //! ## Conform your own types
 //!
 //! If you have your own geometric types, you can conform them to the `Coord` trait and use `proj`

src/proj.rs

@@ -23,7 +23,7 @@ use std::{
     str,
 };
 
-use crate::context::{Context, ProjContext};
+use crate::context::{Context, ProjContext, thread_local_context};
 use crate::cstring_array::CStringArray;
 
 #[cfg(feature = "network")]
@@ -673,7 +673,7 @@ impl Proj {
     // PJ_LP signals projection of geodetic coordinates, with output being PJ_XY
     // and vice versa, or using PJ_XY for conversion operations
     pub fn new(definition: &str) -> Result<Proj, ProjCreateError> {
-        ProjContext::Owned(Context::new()).transform_string(definition)
+        thread_local_context().transform_string(definition)
     }
 
     /// Try to create a new transformation object that is a pipeline between two known coordinate reference systems.
@@ -728,7 +728,7 @@ impl Proj {
         to: &str,
         area: Option<Area>,
     ) -> Result<Proj, ProjCreateError> {
-        ProjContext::Owned(Context::new()).transform_epsg(from, to, area)
+        thread_local_context().transform_epsg(from, to, area)
     }
 
     /// Create a transformation object that is a pipeline _between_ two known coordinate reference systems.
@@ -1655,6 +1655,81 @@ mod test {
         let proj = Proj::new(wgs84).unwrap();
         let np = proj.coordinate_metadata_create(epoch).unwrap();
         assert_eq!(np.coordinate_metadata_get_epoch(), 2021.3);
+        // The metadata object clones the context, so it owns a distinct one rather than
+        // borrowing the shared per-thread context.
+        assert_ne!(np.ctx() as usize, proj.ctx() as usize);
+    }
+
+    #[test]
+    fn test_new_reuses_thread_context() {
+        // Every Proj::new on a thread borrows the same per-thread context.
+        let a = Proj::new("EPSG:4326").unwrap();
+        let b = Proj::new_known_crs("EPSG:4326", "EPSG:3857", None).unwrap();
+        assert_eq!(a.ctx(), b.ctx());
+    }
+
+    #[test]
+    fn test_each_thread_gets_its_own_context() {
+        // The shared context is per-thread: each thread must get a distinct context. A barrier
+        // keeps every context alive simultaneously while addresses are captured, so a freed
+        // context's address cannot be reused by another thread and falsely collide.
+        use std::sync::{Arc, Barrier};
+
+        let threads = 4;
+        let barrier = Arc::new(Barrier::new(threads + 1));
+        let main = Proj::new("EPSG:4326").unwrap();
+
+        let handles: Vec<_> = (0..threads)
+            .map(|_| {
+                let barrier = Arc::clone(&barrier);
+                // Send the context address (usize), not the !Send Proj itself.
+                std::thread::spawn(move || {
+                    let proj = Proj::new("EPSG:4326").unwrap();
+                    let addr = proj.ctx() as usize;
+                    barrier.wait();
+                    drop(proj);
+                    addr
+                })
+            })
+            .collect();
+
+        barrier.wait();
+        let mut seen = vec![main.ctx() as usize];
+        for handle in handles {
+            seen.push(handle.join().unwrap());
+        }
+
+        let total = seen.len();
+        seen.sort_unstable();
+        seen.dedup();
+        assert_eq!(
+            seen.len(),
+            total,
+            "each thread should get a distinct context"
+        );
+    }
+
+    #[test]
+    fn test_builder_context_is_not_shared() {
+        // ProjBuilder owns its context (it mutates context state), so it must not borrow the
+        // shared per-thread context.
+        let shared = Proj::new("EPSG:4326").unwrap().ctx() as usize;
+        let built = ProjBuilder::new().proj("EPSG:4326").unwrap();
+        assert_ne!(built.ctx() as usize, shared);
+    }
+
+    #[test]
+    fn test_drop_does_not_free_shared_context() {
+        // Dropping a Proj must not destroy the shared context other Proj instances still use.
+        // Under AddressSanitizer this would surface as a use-after-free if the invariant broke.
+        let first = Proj::new("EPSG:4326").unwrap().ctx() as usize;
+        for _ in 0..1000 {
+            let _ = Proj::new("EPSG:4326").unwrap();
+        }
+        let transformer = Proj::new_known_crs("EPSG:4326", "EPSG:3857", None).unwrap();
+        assert_eq!(transformer.ctx() as usize, first);
+        // The shared context is still valid and usable.
+        transformer.convert((2.0, 49.0)).unwrap();
     }
 
     #[test]
@@ -1669,6 +1744,8 @@ mod test {
 
         assert_relative_eq!(result.x(), 1450880.2910605022, epsilon = 1.0e-8);
         assert_relative_eq!(result.y(), 1141263.0111604782, epsilon = 1.0e-8);
+        // The transformer clones the source context, so it owns a distinct one.
+        assert_ne!(transformer.ctx() as usize, from.ctx() as usize);
     }
 
     #[test]