rune/runtime/
access.rs

Help
1use core::cell::Cell;
2use core::fmt;
3use core::mem::ManuallyDrop;
4use core::ptr::NonNull;
5
6use super::TypeInfo;
7
8/// Test if exclusively held.
9const EXCLUSIVE: usize = 1usize.rotate_right(2);
10/// Sentinel value to indicate that access is taken.
11const MOVED: usize = 1usize.rotate_right(1);
12/// Mask indicating if the value is exclusively set or moved.
13const MASK: usize = EXCLUSIVE | MOVED;
14
15/// An error raised when failing to access a value.
16///
17/// Access errors can be raised for various reasons, such as:
18/// * The value you are trying to access is an empty placeholder.
19/// * The value is already being accessed in an incompatible way, such as trying
20///   to access a value exclusively twice.
21/// * The value has been taken and is no longer present.
22#[derive(Debug)]
23#[cfg_attr(test, derive(PartialEq))]
24#[non_exhaustive]
25pub struct AccessError {
26    kind: AccessErrorKind,
27}
28
29impl AccessError {
30    #[inline]
31    pub(crate) const fn not_owned(type_info: TypeInfo) -> Self {
32        Self {
33            kind: AccessErrorKind::NotAccessibleOwned(type_info),
34        }
35    }
36
37    #[inline]
38    pub(crate) const fn new(kind: AccessErrorKind) -> Self {
39        Self { kind }
40    }
41}
42
43impl fmt::Display for AccessError {
44    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
45        match &self.kind {
46            AccessErrorKind::NotAccessibleRef(s) => write!(f, "Cannot read, value is {s}"),
47            AccessErrorKind::NotAccessibleMut(s) => write!(f, "Cannot write, value is {s}"),
48            AccessErrorKind::NotAccessibleTake(s) => write!(f, "Cannot take, value is {s}"),
49            AccessErrorKind::NotAccessibleOwned(type_info) => {
50                write!(f, "Cannot use owned operations for {type_info}")
51            }
52        }
53    }
54}
55
56impl core::error::Error for AccessError {}
57
58impl From<AccessErrorKind> for AccessError {
59    #[inline]
60    fn from(kind: AccessErrorKind) -> Self {
61        AccessError::new(kind)
62    }
63}
64
65#[derive(Debug)]
66#[cfg_attr(test, derive(PartialEq))]
67pub(crate) enum AccessErrorKind {
68    NotAccessibleRef(Snapshot),
69    NotAccessibleMut(Snapshot),
70    NotAccessibleTake(Snapshot),
71    NotAccessibleOwned(TypeInfo),
72}
73
74/// Snapshot that can be used to indicate how the value was being accessed at
75/// the time of an error.
76#[derive(PartialEq)]
77#[repr(transparent)]
78pub(crate) struct Snapshot(usize);
79
80impl Snapshot {
81    /// Test if the snapshot indicates that the value is readable.
82    pub(crate) fn is_readable(&self) -> bool {
83        self.0 & MASK == 0
84    }
85
86    /// Test if the snapshot indicates that the value is writable.
87    pub(crate) fn is_writable(&self) -> bool {
88        self.0 & MASK == 0
89    }
90
91    /// Test if access is exclusively held.
92    pub(crate) fn is_exclusive(&self) -> bool {
93        self.0 & MASK != 0
94    }
95
96    /// The number of times a value is shared.
97    pub(crate) fn shared(&self) -> usize {
98        self.0 & !MASK
99    }
100}
101
102impl fmt::Display for Snapshot {
103    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
104        if self.0 & MOVED != 0 {
105            write!(f, "M")?;
106        } else {
107            write!(f, "-")?;
108        }
109
110        if self.0 & EXCLUSIVE != 0 {
111            write!(f, "X")?;
112        } else {
113            write!(f, "-")?;
114        }
115
116        write!(f, "{:06}", self.shared())?;
117        Ok(())
118    }
119}
120
121impl fmt::Debug for Snapshot {
122    #[inline]
123    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
124        write!(f, "Snapshot({self})")
125    }
126}
127
128/// Access flags.
129///
130/// These accomplish the following things:
131/// * Indicates if a value is exclusively held.
132/// * Indicates if a value is taken .
133/// * Indicates if a value is shared, and if so by how many.
134#[repr(transparent)]
135pub(crate) struct Access(Cell<usize>);
136
137impl Access {
138    /// Construct a new default access.
139    pub(crate) const fn new() -> Self {
140        Self(Cell::new(0))
141    }
142
143    /// Test if we can have shared access without modifying the internal count.
144    #[inline(always)]
145    pub(crate) fn is_shared(&self) -> bool {
146        self.0.get() & MASK == 0
147    }
148
149    /// Test if we can have exclusive access without modifying the internal
150    /// count.
151    #[inline(always)]
152    pub(crate) fn is_exclusive(&self) -> bool {
153        self.0.get() == 0
154    }
155
156    /// Test if the data has been taken.
157    #[inline(always)]
158    pub(crate) fn is_taken(&self) -> bool {
159        self.0.get() & MOVED != 0
160    }
161
162    /// Mark that we want shared access to the given access token.
163    pub(crate) fn shared(&self) -> Result<AccessGuard<'_>, AccessError> {
164        self.try_shared()?;
165        Ok(AccessGuard(self))
166    }
167
168    #[inline(always)]
169    pub(crate) fn try_shared(&self) -> Result<(), AccessError> {
170        let state = self.0.get();
171
172        if state & MASK != 0 {
173            debug_assert_eq!(
174                state & !MASK,
175                0,
176                "count should be zero, but was {}",
177                Snapshot(state)
178            );
179            return Err(AccessError::new(AccessErrorKind::NotAccessibleRef(
180                Snapshot(state),
181            )));
182        }
183
184        // NB: Max number of shared.
185        if state == !MASK {
186            crate::alloc::abort();
187        }
188
189        self.0.set(state + 1);
190        Ok(())
191    }
192
193    /// Mark that we want exclusive access to the given access token.
194    #[inline(always)]
195    pub(crate) fn exclusive(&self) -> Result<AccessGuard<'_>, AccessError> {
196        self.try_exclusive()?;
197        Ok(AccessGuard(self))
198    }
199
200    #[inline(always)]
201    pub(crate) fn try_exclusive(&self) -> Result<(), AccessError> {
202        let state = self.0.get();
203
204        if state != 0 {
205            return Err(AccessError::new(AccessErrorKind::NotAccessibleMut(
206                Snapshot(state),
207            )));
208        }
209
210        self.0.set(state | EXCLUSIVE);
211        Ok(())
212    }
213
214    /// Mark that we want to mark the given access as "taken".
215    ///
216    /// I.e. whatever guarded data is no longer available.
217    #[inline(always)]
218    pub(crate) fn try_take(&self) -> Result<(), AccessError> {
219        let state = self.0.get();
220
221        if state != 0 {
222            return Err(AccessError::new(AccessErrorKind::NotAccessibleTake(
223                Snapshot(state),
224            )));
225        }
226
227        self.0.set(state | MOVED);
228        Ok(())
229    }
230
231    /// Unconditionally mark the given access as "taken".
232    #[inline(always)]
233    pub(crate) fn take(&self) {
234        let state = self.0.get();
235        self.0.set(state | MOVED);
236    }
237
238    /// Release the current access, unless it's moved.
239    #[inline(always)]
240    pub(super) fn release(&self) {
241        let b = self.0.get();
242
243        let b = if b & EXCLUSIVE != 0 {
244            b & !EXCLUSIVE
245        } else {
246            debug_assert_ne!(b & !MASK, 0, "count should be zero but was {}", Snapshot(b));
247            b - 1
248        };
249
250        self.0.set(b);
251    }
252
253    /// Get a snapshot of current access.
254    #[inline(always)]
255    pub(super) fn snapshot(&self) -> Snapshot {
256        Snapshot(self.0.get())
257    }
258}
259
260impl fmt::Debug for Access {
261    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
262        write!(f, "{}", Snapshot(self.0.get()))
263    }
264}
265
266/// A guard around some specific access access.
267#[repr(transparent)]
268pub(crate) struct AccessGuard<'a>(&'a Access);
269
270impl AccessGuard<'_> {
271    /// Convert into a raw guard which does not have a lifetime associated with
272    /// it. Droping the raw guard will release the resource.
273    ///
274    /// # Safety
275    ///
276    /// Since we're losing track of the lifetime, caller must ensure that the
277    /// access outlives the guard.
278    pub(crate) unsafe fn into_raw(self) -> RawAccessGuard {
279        RawAccessGuard(NonNull::from(ManuallyDrop::new(self).0))
280    }
281}
282
283impl Drop for AccessGuard<'_> {
284    fn drop(&mut self) {
285        self.0.release();
286    }
287}
288
289/// A raw guard around some level of access which will be released once the guard is dropped.
290#[repr(transparent)]
291pub(crate) struct RawAccessGuard(NonNull<Access>);
292
293impl Drop for RawAccessGuard {
294    fn drop(&mut self) {
295        unsafe { self.0.as_ref().release() }
296    }
297}
rune/runtime/access.rs

rune/runtime/
access.rs
