Loading...
1// SPDX-License-Identifier: GPL-2.0
2
3//! Kernel types.
4
5use crate::init::{self, PinInit};
6use core::{
7 cell::UnsafeCell,
8 marker::{PhantomData, PhantomPinned},
9 mem::{ManuallyDrop, MaybeUninit},
10 ops::{Deref, DerefMut},
11 ptr::NonNull,
12};
13
14/// Used to transfer ownership to and from foreign (non-Rust) languages.
15///
16/// Ownership is transferred from Rust to a foreign language by calling [`Self::into_foreign`] and
17/// later may be transferred back to Rust by calling [`Self::from_foreign`].
18///
19/// This trait is meant to be used in cases when Rust objects are stored in C objects and
20/// eventually "freed" back to Rust.
21pub trait ForeignOwnable: Sized {
22 /// Type of values borrowed between calls to [`ForeignOwnable::into_foreign`] and
23 /// [`ForeignOwnable::from_foreign`].
24 type Borrowed<'a>;
25
26 /// Converts a Rust-owned object to a foreign-owned one.
27 ///
28 /// The foreign representation is a pointer to void. There are no guarantees for this pointer.
29 /// For example, it might be invalid, dangling or pointing to uninitialized memory. Using it in
30 /// any way except for [`ForeignOwnable::from_foreign`], [`ForeignOwnable::borrow`],
31 /// [`ForeignOwnable::try_from_foreign`] can result in undefined behavior.
32 fn into_foreign(self) -> *const crate::ffi::c_void;
33
34 /// Borrows a foreign-owned object.
35 ///
36 /// # Safety
37 ///
38 /// `ptr` must have been returned by a previous call to [`ForeignOwnable::into_foreign`] for
39 /// which a previous matching [`ForeignOwnable::from_foreign`] hasn't been called yet.
40 unsafe fn borrow<'a>(ptr: *const crate::ffi::c_void) -> Self::Borrowed<'a>;
41
42 /// Converts a foreign-owned object back to a Rust-owned one.
43 ///
44 /// # Safety
45 ///
46 /// `ptr` must have been returned by a previous call to [`ForeignOwnable::into_foreign`] for
47 /// which a previous matching [`ForeignOwnable::from_foreign`] hasn't been called yet.
48 /// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow`] for
49 /// this object must have been dropped.
50 unsafe fn from_foreign(ptr: *const crate::ffi::c_void) -> Self;
51
52 /// Tries to convert a foreign-owned object back to a Rust-owned one.
53 ///
54 /// A convenience wrapper over [`ForeignOwnable::from_foreign`] that returns [`None`] if `ptr`
55 /// is null.
56 ///
57 /// # Safety
58 ///
59 /// `ptr` must either be null or satisfy the safety requirements for
60 /// [`ForeignOwnable::from_foreign`].
61 unsafe fn try_from_foreign(ptr: *const crate::ffi::c_void) -> Option<Self> {
62 if ptr.is_null() {
63 None
64 } else {
65 // SAFETY: Since `ptr` is not null here, then `ptr` satisfies the safety requirements
66 // of `from_foreign` given the safety requirements of this function.
67 unsafe { Some(Self::from_foreign(ptr)) }
68 }
69 }
70}
71
72impl ForeignOwnable for () {
73 type Borrowed<'a> = ();
74
75 fn into_foreign(self) -> *const crate::ffi::c_void {
76 core::ptr::NonNull::dangling().as_ptr()
77 }
78
79 unsafe fn borrow<'a>(_: *const crate::ffi::c_void) -> Self::Borrowed<'a> {}
80
81 unsafe fn from_foreign(_: *const crate::ffi::c_void) -> Self {}
82}
83
84/// Runs a cleanup function/closure when dropped.
85///
86/// The [`ScopeGuard::dismiss`] function prevents the cleanup function from running.
87///
88/// # Examples
89///
90/// In the example below, we have multiple exit paths and we want to log regardless of which one is
91/// taken:
92///
93/// ```
94/// # use kernel::types::ScopeGuard;
95/// fn example1(arg: bool) {
96/// let _log = ScopeGuard::new(|| pr_info!("example1 completed\n"));
97///
98/// if arg {
99/// return;
100/// }
101///
102/// pr_info!("Do something...\n");
103/// }
104///
105/// # example1(false);
106/// # example1(true);
107/// ```
108///
109/// In the example below, we want to log the same message on all early exits but a different one on
110/// the main exit path:
111///
112/// ```
113/// # use kernel::types::ScopeGuard;
114/// fn example2(arg: bool) {
115/// let log = ScopeGuard::new(|| pr_info!("example2 returned early\n"));
116///
117/// if arg {
118/// return;
119/// }
120///
121/// // (Other early returns...)
122///
123/// log.dismiss();
124/// pr_info!("example2 no early return\n");
125/// }
126///
127/// # example2(false);
128/// # example2(true);
129/// ```
130///
131/// In the example below, we need a mutable object (the vector) to be accessible within the log
132/// function, so we wrap it in the [`ScopeGuard`]:
133///
134/// ```
135/// # use kernel::types::ScopeGuard;
136/// fn example3(arg: bool) -> Result {
137/// let mut vec =
138/// ScopeGuard::new_with_data(KVec::new(), |v| pr_info!("vec had {} elements\n", v.len()));
139///
140/// vec.push(10u8, GFP_KERNEL)?;
141/// if arg {
142/// return Ok(());
143/// }
144/// vec.push(20u8, GFP_KERNEL)?;
145/// Ok(())
146/// }
147///
148/// # assert_eq!(example3(false), Ok(()));
149/// # assert_eq!(example3(true), Ok(()));
150/// ```
151///
152/// # Invariants
153///
154/// The value stored in the struct is nearly always `Some(_)`, except between
155/// [`ScopeGuard::dismiss`] and [`ScopeGuard::drop`]: in this case, it will be `None` as the value
156/// will have been returned to the caller. Since [`ScopeGuard::dismiss`] consumes the guard,
157/// callers won't be able to use it anymore.
158pub struct ScopeGuard<T, F: FnOnce(T)>(Option<(T, F)>);
159
160impl<T, F: FnOnce(T)> ScopeGuard<T, F> {
161 /// Creates a new guarded object wrapping the given data and with the given cleanup function.
162 pub fn new_with_data(data: T, cleanup_func: F) -> Self {
163 // INVARIANT: The struct is being initialised with `Some(_)`.
164 Self(Some((data, cleanup_func)))
165 }
166
167 /// Prevents the cleanup function from running and returns the guarded data.
168 pub fn dismiss(mut self) -> T {
169 // INVARIANT: This is the exception case in the invariant; it is not visible to callers
170 // because this function consumes `self`.
171 self.0.take().unwrap().0
172 }
173}
174
175impl ScopeGuard<(), fn(())> {
176 /// Creates a new guarded object with the given cleanup function.
177 pub fn new(cleanup: impl FnOnce()) -> ScopeGuard<(), impl FnOnce(())> {
178 ScopeGuard::new_with_data((), move |()| cleanup())
179 }
180}
181
182impl<T, F: FnOnce(T)> Deref for ScopeGuard<T, F> {
183 type Target = T;
184
185 fn deref(&self) -> &T {
186 // The type invariants guarantee that `unwrap` will succeed.
187 &self.0.as_ref().unwrap().0
188 }
189}
190
191impl<T, F: FnOnce(T)> DerefMut for ScopeGuard<T, F> {
192 fn deref_mut(&mut self) -> &mut T {
193 // The type invariants guarantee that `unwrap` will succeed.
194 &mut self.0.as_mut().unwrap().0
195 }
196}
197
198impl<T, F: FnOnce(T)> Drop for ScopeGuard<T, F> {
199 fn drop(&mut self) {
200 // Run the cleanup function if one is still present.
201 if let Some((data, cleanup)) = self.0.take() {
202 cleanup(data)
203 }
204 }
205}
206
207/// Stores an opaque value.
208///
209/// `Opaque<T>` is meant to be used with FFI objects that are never interpreted by Rust code.
210///
211/// It is used to wrap structs from the C side, like for example `Opaque<bindings::mutex>`.
212/// It gets rid of all the usual assumptions that Rust has for a value:
213///
214/// * The value is allowed to be uninitialized (for example have invalid bit patterns: `3` for a
215/// [`bool`]).
216/// * The value is allowed to be mutated, when a `&Opaque<T>` exists on the Rust side.
217/// * No uniqueness for mutable references: it is fine to have multiple `&mut Opaque<T>` point to
218/// the same value.
219/// * The value is not allowed to be shared with other threads (i.e. it is `!Sync`).
220///
221/// This has to be used for all values that the C side has access to, because it can't be ensured
222/// that the C side is adhering to the usual constraints that Rust needs.
223///
224/// Using `Opaque<T>` allows to continue to use references on the Rust side even for values shared
225/// with C.
226///
227/// # Examples
228///
229/// ```
230/// # #![expect(unreachable_pub, clippy::disallowed_names)]
231/// use kernel::types::Opaque;
232/// # // Emulate a C struct binding which is from C, maybe uninitialized or not, only the C side
233/// # // knows.
234/// # mod bindings {
235/// # pub struct Foo {
236/// # pub val: u8,
237/// # }
238/// # }
239///
240/// // `foo.val` is assumed to be handled on the C side, so we use `Opaque` to wrap it.
241/// pub struct Foo {
242/// foo: Opaque<bindings::Foo>,
243/// }
244///
245/// impl Foo {
246/// pub fn get_val(&self) -> u8 {
247/// let ptr = Opaque::get(&self.foo);
248///
249/// // SAFETY: `Self` is valid from C side.
250/// unsafe { (*ptr).val }
251/// }
252/// }
253///
254/// // Create an instance of `Foo` with the `Opaque` wrapper.
255/// let foo = Foo {
256/// foo: Opaque::new(bindings::Foo { val: 0xdb }),
257/// };
258///
259/// assert_eq!(foo.get_val(), 0xdb);
260/// ```
261#[repr(transparent)]
262pub struct Opaque<T> {
263 value: UnsafeCell<MaybeUninit<T>>,
264 _pin: PhantomPinned,
265}
266
267impl<T> Opaque<T> {
268 /// Creates a new opaque value.
269 pub const fn new(value: T) -> Self {
270 Self {
271 value: UnsafeCell::new(MaybeUninit::new(value)),
272 _pin: PhantomPinned,
273 }
274 }
275
276 /// Creates an uninitialised value.
277 pub const fn uninit() -> Self {
278 Self {
279 value: UnsafeCell::new(MaybeUninit::uninit()),
280 _pin: PhantomPinned,
281 }
282 }
283
284 /// Creates a pin-initializer from the given initializer closure.
285 ///
286 /// The returned initializer calls the given closure with the pointer to the inner `T` of this
287 /// `Opaque`. Since this memory is uninitialized, the closure is not allowed to read from it.
288 ///
289 /// This function is safe, because the `T` inside of an `Opaque` is allowed to be
290 /// uninitialized. Additionally, access to the inner `T` requires `unsafe`, so the caller needs
291 /// to verify at that point that the inner value is valid.
292 pub fn ffi_init(init_func: impl FnOnce(*mut T)) -> impl PinInit<Self> {
293 // SAFETY: We contain a `MaybeUninit`, so it is OK for the `init_func` to not fully
294 // initialize the `T`.
295 unsafe {
296 init::pin_init_from_closure::<_, ::core::convert::Infallible>(move |slot| {
297 init_func(Self::raw_get(slot));
298 Ok(())
299 })
300 }
301 }
302
303 /// Creates a fallible pin-initializer from the given initializer closure.
304 ///
305 /// The returned initializer calls the given closure with the pointer to the inner `T` of this
306 /// `Opaque`. Since this memory is uninitialized, the closure is not allowed to read from it.
307 ///
308 /// This function is safe, because the `T` inside of an `Opaque` is allowed to be
309 /// uninitialized. Additionally, access to the inner `T` requires `unsafe`, so the caller needs
310 /// to verify at that point that the inner value is valid.
311 pub fn try_ffi_init<E>(
312 init_func: impl FnOnce(*mut T) -> Result<(), E>,
313 ) -> impl PinInit<Self, E> {
314 // SAFETY: We contain a `MaybeUninit`, so it is OK for the `init_func` to not fully
315 // initialize the `T`.
316 unsafe { init::pin_init_from_closure::<_, E>(move |slot| init_func(Self::raw_get(slot))) }
317 }
318
319 /// Returns a raw pointer to the opaque data.
320 pub const fn get(&self) -> *mut T {
321 UnsafeCell::get(&self.value).cast::<T>()
322 }
323
324 /// Gets the value behind `this`.
325 ///
326 /// This function is useful to get access to the value without creating intermediate
327 /// references.
328 pub const fn raw_get(this: *const Self) -> *mut T {
329 UnsafeCell::raw_get(this.cast::<UnsafeCell<MaybeUninit<T>>>()).cast::<T>()
330 }
331}
332
333/// Types that are _always_ reference counted.
334///
335/// It allows such types to define their own custom ref increment and decrement functions.
336/// Additionally, it allows users to convert from a shared reference `&T` to an owned reference
337/// [`ARef<T>`].
338///
339/// This is usually implemented by wrappers to existing structures on the C side of the code. For
340/// Rust code, the recommendation is to use [`Arc`](crate::sync::Arc) to create reference-counted
341/// instances of a type.
342///
343/// # Safety
344///
345/// Implementers must ensure that increments to the reference count keep the object alive in memory
346/// at least until matching decrements are performed.
347///
348/// Implementers must also ensure that all instances are reference-counted. (Otherwise they
349/// won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object
350/// alive.)
351pub unsafe trait AlwaysRefCounted {
352 /// Increments the reference count on the object.
353 fn inc_ref(&self);
354
355 /// Decrements the reference count on the object.
356 ///
357 /// Frees the object when the count reaches zero.
358 ///
359 /// # Safety
360 ///
361 /// Callers must ensure that there was a previous matching increment to the reference count,
362 /// and that the object is no longer used after its reference count is decremented (as it may
363 /// result in the object being freed), unless the caller owns another increment on the refcount
364 /// (e.g., it calls [`AlwaysRefCounted::inc_ref`] twice, then calls
365 /// [`AlwaysRefCounted::dec_ref`] once).
366 unsafe fn dec_ref(obj: NonNull<Self>);
367}
368
369/// An owned reference to an always-reference-counted object.
370///
371/// The object's reference count is automatically decremented when an instance of [`ARef`] is
372/// dropped. It is also automatically incremented when a new instance is created via
373/// [`ARef::clone`].
374///
375/// # Invariants
376///
377/// The pointer stored in `ptr` is non-null and valid for the lifetime of the [`ARef`] instance. In
378/// particular, the [`ARef`] instance owns an increment on the underlying object's reference count.
379pub struct ARef<T: AlwaysRefCounted> {
380 ptr: NonNull<T>,
381 _p: PhantomData<T>,
382}
383
384// SAFETY: It is safe to send `ARef<T>` to another thread when the underlying `T` is `Sync` because
385// it effectively means sharing `&T` (which is safe because `T` is `Sync`); additionally, it needs
386// `T` to be `Send` because any thread that has an `ARef<T>` may ultimately access `T` using a
387// mutable reference, for example, when the reference count reaches zero and `T` is dropped.
388unsafe impl<T: AlwaysRefCounted + Sync + Send> Send for ARef<T> {}
389
390// SAFETY: It is safe to send `&ARef<T>` to another thread when the underlying `T` is `Sync`
391// because it effectively means sharing `&T` (which is safe because `T` is `Sync`); additionally,
392// it needs `T` to be `Send` because any thread that has a `&ARef<T>` may clone it and get an
393// `ARef<T>` on that thread, so the thread may ultimately access `T` using a mutable reference, for
394// example, when the reference count reaches zero and `T` is dropped.
395unsafe impl<T: AlwaysRefCounted + Sync + Send> Sync for ARef<T> {}
396
397impl<T: AlwaysRefCounted> ARef<T> {
398 /// Creates a new instance of [`ARef`].
399 ///
400 /// It takes over an increment of the reference count on the underlying object.
401 ///
402 /// # Safety
403 ///
404 /// Callers must ensure that the reference count was incremented at least once, and that they
405 /// are properly relinquishing one increment. That is, if there is only one increment, callers
406 /// must not use the underlying object anymore -- it is only safe to do so via the newly
407 /// created [`ARef`].
408 pub unsafe fn from_raw(ptr: NonNull<T>) -> Self {
409 // INVARIANT: The safety requirements guarantee that the new instance now owns the
410 // increment on the refcount.
411 Self {
412 ptr,
413 _p: PhantomData,
414 }
415 }
416
417 /// Consumes the `ARef`, returning a raw pointer.
418 ///
419 /// This function does not change the refcount. After calling this function, the caller is
420 /// responsible for the refcount previously managed by the `ARef`.
421 ///
422 /// # Examples
423 ///
424 /// ```
425 /// use core::ptr::NonNull;
426 /// use kernel::types::{ARef, AlwaysRefCounted};
427 ///
428 /// struct Empty {}
429 ///
430 /// # // SAFETY: TODO.
431 /// unsafe impl AlwaysRefCounted for Empty {
432 /// fn inc_ref(&self) {}
433 /// unsafe fn dec_ref(_obj: NonNull<Self>) {}
434 /// }
435 ///
436 /// let mut data = Empty {};
437 /// let ptr = NonNull::<Empty>::new(&mut data as *mut _).unwrap();
438 /// # // SAFETY: TODO.
439 /// let data_ref: ARef<Empty> = unsafe { ARef::from_raw(ptr) };
440 /// let raw_ptr: NonNull<Empty> = ARef::into_raw(data_ref);
441 ///
442 /// assert_eq!(ptr, raw_ptr);
443 /// ```
444 pub fn into_raw(me: Self) -> NonNull<T> {
445 ManuallyDrop::new(me).ptr
446 }
447}
448
449impl<T: AlwaysRefCounted> Clone for ARef<T> {
450 fn clone(&self) -> Self {
451 self.inc_ref();
452 // SAFETY: We just incremented the refcount above.
453 unsafe { Self::from_raw(self.ptr) }
454 }
455}
456
457impl<T: AlwaysRefCounted> Deref for ARef<T> {
458 type Target = T;
459
460 fn deref(&self) -> &Self::Target {
461 // SAFETY: The type invariants guarantee that the object is valid.
462 unsafe { self.ptr.as_ref() }
463 }
464}
465
466impl<T: AlwaysRefCounted> From<&T> for ARef<T> {
467 fn from(b: &T) -> Self {
468 b.inc_ref();
469 // SAFETY: We just incremented the refcount above.
470 unsafe { Self::from_raw(NonNull::from(b)) }
471 }
472}
473
474impl<T: AlwaysRefCounted> Drop for ARef<T> {
475 fn drop(&mut self) {
476 // SAFETY: The type invariants guarantee that the `ARef` owns the reference we're about to
477 // decrement.
478 unsafe { T::dec_ref(self.ptr) };
479 }
480}
481
482/// A sum type that always holds either a value of type `L` or `R`.
483///
484/// # Examples
485///
486/// ```
487/// use kernel::types::Either;
488///
489/// let left_value: Either<i32, &str> = Either::Left(7);
490/// let right_value: Either<i32, &str> = Either::Right("right value");
491/// ```
492pub enum Either<L, R> {
493 /// Constructs an instance of [`Either`] containing a value of type `L`.
494 Left(L),
495
496 /// Constructs an instance of [`Either`] containing a value of type `R`.
497 Right(R),
498}
499
500/// Zero-sized type to mark types not [`Send`].
501///
502/// Add this type as a field to your struct if your type should not be sent to a different task.
503/// Since [`Send`] is an auto trait, adding a single field that is `!Send` will ensure that the
504/// whole type is `!Send`.
505///
506/// If a type is `!Send` it is impossible to give control over an instance of the type to another
507/// task. This is useful to include in types that store or reference task-local information. A file
508/// descriptor is an example of such task-local information.
509///
510/// This type also makes the type `!Sync`, which prevents immutable access to the value from
511/// several threads in parallel.
512pub type NotThreadSafe = PhantomData<*mut ()>;
513
514/// Used to construct instances of type [`NotThreadSafe`] similar to how `PhantomData` is
515/// constructed.
516///
517/// [`NotThreadSafe`]: type@NotThreadSafe
518#[allow(non_upper_case_globals)]
519pub const NotThreadSafe: NotThreadSafe = PhantomData;
1// SPDX-License-Identifier: GPL-2.0
2
3//! Kernel types.
4
5use crate::init::{self, PinInit};
6use alloc::boxed::Box;
7use core::{
8 cell::UnsafeCell,
9 marker::{PhantomData, PhantomPinned},
10 mem::MaybeUninit,
11 ops::{Deref, DerefMut},
12 ptr::NonNull,
13};
14
15/// Used to transfer ownership to and from foreign (non-Rust) languages.
16///
17/// Ownership is transferred from Rust to a foreign language by calling [`Self::into_foreign`] and
18/// later may be transferred back to Rust by calling [`Self::from_foreign`].
19///
20/// This trait is meant to be used in cases when Rust objects are stored in C objects and
21/// eventually "freed" back to Rust.
22pub trait ForeignOwnable: Sized {
23 /// Type of values borrowed between calls to [`ForeignOwnable::into_foreign`] and
24 /// [`ForeignOwnable::from_foreign`].
25 type Borrowed<'a>;
26
27 /// Converts a Rust-owned object to a foreign-owned one.
28 ///
29 /// The foreign representation is a pointer to void.
30 fn into_foreign(self) -> *const core::ffi::c_void;
31
32 /// Borrows a foreign-owned object.
33 ///
34 /// # Safety
35 ///
36 /// `ptr` must have been returned by a previous call to [`ForeignOwnable::into_foreign`] for
37 /// which a previous matching [`ForeignOwnable::from_foreign`] hasn't been called yet.
38 unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> Self::Borrowed<'a>;
39
40 /// Converts a foreign-owned object back to a Rust-owned one.
41 ///
42 /// # Safety
43 ///
44 /// `ptr` must have been returned by a previous call to [`ForeignOwnable::into_foreign`] for
45 /// which a previous matching [`ForeignOwnable::from_foreign`] hasn't been called yet.
46 /// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow`] for
47 /// this object must have been dropped.
48 unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self;
49
50 /// Tries to convert a foreign-owned object back to a Rust-owned one.
51 ///
52 /// A convenience wrapper over [`ForeignOwnable::from_foreign`] that returns [`None`] if `ptr`
53 /// is null.
54 ///
55 /// # Safety
56 ///
57 /// `ptr` must either be null or satisfy the safety requirements for
58 /// [`ForeignOwnable::from_foreign`].
59 unsafe fn try_from_foreign(ptr: *const core::ffi::c_void) -> Option<Self> {
60 if ptr.is_null() {
61 None
62 } else {
63 // SAFETY: Since `ptr` is not null here, then `ptr` satisfies the safety requirements
64 // of `from_foreign` given the safety requirements of this function.
65 unsafe { Some(Self::from_foreign(ptr)) }
66 }
67 }
68}
69
70impl<T: 'static> ForeignOwnable for Box<T> {
71 type Borrowed<'a> = &'a T;
72
73 fn into_foreign(self) -> *const core::ffi::c_void {
74 Box::into_raw(self) as _
75 }
76
77 unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> &'a T {
78 // SAFETY: The safety requirements for this function ensure that the object is still alive,
79 // so it is safe to dereference the raw pointer.
80 // The safety requirements of `from_foreign` also ensure that the object remains alive for
81 // the lifetime of the returned value.
82 unsafe { &*ptr.cast() }
83 }
84
85 unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {
86 // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
87 // call to `Self::into_foreign`.
88 unsafe { Box::from_raw(ptr as _) }
89 }
90}
91
92impl ForeignOwnable for () {
93 type Borrowed<'a> = ();
94
95 fn into_foreign(self) -> *const core::ffi::c_void {
96 core::ptr::NonNull::dangling().as_ptr()
97 }
98
99 unsafe fn borrow<'a>(_: *const core::ffi::c_void) -> Self::Borrowed<'a> {}
100
101 unsafe fn from_foreign(_: *const core::ffi::c_void) -> Self {}
102}
103
104/// Runs a cleanup function/closure when dropped.
105///
106/// The [`ScopeGuard::dismiss`] function prevents the cleanup function from running.
107///
108/// # Examples
109///
110/// In the example below, we have multiple exit paths and we want to log regardless of which one is
111/// taken:
112///
113/// ```
114/// # use kernel::types::ScopeGuard;
115/// fn example1(arg: bool) {
116/// let _log = ScopeGuard::new(|| pr_info!("example1 completed\n"));
117///
118/// if arg {
119/// return;
120/// }
121///
122/// pr_info!("Do something...\n");
123/// }
124///
125/// # example1(false);
126/// # example1(true);
127/// ```
128///
129/// In the example below, we want to log the same message on all early exits but a different one on
130/// the main exit path:
131///
132/// ```
133/// # use kernel::types::ScopeGuard;
134/// fn example2(arg: bool) {
135/// let log = ScopeGuard::new(|| pr_info!("example2 returned early\n"));
136///
137/// if arg {
138/// return;
139/// }
140///
141/// // (Other early returns...)
142///
143/// log.dismiss();
144/// pr_info!("example2 no early return\n");
145/// }
146///
147/// # example2(false);
148/// # example2(true);
149/// ```
150///
151/// In the example below, we need a mutable object (the vector) to be accessible within the log
152/// function, so we wrap it in the [`ScopeGuard`]:
153///
154/// ```
155/// # use kernel::types::ScopeGuard;
156/// fn example3(arg: bool) -> Result {
157/// let mut vec =
158/// ScopeGuard::new_with_data(Vec::new(), |v| pr_info!("vec had {} elements\n", v.len()));
159///
160/// vec.try_push(10u8)?;
161/// if arg {
162/// return Ok(());
163/// }
164/// vec.try_push(20u8)?;
165/// Ok(())
166/// }
167///
168/// # assert_eq!(example3(false), Ok(()));
169/// # assert_eq!(example3(true), Ok(()));
170/// ```
171///
172/// # Invariants
173///
174/// The value stored in the struct is nearly always `Some(_)`, except between
175/// [`ScopeGuard::dismiss`] and [`ScopeGuard::drop`]: in this case, it will be `None` as the value
176/// will have been returned to the caller. Since [`ScopeGuard::dismiss`] consumes the guard,
177/// callers won't be able to use it anymore.
178pub struct ScopeGuard<T, F: FnOnce(T)>(Option<(T, F)>);
179
180impl<T, F: FnOnce(T)> ScopeGuard<T, F> {
181 /// Creates a new guarded object wrapping the given data and with the given cleanup function.
182 pub fn new_with_data(data: T, cleanup_func: F) -> Self {
183 // INVARIANT: The struct is being initialised with `Some(_)`.
184 Self(Some((data, cleanup_func)))
185 }
186
187 /// Prevents the cleanup function from running and returns the guarded data.
188 pub fn dismiss(mut self) -> T {
189 // INVARIANT: This is the exception case in the invariant; it is not visible to callers
190 // because this function consumes `self`.
191 self.0.take().unwrap().0
192 }
193}
194
195impl ScopeGuard<(), fn(())> {
196 /// Creates a new guarded object with the given cleanup function.
197 pub fn new(cleanup: impl FnOnce()) -> ScopeGuard<(), impl FnOnce(())> {
198 ScopeGuard::new_with_data((), move |_| cleanup())
199 }
200}
201
202impl<T, F: FnOnce(T)> Deref for ScopeGuard<T, F> {
203 type Target = T;
204
205 fn deref(&self) -> &T {
206 // The type invariants guarantee that `unwrap` will succeed.
207 &self.0.as_ref().unwrap().0
208 }
209}
210
211impl<T, F: FnOnce(T)> DerefMut for ScopeGuard<T, F> {
212 fn deref_mut(&mut self) -> &mut T {
213 // The type invariants guarantee that `unwrap` will succeed.
214 &mut self.0.as_mut().unwrap().0
215 }
216}
217
218impl<T, F: FnOnce(T)> Drop for ScopeGuard<T, F> {
219 fn drop(&mut self) {
220 // Run the cleanup function if one is still present.
221 if let Some((data, cleanup)) = self.0.take() {
222 cleanup(data)
223 }
224 }
225}
226
227/// Stores an opaque value.
228///
229/// This is meant to be used with FFI objects that are never interpreted by Rust code.
230#[repr(transparent)]
231pub struct Opaque<T> {
232 value: UnsafeCell<MaybeUninit<T>>,
233 _pin: PhantomPinned,
234}
235
236impl<T> Opaque<T> {
237 /// Creates a new opaque value.
238 pub const fn new(value: T) -> Self {
239 Self {
240 value: UnsafeCell::new(MaybeUninit::new(value)),
241 _pin: PhantomPinned,
242 }
243 }
244
245 /// Creates an uninitialised value.
246 pub const fn uninit() -> Self {
247 Self {
248 value: UnsafeCell::new(MaybeUninit::uninit()),
249 _pin: PhantomPinned,
250 }
251 }
252
253 /// Creates a pin-initializer from the given initializer closure.
254 ///
255 /// The returned initializer calls the given closure with the pointer to the inner `T` of this
256 /// `Opaque`. Since this memory is uninitialized, the closure is not allowed to read from it.
257 ///
258 /// This function is safe, because the `T` inside of an `Opaque` is allowed to be
259 /// uninitialized. Additionally, access to the inner `T` requires `unsafe`, so the caller needs
260 /// to verify at that point that the inner value is valid.
261 pub fn ffi_init(init_func: impl FnOnce(*mut T)) -> impl PinInit<Self> {
262 // SAFETY: We contain a `MaybeUninit`, so it is OK for the `init_func` to not fully
263 // initialize the `T`.
264 unsafe {
265 init::pin_init_from_closure::<_, ::core::convert::Infallible>(move |slot| {
266 init_func(Self::raw_get(slot));
267 Ok(())
268 })
269 }
270 }
271
272 /// Returns a raw pointer to the opaque data.
273 pub fn get(&self) -> *mut T {
274 UnsafeCell::get(&self.value).cast::<T>()
275 }
276
277 /// Gets the value behind `this`.
278 ///
279 /// This function is useful to get access to the value without creating intermediate
280 /// references.
281 pub const fn raw_get(this: *const Self) -> *mut T {
282 UnsafeCell::raw_get(this.cast::<UnsafeCell<MaybeUninit<T>>>()).cast::<T>()
283 }
284}
285
286/// Types that are _always_ reference counted.
287///
288/// It allows such types to define their own custom ref increment and decrement functions.
289/// Additionally, it allows users to convert from a shared reference `&T` to an owned reference
290/// [`ARef<T>`].
291///
292/// This is usually implemented by wrappers to existing structures on the C side of the code. For
293/// Rust code, the recommendation is to use [`Arc`](crate::sync::Arc) to create reference-counted
294/// instances of a type.
295///
296/// # Safety
297///
298/// Implementers must ensure that increments to the reference count keep the object alive in memory
299/// at least until matching decrements are performed.
300///
301/// Implementers must also ensure that all instances are reference-counted. (Otherwise they
302/// won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object
303/// alive.)
304pub unsafe trait AlwaysRefCounted {
305 /// Increments the reference count on the object.
306 fn inc_ref(&self);
307
308 /// Decrements the reference count on the object.
309 ///
310 /// Frees the object when the count reaches zero.
311 ///
312 /// # Safety
313 ///
314 /// Callers must ensure that there was a previous matching increment to the reference count,
315 /// and that the object is no longer used after its reference count is decremented (as it may
316 /// result in the object being freed), unless the caller owns another increment on the refcount
317 /// (e.g., it calls [`AlwaysRefCounted::inc_ref`] twice, then calls
318 /// [`AlwaysRefCounted::dec_ref`] once).
319 unsafe fn dec_ref(obj: NonNull<Self>);
320}
321
322/// An owned reference to an always-reference-counted object.
323///
324/// The object's reference count is automatically decremented when an instance of [`ARef`] is
325/// dropped. It is also automatically incremented when a new instance is created via
326/// [`ARef::clone`].
327///
328/// # Invariants
329///
330/// The pointer stored in `ptr` is non-null and valid for the lifetime of the [`ARef`] instance. In
331/// particular, the [`ARef`] instance owns an increment on the underlying object's reference count.
332pub struct ARef<T: AlwaysRefCounted> {
333 ptr: NonNull<T>,
334 _p: PhantomData<T>,
335}
336
337// SAFETY: It is safe to send `ARef<T>` to another thread when the underlying `T` is `Sync` because
338// it effectively means sharing `&T` (which is safe because `T` is `Sync`); additionally, it needs
339// `T` to be `Send` because any thread that has an `ARef<T>` may ultimately access `T` using a
340// mutable reference, for example, when the reference count reaches zero and `T` is dropped.
341unsafe impl<T: AlwaysRefCounted + Sync + Send> Send for ARef<T> {}
342
343// SAFETY: It is safe to send `&ARef<T>` to another thread when the underlying `T` is `Sync`
344// because it effectively means sharing `&T` (which is safe because `T` is `Sync`); additionally,
345// it needs `T` to be `Send` because any thread that has a `&ARef<T>` may clone it and get an
346// `ARef<T>` on that thread, so the thread may ultimately access `T` using a mutable reference, for
347// example, when the reference count reaches zero and `T` is dropped.
348unsafe impl<T: AlwaysRefCounted + Sync + Send> Sync for ARef<T> {}
349
350impl<T: AlwaysRefCounted> ARef<T> {
351 /// Creates a new instance of [`ARef`].
352 ///
353 /// It takes over an increment of the reference count on the underlying object.
354 ///
355 /// # Safety
356 ///
357 /// Callers must ensure that the reference count was incremented at least once, and that they
358 /// are properly relinquishing one increment. That is, if there is only one increment, callers
359 /// must not use the underlying object anymore -- it is only safe to do so via the newly
360 /// created [`ARef`].
361 pub unsafe fn from_raw(ptr: NonNull<T>) -> Self {
362 // INVARIANT: The safety requirements guarantee that the new instance now owns the
363 // increment on the refcount.
364 Self {
365 ptr,
366 _p: PhantomData,
367 }
368 }
369}
370
371impl<T: AlwaysRefCounted> Clone for ARef<T> {
372 fn clone(&self) -> Self {
373 self.inc_ref();
374 // SAFETY: We just incremented the refcount above.
375 unsafe { Self::from_raw(self.ptr) }
376 }
377}
378
379impl<T: AlwaysRefCounted> Deref for ARef<T> {
380 type Target = T;
381
382 fn deref(&self) -> &Self::Target {
383 // SAFETY: The type invariants guarantee that the object is valid.
384 unsafe { self.ptr.as_ref() }
385 }
386}
387
388impl<T: AlwaysRefCounted> From<&T> for ARef<T> {
389 fn from(b: &T) -> Self {
390 b.inc_ref();
391 // SAFETY: We just incremented the refcount above.
392 unsafe { Self::from_raw(NonNull::from(b)) }
393 }
394}
395
396impl<T: AlwaysRefCounted> Drop for ARef<T> {
397 fn drop(&mut self) {
398 // SAFETY: The type invariants guarantee that the `ARef` owns the reference we're about to
399 // decrement.
400 unsafe { T::dec_ref(self.ptr) };
401 }
402}
403
404/// A sum type that always holds either a value of type `L` or `R`.
405pub enum Either<L, R> {
406 /// Constructs an instance of [`Either`] containing a value of type `L`.
407 Left(L),
408
409 /// Constructs an instance of [`Either`] containing a value of type `R`.
410 Right(R),
411}