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
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
use super::collectible::DeferredClosure;
use super::collector::Collector;
use super::{Collectible, 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_ptr).new_guard(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 of a [`Collectible`]
/// type 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` again, 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()
}
/// Defers dropping and memory reclamation of the supplied [`Box`] of a type implementing
/// [`Collectible`].
///
/// # Examples
///
/// ```
/// use sdd::{Guard, Collectible};
/// use std::ptr::NonNull;
///
/// struct C(usize, Option<NonNull<dyn Collectible>>);
///
/// impl Collectible for C {
/// fn next_ptr_mut(&mut self) -> &mut Option<NonNull<dyn Collectible>> {
/// &mut self.1
/// }
/// }
///
/// let boxed: Box<C> = Box::new(C(7, None));
///
/// let static_ref: &'static C = unsafe { std::mem::transmute(&*boxed) };
///
/// let guard = Guard::new();
/// guard.defer(boxed);
///
/// assert_eq!(static_ref.0, 7);
/// ```
#[inline]
pub fn defer(&self, collectible: Box<dyn Collectible>) {
self.collect(Box::into_raw(collectible));
}
/// 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) {
self.defer(Box::new(DeferredClosure::new(f)));
}
/// Creates a new [`Guard`] for dropping an instance in the supplied [`Collector`].
#[inline]
pub(super) fn new_for_drop(collector_ptr: *mut Collector) -> Self {
unsafe {
(*collector_ptr).new_guard(false);
}
Self { collector_ptr }
}
/// Reclaims the supplied instance.
#[inline]
pub(super) fn collect(&self, collectible: *mut dyn Collectible) {
unsafe {
(*self.collector_ptr).reclaim(collectible);
}
}
}
impl Default for Guard {
#[inline]
fn default() -> Self {
Self::new()
}
}
impl Drop for Guard {
#[inline]
fn drop(&mut self) {
unsafe {
(*self.collector_ptr).end_guard();
}
}
}
impl UnwindSafe for Guard {}