token_cell/
core.rs

1use ::core::{
2    cell::UnsafeCell,
3    ops::{Deref, DerefMut},
4};
5
6trait MapLikely<T> {
7    type Output<U>;
8    fn map_likely<U, F: FnOnce(T) -> U>(self, f: F) -> Self::Output<U>;
9}
10#[cold]
11const fn cold() {}
12impl<T, E> MapLikely<T> for Result<T, E> {
13    type Output<U> = Result<U, E>;
14    fn map_likely<U, F: FnOnce(T) -> U>(self, f: F) -> Self::Output<U> {
15        match self {
16            Ok(v) => Ok(f(v)),
17            Err(e) => {
18                cold();
19                Err(e)
20            }
21        }
22    }
23}
24
25use crate::monads::{TokenMap, TokenMapMut};
26/// A trait for tokens
27pub trait TokenTrait: Sized {
28    /// Constructing a token may fail.
29    type ConstructionError;
30    /// [`TokenTrait::with_token`] may fail, typically if construction failed.
31    ///
32    /// Some types, like [`GhostToken`](crate::ghost::GhostToken) are inconstructible with [`TokenTrait::new`], but cannot fail to run, hence the distinction.
33    type RunError;
34    /// Lets a [`TokenCell`] keep track of the token.
35    ///
36    /// In most cases, this is a ZST in release mode.
37    type Identifier;
38    /// [`core::convert::Infallible`] unless [`TokenTrait::compare`] is fallible (ie. comparison is done at runtime).
39    type ComparisonError;
40    /// Rebrands the token, this is necessary for [`GhostToken`](crate::ghost::GhostToken) to function properly
41    type Branded<'a>;
42    /// Constructs a new Token.
43    ///
44    /// # Errors
45    /// Some token implementations may chose to be constructible only once, or only while holding a given lock.
46    fn new() -> Result<Self, Self::ConstructionError>;
47    /// Constructs a new, lifetime-branded Token, and provides it to the closure.
48    ///
49    /// This is especially useful for [`GhostToken`](crate::ghost::GhostToken), which can only be constructed that way, as they use lifetimes to obtain a unique brand.
50    ///
51    /// # Errors
52    /// If construction failed, so will this.
53    fn with_token<R, F: for<'a> FnOnce(Self::Branded<'a>) -> R>(f: F) -> Result<R, Self::RunError>;
54    /// Returns the Token's identifier, which cells may store to allow comparison.
55    fn identifier(&self) -> Self::Identifier;
56    /// Allows the cell to compare its identifier to the Token.
57    ///
58    /// # Errors
59    /// If a wrong token was mistakenly passed to the cell.
60    fn compare(&self, id: &Self::Identifier) -> Result<(), Self::ComparisonError>;
61}
62
63/// Common ways to interract with a [`TokenCell`].
64///
65/// Note that while many functions document fallihle behaviours, this behaviour is only reachable for tokens that perform runtime check. These are identifiable by their [`TokenTrait::ComparisonError`] type not being [`core::convert::Infallible`].
66pub trait TokenCellTrait<T: ?Sized, Token: TokenTrait>: Sync {
67    /// Constructs a new cell using `token` as its key.
68    fn new(inner: T, token: &Token) -> Self
69    where
70        T: Sized;
71    /// Attempts to construct a guard which [`Deref`]s to the inner data,
72    /// but also allows recovering the `Token`.
73    ///
74    /// # Errors
75    /// If the token provides runtime checking and detects that `self` was constructed with another token.
76    fn try_guard<'l>(
77        &'l self,
78        token: &'l Token,
79    ) -> Result<TokenGuard<'l, T, Token>, Token::ComparisonError>;
80    /// Attempts to borrow the inner data.
81    ///
82    /// # Errors
83    /// If the token provides runtime checking and detects that `self` was constructed with another token.
84    fn try_borrow<'l>(&'l self, token: &'l Token) -> Result<&'l T, Token::ComparisonError>;
85    /// Attempts to construct a guard which [`DerefMut`]s to the inner data,
86    /// but also allows recovering the `Token`.
87    ///
88    /// # Errors
89    /// If the token provides runtime checking and detects that `self` was constructed with another token.
90    fn try_guard_mut<'l>(
91        &'l self,
92        token: &'l mut Token,
93    ) -> Result<TokenGuardMut<'l, T, Token>, Token::ComparisonError>;
94    /// Attempts to borrow the inner data mutably.
95    ///
96    /// # Errors
97    /// If the token provides runtime checking and detects that `self` was constructed with another token.
98    fn try_borrow_mut<'l>(
99        &'l self,
100        token: &'l mut Token,
101    ) -> Result<&'l mut T, Token::ComparisonError>;
102    /// Borrows the inner data, panicking if the wrong token was used as key.
103    fn borrow<'l>(&'l self, token: &'l Token) -> &'l T
104    where
105        Token::ComparisonError: core::fmt::Debug,
106    {
107        self.try_borrow(token).unwrap()
108    }
109    /// Borrows the inner data mutably, panicking if the wrong token was used as key.
110    fn borrow_mut<'l>(&'l self, token: &'l mut Token) -> &'l mut T
111    where
112        Token::ComparisonError: core::fmt::Debug,
113    {
114        self.try_borrow_mut(token).unwrap()
115    }
116    /// Constructs a lazy computation that can then be applied using the token.
117    fn map<'a, U, F: FnOnce(TokenGuard<'a, T, Token>) -> U>(
118        &'a self,
119        f: F,
120    ) -> TokenMap<'a, T, U, F, Self, Token> {
121        TokenMap {
122            cell: self,
123            f,
124            marker: core::marker::PhantomData,
125        }
126    }
127    /// Constructs a lazy computation that can then be applied using the token.
128    fn map_mut<'a, U, F: FnOnce(TokenGuardMut<'a, T, Token>) -> U>(
129        &'a self,
130        f: F,
131    ) -> TokenMapMut<'a, T, U, F, Self, Token> {
132        TokenMapMut {
133            cell: self,
134            f,
135            marker: core::marker::PhantomData,
136        }
137    }
138}
139
140/// A guard that allows immutably borrowing the cell's value, as well as its token.
141pub struct TokenGuard<'a, T: ?Sized, Token: TokenTrait> {
142    cell: &'a TokenCell<T, Token>,
143    token: &'a Token,
144}
145impl<'a, T: ?Sized, Token: TokenTrait> TokenGuard<'a, T, Token> {
146    /// Reborrows the token immutably.
147    pub const fn token(&self) -> &Token {
148        self.token
149    }
150}
151impl<'a, T: ?Sized, Token: TokenTrait> Deref for TokenGuard<'a, T, Token> {
152    type Target = T;
153    fn deref(&self) -> &Self::Target {
154        unsafe { &*self.cell.inner.get() }
155    }
156}
157
158/// A guard that allows mutably borrowing the cell's value, as well as its token.
159pub struct TokenGuardMut<'a, T: ?Sized, Token: TokenTrait> {
160    cell: &'a TokenCell<T, Token>,
161    token: &'a mut Token,
162}
163impl<'a, T: ?Sized, Token: TokenTrait> TokenGuardMut<'a, T, Token> {
164    /// Reborrows the token immutably.
165    pub const fn token(&self) -> &Token {
166        self.token
167    }
168    /// Reborrows the token mutably.
169    #[rustversion::attr(since(1.83), const)]
170    pub fn token_mut(&mut self) -> &mut Token {
171        self.token
172    }
173}
174impl<'a, T: ?Sized, Token: TokenTrait> Deref for TokenGuardMut<'a, T, Token> {
175    type Target = T;
176    fn deref(&self) -> &Self::Target {
177        unsafe { &*self.cell.inner.get() }
178    }
179}
180impl<'a, T, Token: TokenTrait> core::ops::DerefMut for TokenGuardMut<'a, T, Token> {
181    fn deref_mut(&mut self) -> &mut Self::Target {
182        unsafe { &mut *self.cell.inner.get() }
183    }
184}
185
186/// A Cell that shifts the management of access permissions to its inner value onto a `Token`.
187pub struct TokenCell<T: ?Sized, Token: TokenTrait> {
188    token_id: Token::Identifier,
189    inner: UnsafeCell<T>,
190}
191impl<T: ?Sized, Token: TokenTrait> TokenCell<T, Token> {
192    /// While cells are typically behind immutable references,
193    /// obtaining a mutable reference to one is still proof of unique access.
194    #[rustversion::attr(since(1.83), const)]
195    pub fn get_mut(&mut self) -> &mut T {
196        self.inner.get_mut()
197    }
198}
199impl<T: Sized, Token: TokenTrait> TokenCell<T, Token> {
200    /// Unwraps the value from the cell.
201    ///
202    /// Full ownership of the cell is sufficient proof that the inner value can be recovered.
203    pub fn into_inner(self) -> T {
204        self.inner.into_inner()
205    }
206}
207impl<T: ?Sized, Token: TokenTrait> Deref for TokenCell<T, Token> {
208    type Target = UnsafeCell<T>;
209    fn deref(&self) -> &Self::Target {
210        &self.inner
211    }
212}
213impl<T: ?Sized, Token: TokenTrait> DerefMut for TokenCell<T, Token> {
214    fn deref_mut(&mut self) -> &mut Self::Target {
215        &mut self.inner
216    }
217}
218
219unsafe impl<T: ?Sized, Token: TokenTrait> Sync for TokenCell<T, Token> {}
220
221impl<T: ?Sized, Token: TokenTrait> TokenCellTrait<T, Token> for TokenCell<T, Token> {
222    fn new(inner: T, token: &Token) -> Self
223    where
224        T: Sized,
225    {
226        TokenCell {
227            inner: UnsafeCell::new(inner),
228            token_id: token.identifier(),
229        }
230    }
231    fn try_guard<'l>(
232        &'l self,
233        token: &'l Token,
234    ) -> Result<TokenGuard<'l, T, Token>, <Token as TokenTrait>::ComparisonError> {
235        token
236            .compare(&self.token_id)
237            .map_likely(move |_| TokenGuard { cell: self, token })
238    }
239    fn try_borrow<'l>(&'l self, token: &'l Token) -> Result<&'l T, Token::ComparisonError> {
240        token
241            .compare(&self.token_id)
242            .map_likely(move |_| unsafe { &*self.inner.get() })
243    }
244    fn try_guard_mut<'l>(
245        &'l self,
246        token: &'l mut Token,
247    ) -> Result<TokenGuardMut<'l, T, Token>, <Token as TokenTrait>::ComparisonError> {
248        token
249            .compare(&self.token_id)
250            .map_likely(move |_| TokenGuardMut { cell: self, token })
251    }
252
253    fn try_borrow_mut<'l>(
254        &'l self,
255        token: &'l mut Token,
256    ) -> Result<&'l mut T, Token::ComparisonError> {
257        token
258            .compare(&self.token_id)
259            .map_likely(move |_| unsafe { &mut *self.inner.get() })
260    }
261}
token_cell/core.rs

token_cell/
core.rs
