1 // SPDX-License-Identifier: GPL-2.0
9 ops::{Deref, DerefMut},
12 /// Used to transfer ownership to and from foreign (non-Rust) languages.
14 /// Ownership is transferred from Rust to a foreign language by calling [`Self::into_foreign`] and
15 /// later may be transferred back to Rust by calling [`Self::from_foreign`].
17 /// This trait is meant to be used in cases when Rust objects are stored in C objects and
18 /// eventually "freed" back to Rust.
19 pub trait ForeignOwnable: Sized {
20 /// Type of values borrowed between calls to [`ForeignOwnable::into_foreign`] and
21 /// [`ForeignOwnable::from_foreign`].
24 /// Converts a Rust-owned object to a foreign-owned one.
26 /// The foreign representation is a pointer to void.
27 fn into_foreign(self) -> *const core::ffi::c_void;
29 /// Borrows a foreign-owned object.
33 /// `ptr` must have been returned by a previous call to [`ForeignOwnable::into_foreign`] for
34 /// which a previous matching [`ForeignOwnable::from_foreign`] hasn't been called yet.
35 /// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow_mut`]
36 /// for this object must have been dropped.
37 unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> Self::Borrowed<'a>;
39 /// Mutably borrows a foreign-owned object.
43 /// `ptr` must have been returned by a previous call to [`ForeignOwnable::into_foreign`] for
44 /// which a previous matching [`ForeignOwnable::from_foreign`] hasn't been called yet.
45 /// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow`] and
46 /// [`ForeignOwnable::borrow_mut`] for this object must have been dropped.
47 unsafe fn borrow_mut(ptr: *const core::ffi::c_void) -> ScopeGuard<Self, fn(Self)> {
48 // SAFETY: The safety requirements ensure that `ptr` came from a previous call to
50 ScopeGuard::new_with_data(unsafe { Self::from_foreign(ptr) }, |d| {
55 /// Converts a foreign-owned object back to a Rust-owned one.
59 /// `ptr` must have been returned by a previous call to [`ForeignOwnable::into_foreign`] for
60 /// which a previous matching [`ForeignOwnable::from_foreign`] hasn't been called yet.
61 /// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow`] and
62 /// [`ForeignOwnable::borrow_mut`] for this object must have been dropped.
63 unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self;
66 impl<T: 'static> ForeignOwnable for Box<T> {
67 type Borrowed<'a> = &'a T;
69 fn into_foreign(self) -> *const core::ffi::c_void {
70 Box::into_raw(self) as _
73 unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> &'a T {
74 // SAFETY: The safety requirements for this function ensure that the object is still alive,
75 // so it is safe to dereference the raw pointer.
76 // The safety requirements of `from_foreign` also ensure that the object remains alive for
77 // the lifetime of the returned value.
78 unsafe { &*ptr.cast() }
81 unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {
82 // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
83 // call to `Self::into_foreign`.
84 unsafe { Box::from_raw(ptr as _) }
88 impl ForeignOwnable for () {
89 type Borrowed<'a> = ();
91 fn into_foreign(self) -> *const core::ffi::c_void {
92 core::ptr::NonNull::dangling().as_ptr()
95 unsafe fn borrow<'a>(_: *const core::ffi::c_void) -> Self::Borrowed<'a> {}
97 unsafe fn from_foreign(_: *const core::ffi::c_void) -> Self {}
100 /// Runs a cleanup function/closure when dropped.
102 /// The [`ScopeGuard::dismiss`] function prevents the cleanup function from running.
106 /// In the example below, we have multiple exit paths and we want to log regardless of which one is
109 /// # use kernel::ScopeGuard;
110 /// fn example1(arg: bool) {
111 /// let _log = ScopeGuard::new(|| pr_info!("example1 completed\n"));
117 /// pr_info!("Do something...\n");
120 /// # example1(false);
121 /// # example1(true);
124 /// In the example below, we want to log the same message on all early exits but a different one on
125 /// the main exit path:
127 /// # use kernel::ScopeGuard;
128 /// fn example2(arg: bool) {
129 /// let log = ScopeGuard::new(|| pr_info!("example2 returned early\n"));
135 /// // (Other early returns...)
138 /// pr_info!("example2 no early return\n");
141 /// # example2(false);
142 /// # example2(true);
145 /// In the example below, we need a mutable object (the vector) to be accessible within the log
146 /// function, so we wrap it in the [`ScopeGuard`]:
148 /// # use kernel::ScopeGuard;
149 /// fn example3(arg: bool) -> Result {
151 /// ScopeGuard::new_with_data(Vec::new(), |v| pr_info!("vec had {} elements\n", v.len()));
153 /// vec.try_push(10u8)?;
157 /// vec.try_push(20u8)?;
161 /// # assert_eq!(example3(false), Ok(()));
162 /// # assert_eq!(example3(true), Ok(()));
167 /// The value stored in the struct is nearly always `Some(_)`, except between
168 /// [`ScopeGuard::dismiss`] and [`ScopeGuard::drop`]: in this case, it will be `None` as the value
169 /// will have been returned to the caller. Since [`ScopeGuard::dismiss`] consumes the guard,
170 /// callers won't be able to use it anymore.
171 pub struct ScopeGuard<T, F: FnOnce(T)>(Option<(T, F)>);
173 impl<T, F: FnOnce(T)> ScopeGuard<T, F> {
174 /// Creates a new guarded object wrapping the given data and with the given cleanup function.
175 pub fn new_with_data(data: T, cleanup_func: F) -> Self {
176 // INVARIANT: The struct is being initialised with `Some(_)`.
177 Self(Some((data, cleanup_func)))
180 /// Prevents the cleanup function from running and returns the guarded data.
181 pub fn dismiss(mut self) -> T {
182 // INVARIANT: This is the exception case in the invariant; it is not visible to callers
183 // because this function consumes `self`.
184 self.0.take().unwrap().0
188 impl ScopeGuard<(), fn(())> {
189 /// Creates a new guarded object with the given cleanup function.
190 pub fn new(cleanup: impl FnOnce()) -> ScopeGuard<(), impl FnOnce(())> {
191 ScopeGuard::new_with_data((), move |_| cleanup())
195 impl<T, F: FnOnce(T)> Deref for ScopeGuard<T, F> {
198 fn deref(&self) -> &T {
199 // The type invariants guarantee that `unwrap` will succeed.
200 &self.0.as_ref().unwrap().0
204 impl<T, F: FnOnce(T)> DerefMut for ScopeGuard<T, F> {
205 fn deref_mut(&mut self) -> &mut T {
206 // The type invariants guarantee that `unwrap` will succeed.
207 &mut self.0.as_mut().unwrap().0
211 impl<T, F: FnOnce(T)> Drop for ScopeGuard<T, F> {
213 // Run the cleanup function if one is still present.
214 if let Some((data, cleanup)) = self.0.take() {
220 /// Stores an opaque value.
222 /// This is meant to be used with FFI objects that are never interpreted by Rust code.
224 pub struct Opaque<T>(MaybeUninit<UnsafeCell<T>>);
227 /// Creates a new opaque value.
228 pub const fn new(value: T) -> Self {
229 Self(MaybeUninit::new(UnsafeCell::new(value)))
232 /// Creates an uninitialised value.
233 pub const fn uninit() -> Self {
234 Self(MaybeUninit::uninit())
237 /// Returns a raw pointer to the opaque data.
238 pub fn get(&self) -> *mut T {
239 UnsafeCell::raw_get(self.0.as_ptr())
243 /// A sum type that always holds either a value of type `L` or `R`.
244 pub enum Either<L, R> {
245 /// Constructs an instance of [`Either`] containing a value of type `L`.
248 /// Constructs an instance of [`Either`] containing a value of type `R`.