sdd/guard.rs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165
use super::collectible::DeferredClosure;
use super::collector::Collector;
use super::Epoch;
use std::panic::UnwindSafe;
/// [`Guard`] allows the user to read [`AtomicShared`](super::AtomicShared) and keeps the
/// underlying instance pinned to the thread.
///
/// [`Guard`] internally prevents the global epoch value from passing through the value
/// announced by the current thread, thus keeping reachable instances in the thread from being
/// garbage collected.
pub struct Guard {
collector_ptr: *mut Collector,
}
impl Guard {
/// Creates a new [`Guard`].
///
/// # Panics
///
/// The maximum number of [`Guard`] instances in a thread is limited to `u32::MAX`; a
/// thread panics when the number of [`Guard`] instances in the thread exceeds the limit.
///
/// # Examples
///
/// ```
/// use sdd::Guard;
///
/// let guard = Guard::new();
/// ```
#[inline]
#[must_use]
pub fn new() -> Self {
let collector_ptr = Collector::current();
unsafe {
Collector::new_guard(collector_ptr, true);
}
Self { collector_ptr }
}
/// Returns the epoch in which the current thread lives.
///
/// This method can be used to check whether a retired memory region is potentially reachable or
/// not. A chunk of memory retired in a witnessed [`Epoch`] can be deallocated after the thread
/// has observed three new epochs. For instance, if the witnessed epoch value is `1` in the
/// current thread where the global epoch value is `2`, and an instance is retired in the same
/// thread, the instance can be dropped when the thread witnesses `0` which is three epochs away
/// from `1`.
///
/// In other words, there can be potential readers of the memory chunk until the current thread
/// witnesses the previous epoch. In the above example, the global epoch can be in `2`
/// while the current thread has only witnessed `1`, and therefore there can a reader of the
/// memory chunk in another thread in epoch `2`. The reader can survive until the global epoch
/// reaches `0`, because the thread being in `2` prevents the global epoch from reaching `0`.
///
/// # Examples
///
/// ```
/// use sdd::{Guard, Owned};
/// use std::sync::atomic::AtomicBool;
/// use std::sync::atomic::Ordering::Relaxed;
///
/// static DROPPED: AtomicBool = AtomicBool::new(false);
///
/// struct D(&'static AtomicBool);
///
/// impl Drop for D {
/// fn drop(&mut self) {
/// self.0.store(true, Relaxed);
/// }
/// }
///
/// let owned = Owned::new(D(&DROPPED));
///
/// let epoch_before = Guard::new().epoch();
///
/// drop(owned);
/// assert!(!DROPPED.load(Relaxed));
///
/// while Guard::new().epoch() == epoch_before {
/// assert!(!DROPPED.load(Relaxed));
/// }
///
/// while Guard::new().epoch() == epoch_before.next() {
/// assert!(!DROPPED.load(Relaxed));
/// }
///
/// while Guard::new().epoch() == epoch_before.next().next() {
/// assert!(!DROPPED.load(Relaxed));
/// }
///
/// assert!(DROPPED.load(Relaxed));
/// assert_eq!(Guard::new().epoch(), epoch_before.prev());
/// ```
#[inline]
#[must_use]
pub fn epoch(&self) -> Epoch {
Collector::current_epoch()
}
/// Forces the [`Guard`] to try to start a new epoch when it is dropped.
///
/// # Examples
///
/// ```
/// use sdd::Guard;
///
/// let guard = Guard::new();
///
/// let epoch = guard.epoch();
/// guard.accelerate();
///
/// drop(guard);
///
/// assert_ne!(epoch, Guard::new().epoch());
/// ```
#[inline]
pub fn accelerate(&self) {
unsafe {
(*self.collector_ptr).accelerate();
}
}
/// Executes the supplied closure at a later point of time.
///
/// It is guaranteed that the closure will be executed after every [`Guard`] at the moment when
/// the method was invoked is dropped, however it is totally non-deterministic when exactly the
/// closure will be executed.
///
/// # Examples
///
/// ```
/// use sdd::Guard;
///
/// let guard = Guard::new();
/// guard.defer_execute(|| println!("deferred"));
/// ```
#[inline]
pub fn defer_execute<F: 'static + FnOnce()>(&self, f: F) {
unsafe {
Collector::collect(
self.collector_ptr,
Box::into_raw(Box::new(DeferredClosure::new(f))),
);
}
}
}
impl Default for Guard {
#[inline]
fn default() -> Self {
Self::new()
}
}
impl Drop for Guard {
#[inline]
fn drop(&mut self) {
unsafe {
Collector::end_guard(self.collector_ptr);
}
}
}
impl UnwindSafe for Guard {}