Add 'SpiceLock' example to README

Author: mclrc

rust-spice/README.md

@@ -78,6 +78,34 @@ spice::unload("hera/kernels/mk/hera_study_PO_EMA_2024.tm");
 
 You can look for some inspirations in the [core tests][core tests link].
 
+## Multi-threaded usage
+
+CSPICE itself contains massive amounts of shared mutable state and is thus not thread-safe - concurrent
+calls to any SPICE functions will almost always lead to crashes. To prevent this, if you need
+to call SPICE functions from multiple threads, this crate provides a thread-safe API with the `lock`
+feature. When enabled, the API is exposed in the form of associated functions on a guard singleton 
+`SpiceLock`, which is `!Sync + Send`. You can then only share this singleton and thus the methods it
+provides between threads using a `Mutex`, preventing concurrent API usage.
+
+The lock exposes the [neat][neat link] versions of functions where available, and the [raw][raw link] versions for the rest.
+For functions which have neither, you will have to use the unsafe (and unguarded) direct C bindings.
+Just make sure you have the lock before calling them.
+
+```rust
+use spice::SpiceLock;
+
+// `try_acquire` will return `Err` if a lock already exists
+let sl = SpiceLock::try_acquire().unwrap();
+
+// SPICE functions are now associated functions of the lock with a `&self` arg
+let mut kernel = sl.furnsh("hera/kernels/mk/hera_study_PO_EMA_2024.tm");
+
+let et = sl.str2et("2027-MAR-23 16:00:00");
+let (position, light_time) = sl.spkpos("DIMORPHOS", et, "J2000", "NONE", "SUN");
+
+sl.unload("hera/kernels/mk/hera_study_PO_EMA_2024.tm");
+```
+
 ## In development
 
 Developing an idiomatic interface for Spice in Rust takes time, and not all
@@ -163,6 +191,8 @@ Licensed under the [Apache License, Version 2.0][license link].
 [cspice install link]: https://naif.jpl.nasa.gov/naif/toolkit_C.html
 [cspice-sys link]: https://github.com/jacob-pro/cspice-rs/tree/master/cspice-sys
 [config doc]: https://doc.rust-lang.org/cargo/reference/config.html
+[raw link]: https://docs.rs/rust-spice/latest/spice/core/raw/index.html
+[neat link]: https://docs.rs/rust-spice/latest/spice/core/neat/index.html
 
 [s-rah url]: https://github.com/s-rah
 [PR 2]: https://github.com/GregoireHENRY/rust-spice/pull/2

rust-spice/tests/core/mod.rs

@@ -466,6 +466,29 @@ pub mod lock_tests {
     }
     #[test]
     #[serial]
+    fn spkezr() {
+        spice::furnsh("hera/kernels/mk/hera_study_PO_EMA_2024.tm");
+
+        // an arbitrary time
+        let et = spice::str2et("2021-01-06 09:36:09.1825432 TDB");
+
+        // sun in relation to ssb
+        let (sun_ssb_posvec, _sun_ssb_lt) = spice::spkezr("sun", et, "j2000", "none", "ssb");
+        // earth in relation to ssb
+        let (earth_ssb_posvec, _earth_ssb_lt) = spice::spkezr("earth", et, "j2000", "none", "ssb");
+        // earth in relation to sun
+        let (earth_sun_posvec, _earth_sun_ly) = spice::spkezr("earth", et, "j2000", "none", "sun");
+
+        // Quick check that the (Sun relative) earth velocity vectors are the same regardless of whether we
+        // calculate them indirectly from SB or directly compared to  the Sun
+        assert_eq!(earth_ssb_posvec[3] - sun_ssb_posvec[3], earth_sun_posvec[3]);
+        assert_eq!(earth_ssb_posvec[4] - sun_ssb_posvec[4], earth_sun_posvec[4]);
+        assert_eq!(earth_ssb_posvec[5] - sun_ssb_posvec[5], earth_sun_posvec[5]);
+
+        spice::unload("hera/kernels/mk/hera_study_PO_EMA_2024.tm");
+    }
+    #[test]
+    #[serial]
     fn multiple_threads() {
         use std::sync::{Arc, Mutex};
         use std::thread;
@@ -479,7 +502,7 @@ pub mod lock_tests {
         let mut children = Vec::with_capacity(n_children);
 
         for _ in 0..n_children {
-            let sl = Arc::clone(&sl);
+            let mut sl = Arc::clone(&sl);
             children.push(thread::spawn(move || {
                 for _ in 0..10 {
                     // If these calls were not guarded by the lock, they could lead to data races and UB