gix_features/
threading.rs

1//! Type definitions for putting shared ownership and synchronized mutation behind the `threading` feature toggle.
2//!
3//! That way, single-threaded applications will not have to use thread-safe primitives, and simply do not specify the 'threading' feature.
4
5#[cfg(feature = "parallel")]
6mod _impl {
7    use std::sync::Arc;
8
9    /// A thread-safe cell which can be written to only once.
10    ///
11    /// Note: We use `once_cell` here because `std::sync::OnceLock::get_or_try_init()` is not yet stable.
12    /// Once it's stabilized, we can switch to `std::sync::OnceLock`.
13    #[cfg(feature = "once_cell")]
14    pub type OnceCell<T> = once_cell::sync::OnceCell<T>;
15    /// A reference counted pointer type for shared ownership.
16    pub type OwnShared<T> = Arc<T>;
17    /// A synchronization primitive which can start read-only and transition to support mutation.
18    pub type MutableOnDemand<T> = parking_lot::RwLock<T>;
19    /// A synchronization primitive which provides read-write access right away.
20    pub type Mutable<T> = parking_lot::Mutex<T>;
21    /// A guarded reference suitable for safekeeping in a struct.
22    pub type RefGuard<'a, T> = parking_lot::RwLockReadGuard<'a, T>;
23    /// A mapped reference created from a `RefGuard`
24    pub type MappedRefGuard<'a, U> = parking_lot::MappedRwLockReadGuard<'a, U>;
25
26    /// Get a shared reference through a [`MutableOnDemand`] for read-only access.
27    pub fn get_ref<T>(v: &MutableOnDemand<T>) -> RefGuard<'_, T> {
28        v.read()
29    }
30
31    /// Get a mutable reference through a [`MutableOnDemand`] for read-write access.
32    pub fn get_mut<T>(v: &MutableOnDemand<T>) -> parking_lot::RwLockWriteGuard<'_, T> {
33        v.write()
34    }
35
36    /// Get a mutable reference to the underlying data, with semantics similar to [Arc::make_mut()].
37    pub fn make_mut<T: Clone>(this: &mut OwnShared<T>) -> &mut T {
38        OwnShared::make_mut(this)
39    }
40
41    /// Get a mutable reference through a [`Mutable`] for read-write access.
42    pub fn lock<T>(v: &Mutable<T>) -> parking_lot::MutexGuard<'_, T> {
43        v.lock()
44    }
45
46    /// Downgrade a handle previously obtained with [`get_mut()`] to drop mutation support.
47    pub fn downgrade_mut_to_ref<'a, T>(
48        v: parking_lot::RwLockWriteGuard<'a, T>,
49        _orig: &'a MutableOnDemand<T>,
50    ) -> RefGuard<'a, T> {
51        parking_lot::RwLockWriteGuard::downgrade(v)
52    }
53
54    /// Map a read guard into a sub-type it contains.
55    pub fn map_ref<T, U: ?Sized>(v: RefGuard<'_, T>, f: impl FnOnce(&T) -> &U) -> MappedRefGuard<'_, U> {
56        parking_lot::RwLockReadGuard::map(v, f)
57    }
58}
59
60#[cfg(not(feature = "parallel"))]
61mod _impl {
62    use std::{
63        cell::{Ref, RefCell, RefMut},
64        rc::Rc,
65    };
66
67    /// A thread-safe cell which can be written to only once.
68    ///
69    /// Note: We use `once_cell` here because `std::cell::OnceCell::get_or_try_init()` is not yet stable.
70    /// Once it's stabilized, we can switch to `std::cell::OnceCell`.
71    #[cfg(feature = "once_cell")]
72    pub type OnceCell<T> = once_cell::unsync::OnceCell<T>;
73    /// A reference counted pointer type for shared ownership.
74    pub type OwnShared<T> = Rc<T>;
75    /// A synchronization primitive which can start read-only and transition to support mutation.
76    pub type MutableOnDemand<T> = RefCell<T>;
77    /// A synchronization primitive which provides read-write access right away.
78    pub type Mutable<T> = RefCell<T>;
79    /// A guarded reference suitable for safekeeping in a struct.
80    pub type RefGuard<'a, T> = Ref<'a, T>;
81    /// A mapped reference created from a RefGuard
82    pub type MappedRefGuard<'a, U> = Ref<'a, U>;
83
84    /// Get a shared reference through a [`MutableOnDemand`] for read-only access.
85    pub fn get_mut<T>(v: &RefCell<T>) -> RefMut<'_, T> {
86        v.borrow_mut()
87    }
88
89    /// Get a mutable reference to the underlying data, with semantics similar to [Rc::make_mut()].
90    pub fn make_mut<T: Clone>(this: &mut OwnShared<T>) -> &mut T {
91        OwnShared::make_mut(this)
92    }
93
94    /// Get a mutable reference through a [`Mutable`] for read-write access.
95    pub fn lock<T>(v: &Mutable<T>) -> RefMut<'_, T> {
96        v.borrow_mut()
97    }
98
99    /// Get a mutable reference through a [`MutableOnDemand`] for read-write access.
100    pub fn get_ref<T>(v: &RefCell<T>) -> RefGuard<'_, T> {
101        v.borrow()
102    }
103
104    /// Downgrade a handle previously obtained with [`upgrade_ref_to_mut()`] to drop mutation support.
105    pub fn downgrade_mut_to_ref<'a, T>(v: RefMut<'a, T>, orig: &'a RefCell<T>) -> RefGuard<'a, T> {
106        drop(v);
107        orig.borrow()
108    }
109
110    /// Map a read guard into a sub-type it contains.
111    pub fn map_ref<T, U: ?Sized>(v: RefGuard<'_, T>, f: impl FnOnce(&T) -> &U) -> MappedRefGuard<'_, U> {
112        Ref::map(v, f)
113    }
114}
115
116pub use _impl::*;
gix_features/threading.rs

gix_features/
threading.rs
