feat: Make a scope-like abstraction available (#293)

This allows more delicate threading control like is required for the
index.

Author: Byron

git-features/src/parallel/in_parallel.rs

@@ -10,6 +10,17 @@ pub fn join<O1: Send, O2: Send>(left: impl FnOnce() -> O1 + Send, right: impl Fn
     .unwrap()
 }
 
+/// Runs `f` with a scope to be used for spawning threads that will not outlive the function call.
+/// That way it's possible to handle threads without needing the 'static lifetime for data they interact with.
+///
+/// Note that the threads should not rely on actual parallelism as threading might be turned off entirely.
+pub fn threads<'env, F, R>(f: F) -> std::thread::Result<R>
+where
+    F: FnOnce(&crossbeam_utils::thread::Scope<'env>) -> R,
+{
+    crossbeam_utils::thread::scope(f)
+}
+
 /// Read items from `input` and `consume` them in multiple threads,
 /// whose output output is collected by a `reducer`. Its task is to
 /// aggregate these outputs into the final result returned by this function with the benefit of not having to be thread-safe.

git-features/src/parallel/mod.rs

@@ -35,11 +35,11 @@
 #[cfg(feature = "parallel")]
 mod in_parallel;
 #[cfg(feature = "parallel")]
-pub use in_parallel::{in_parallel, join};
+pub use in_parallel::{in_parallel, join, threads};
 
 mod serial;
 #[cfg(not(feature = "parallel"))]
-pub use serial::{in_parallel, join};
+pub use serial::{in_parallel, join, threads};
 
 mod eager_iter;
 pub use eager_iter::{EagerIter, EagerIterIf};

git-features/src/parallel/serial.rs

@@ -1,10 +1,63 @@
 use crate::parallel::Reduce;
 
-/// Runs `left` and then `right`, one after another, returning their output when both are done.
 #[cfg(not(feature = "parallel"))]
-pub fn join<O1, O2>(left: impl FnOnce() -> O1, right: impl FnOnce() -> O2) -> (O1, O2) {
-    (left(), right())
+mod not_parallel {
+    /// Runs `left` and then `right`, one after another, returning their output when both are done.
+    pub fn join<O1, O2>(left: impl FnOnce() -> O1, right: impl FnOnce() -> O2) -> (O1, O2) {
+        (left(), right())
+    }
+
+    /// A scope for spawning threads.
+    pub struct Scope<'env> {
+        _marker: std::marker::PhantomData<&'env mut &'env ()>,
+    }
+
+    #[allow(unsafe_code)]
+    unsafe impl Sync for Scope<'_> {}
+
+    impl<'env> Scope<'env> {
+        pub fn spawn<'scope, F, T>(&'scope self, f: F) -> ScopedJoinHandle<'scope, T>
+        where
+            F: FnOnce(&Scope<'env>) -> T,
+            F: Send + 'env,
+            T: Send + 'env,
+        {
+            ScopedJoinHandle {
+                result: f(self),
+                _marker: Default::default(),
+            }
+        }
+    }
+
+    /// Runs `f` with a scope to be used for spawning threads that will not outlive the function call.
+    /// Note that this implementation will run the spawned functions immediately.
+    pub fn threads<'env, F, R>(f: F) -> std::thread::Result<R>
+    where
+        F: FnOnce(&Scope<'env>) -> R,
+    {
+        Ok(f(&Scope {
+            _marker: Default::default(),
+        }))
+    }
+
+    /// A handle that can be used to join its scoped thread.
+    ///
+    /// This struct is created by the [`Scope::spawn`] method and the
+    /// [`ScopedThreadBuilder::spawn`] method.
+    pub struct ScopedJoinHandle<'scope, T> {
+        /// Holds the result of the inner closure.
+        result: T,
+        _marker: std::marker::PhantomData<&'scope mut &'scope ()>,
+    }
+
+    impl<T> ScopedJoinHandle<'_, T> {
+        pub fn join(self) -> std::thread::Result<T> {
+            Ok(self.result)
+        }
+    }
 }
+#[cfg(not(feature = "parallel"))]
+pub use not_parallel::{join, threads, Scope, ScopedJoinHandle};
 
 /// Read items from `input` and `consume` them in a single thread, producing an output to be collected by a `reducer`,
 /// whose task is to aggregate these outputs into the final result returned by this function.