xref: /linux/rust/kernel/revocable.rs (revision 7b1166dee847d5018c1f3cc781218e806078f752)
1 // SPDX-License-Identifier: GPL-2.0
2 
3 //! Revocable objects.
4 //!
5 //! The [`Revocable`] type wraps other types and allows access to them to be revoked. The existence
6 //! of a [`RevocableGuard`] ensures that objects remain valid.
7 
8 use crate::{bindings, prelude::*, sync::rcu, types::Opaque};
9 use core::{
10     marker::PhantomData,
11     ops::Deref,
12     ptr::drop_in_place,
13     sync::atomic::{AtomicBool, Ordering},
14 };
15 
16 /// An object that can become inaccessible at runtime.
17 ///
18 /// Once access is revoked and all concurrent users complete (i.e., all existing instances of
19 /// [`RevocableGuard`] are dropped), the wrapped object is also dropped.
20 ///
21 /// # Examples
22 ///
23 /// ```
24 /// # use kernel::revocable::Revocable;
25 ///
26 /// struct Example {
27 ///     a: u32,
28 ///     b: u32,
29 /// }
30 ///
31 /// fn add_two(v: &Revocable<Example>) -> Option<u32> {
32 ///     let guard = v.try_access()?;
33 ///     Some(guard.a + guard.b)
34 /// }
35 ///
36 /// let v = KBox::pin_init(Revocable::new(Example { a: 10, b: 20 }), GFP_KERNEL).unwrap();
37 /// assert_eq!(add_two(&v), Some(30));
38 /// v.revoke();
39 /// assert_eq!(add_two(&v), None);
40 /// ```
41 ///
42 /// Sample example as above, but explicitly using the rcu read side lock.
43 ///
44 /// ```
45 /// # use kernel::revocable::Revocable;
46 /// use kernel::sync::rcu;
47 ///
48 /// struct Example {
49 ///     a: u32,
50 ///     b: u32,
51 /// }
52 ///
53 /// fn add_two(v: &Revocable<Example>) -> Option<u32> {
54 ///     let guard = rcu::read_lock();
55 ///     let e = v.try_access_with_guard(&guard)?;
56 ///     Some(e.a + e.b)
57 /// }
58 ///
59 /// let v = KBox::pin_init(Revocable::new(Example { a: 10, b: 20 }), GFP_KERNEL).unwrap();
60 /// assert_eq!(add_two(&v), Some(30));
61 /// v.revoke();
62 /// assert_eq!(add_two(&v), None);
63 /// ```
64 #[pin_data(PinnedDrop)]
65 pub struct Revocable<T> {
66     is_available: AtomicBool,
67     #[pin]
68     data: Opaque<T>,
69 }
70 
71 // SAFETY: `Revocable` is `Send` if the wrapped object is also `Send`. This is because while the
72 // functionality exposed by `Revocable` can be accessed from any thread/CPU, it is possible that
73 // this isn't supported by the wrapped object.
74 unsafe impl<T: Send> Send for Revocable<T> {}
75 
76 // SAFETY: `Revocable` is `Sync` if the wrapped object is both `Send` and `Sync`. We require `Send`
77 // from the wrapped object as well because  of `Revocable::revoke`, which can trigger the `Drop`
78 // implementation of the wrapped object from an arbitrary thread.
79 unsafe impl<T: Sync + Send> Sync for Revocable<T> {}
80 
81 impl<T> Revocable<T> {
82     /// Creates a new revocable instance of the given data.
83     pub fn new(data: impl PinInit<T>) -> impl PinInit<Self> {
84         pin_init!(Self {
85             is_available: AtomicBool::new(true),
86             data <- Opaque::pin_init(data),
87         })
88     }
89 
90     /// Tries to access the revocable wrapped object.
91     ///
92     /// Returns `None` if the object has been revoked and is therefore no longer accessible.
93     ///
94     /// Returns a guard that gives access to the object otherwise; the object is guaranteed to
95     /// remain accessible while the guard is alive. In such cases, callers are not allowed to sleep
96     /// because another CPU may be waiting to complete the revocation of this object.
97     pub fn try_access(&self) -> Option<RevocableGuard<'_, T>> {
98         let guard = rcu::read_lock();
99         if self.is_available.load(Ordering::Relaxed) {
100             // Since `self.is_available` is true, data is initialised and has to remain valid
101             // because the RCU read side lock prevents it from being dropped.
102             Some(RevocableGuard::new(self.data.get(), guard))
103         } else {
104             None
105         }
106     }
107 
108     /// Tries to access the revocable wrapped object.
109     ///
110     /// Returns `None` if the object has been revoked and is therefore no longer accessible.
111     ///
112     /// Returns a shared reference to the object otherwise; the object is guaranteed to
113     /// remain accessible while the rcu read side guard is alive. In such cases, callers are not
114     /// allowed to sleep because another CPU may be waiting to complete the revocation of this
115     /// object.
116     pub fn try_access_with_guard<'a>(&'a self, _guard: &'a rcu::Guard) -> Option<&'a T> {
117         if self.is_available.load(Ordering::Relaxed) {
118             // SAFETY: Since `self.is_available` is true, data is initialised and has to remain
119             // valid because the RCU read side lock prevents it from being dropped.
120             Some(unsafe { &*self.data.get() })
121         } else {
122             None
123         }
124     }
125 
126     /// Tries to access the wrapped object and run a closure on it while the guard is held.
127     ///
128     /// This is a convenience method to run short non-sleepable code blocks while ensuring the
129     /// guard is dropped afterwards. [`Self::try_access`] carries the risk that the caller will
130     /// forget to explicitly drop that returned guard before calling sleepable code; this method
131     /// adds an extra safety to make sure it doesn't happen.
132     ///
133     /// Returns [`None`] if the object has been revoked and is therefore no longer accessible, or
134     /// the result of the closure wrapped in [`Some`]. If the closure returns a [`Result`] then the
135     /// return type becomes `Option<Result<>>`, which can be inconvenient. Users are encouraged to
136     /// define their own macro that turns the [`Option`] into a proper error code and flattens the
137     /// inner result into it if it makes sense within their subsystem.
138     pub fn try_access_with<R, F: FnOnce(&T) -> R>(&self, f: F) -> Option<R> {
139         self.try_access().map(|t| f(&*t))
140     }
141 
142     /// Directly access the revocable wrapped object.
143     ///
144     /// # Safety
145     ///
146     /// The caller must ensure this [`Revocable`] instance hasn't been revoked and won't be revoked
147     /// as long as the returned `&T` lives.
148     pub unsafe fn access(&self) -> &T {
149         // SAFETY: By the safety requirement of this function it is guaranteed that
150         // `self.data.get()` is a valid pointer to an instance of `T`.
151         unsafe { &*self.data.get() }
152     }
153 
154     /// # Safety
155     ///
156     /// Callers must ensure that there are no more concurrent users of the revocable object.
157     unsafe fn revoke_internal<const SYNC: bool>(&self) {
158         if self.is_available.swap(false, Ordering::Relaxed) {
159             if SYNC {
160                 // SAFETY: Just an FFI call, there are no further requirements.
161                 unsafe { bindings::synchronize_rcu() };
162             }
163 
164             // SAFETY: We know `self.data` is valid because only one CPU can succeed the
165             // `compare_exchange` above that takes `is_available` from `true` to `false`.
166             unsafe { drop_in_place(self.data.get()) };
167         }
168     }
169 
170     /// Revokes access to and drops the wrapped object.
171     ///
172     /// Access to the object is revoked immediately to new callers of [`Revocable::try_access`],
173     /// expecting that there are no concurrent users of the object.
174     ///
175     /// # Safety
176     ///
177     /// Callers must ensure that there are no more concurrent users of the revocable object.
178     pub unsafe fn revoke_nosync(&self) {
179         // SAFETY: By the safety requirement of this function, the caller ensures that nobody is
180         // accessing the data anymore and hence we don't have to wait for the grace period to
181         // finish.
182         unsafe { self.revoke_internal::<false>() }
183     }
184 
185     /// Revokes access to and drops the wrapped object.
186     ///
187     /// Access to the object is revoked immediately to new callers of [`Revocable::try_access`].
188     ///
189     /// If there are concurrent users of the object (i.e., ones that called
190     /// [`Revocable::try_access`] beforehand and still haven't dropped the returned guard), this
191     /// function waits for the concurrent access to complete before dropping the wrapped object.
192     pub fn revoke(&self) {
193         // SAFETY: By passing `true` we ask `revoke_internal` to wait for the grace period to
194         // finish.
195         unsafe { self.revoke_internal::<true>() }
196     }
197 }
198 
199 #[pinned_drop]
200 impl<T> PinnedDrop for Revocable<T> {
201     fn drop(self: Pin<&mut Self>) {
202         // Drop only if the data hasn't been revoked yet (in which case it has already been
203         // dropped).
204         // SAFETY: We are not moving out of `p`, only dropping in place
205         let p = unsafe { self.get_unchecked_mut() };
206         if *p.is_available.get_mut() {
207             // SAFETY: We know `self.data` is valid because no other CPU has changed
208             // `is_available` to `false` yet, and no other CPU can do it anymore because this CPU
209             // holds the only reference (mutable) to `self` now.
210             unsafe { drop_in_place(p.data.get()) };
211         }
212     }
213 }
214 
215 /// A guard that allows access to a revocable object and keeps it alive.
216 ///
217 /// CPUs may not sleep while holding on to [`RevocableGuard`] because it's in atomic context
218 /// holding the RCU read-side lock.
219 ///
220 /// # Invariants
221 ///
222 /// The RCU read-side lock is held while the guard is alive.
223 pub struct RevocableGuard<'a, T> {
224     data_ref: *const T,
225     _rcu_guard: rcu::Guard,
226     _p: PhantomData<&'a ()>,
227 }
228 
229 impl<T> RevocableGuard<'_, T> {
230     fn new(data_ref: *const T, rcu_guard: rcu::Guard) -> Self {
231         Self {
232             data_ref,
233             _rcu_guard: rcu_guard,
234             _p: PhantomData,
235         }
236     }
237 }
238 
239 impl<T> Deref for RevocableGuard<'_, T> {
240     type Target = T;
241 
242     fn deref(&self) -> &Self::Target {
243         // SAFETY: By the type invariants, we hold the rcu read-side lock, so the object is
244         // guaranteed to remain valid.
245         unsafe { &*self.data_ref }
246     }
247 }
248