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

gix_features/
threading.rs
