kernel/list/
arc_field.rs

1// SPDX-License-Identifier: GPL-2.0
2
3// Copyright (C) 2024 Google LLC.
4
5//! A field that is exclusively owned by a [`ListArc`].
6//!
7//! This can be used to have reference counted struct where one of the reference counted pointers
8//! has exclusive access to a field of the struct.
9//!
10//! [`ListArc`]: crate::list::ListArc
11
12use core::cell::UnsafeCell;
13
14/// A field owned by a specific [`ListArc`].
15///
16/// [`ListArc`]: crate::list::ListArc
17pub struct ListArcField<T, const ID: u64 = 0> {
18    value: UnsafeCell<T>,
19}
20
21// SAFETY: If the inner type is thread-safe, then it's also okay for `ListArc` to be thread-safe.
22unsafe impl<T: Send + Sync, const ID: u64> Send for ListArcField<T, ID> {}
23// SAFETY: If the inner type is thread-safe, then it's also okay for `ListArc` to be thread-safe.
24unsafe impl<T: Send + Sync, const ID: u64> Sync for ListArcField<T, ID> {}
25
26impl<T, const ID: u64> ListArcField<T, ID> {
27    /// Creates a new `ListArcField`.
28    pub fn new(value: T) -> Self {
29        Self {
30            value: UnsafeCell::new(value),
31        }
32    }
33
34    /// Access the value when we have exclusive access to the `ListArcField`.
35    ///
36    /// This allows access to the field using an `UniqueArc` instead of a `ListArc`.
37    pub fn get_mut(&mut self) -> &mut T {
38        self.value.get_mut()
39    }
40
41    /// Unsafely assert that you have shared access to the `ListArc` for this field.
42    ///
43    /// # Safety
44    ///
45    /// The caller must have shared access to the `ListArc<ID>` containing the struct with this
46    /// field for the duration of the returned reference.
47    pub unsafe fn assert_ref(&self) -> &T {
48        // SAFETY: The caller has shared access to the `ListArc`, so they also have shared access
49        // to this field.
50        unsafe { &*self.value.get() }
51    }
52
53    /// Unsafely assert that you have mutable access to the `ListArc` for this field.
54    ///
55    /// # Safety
56    ///
57    /// The caller must have mutable access to the `ListArc<ID>` containing the struct with this
58    /// field for the duration of the returned reference.
59    #[expect(clippy::mut_from_ref)]
60    pub unsafe fn assert_mut(&self) -> &mut T {
61        // SAFETY: The caller has exclusive access to the `ListArc`, so they also have exclusive
62        // access to this field.
63        unsafe { &mut *self.value.get() }
64    }
65}
66
67/// Defines getters for a [`ListArcField`].
68#[macro_export]
69#[doc(hidden)]
70macro_rules! define_list_arc_field_getter {
71    ($pub:vis fn $name:ident(&self $(<$id:tt>)?) -> &$typ:ty { $field:ident }
72     $($rest:tt)*
73    ) => {
74        $pub fn $name<'a>(self: &'a $crate::list::ListArc<Self $(, $id)?>) -> &'a $typ {
75            let field = &(&**self).$field;
76            // SAFETY: We have a shared reference to the `ListArc`.
77            unsafe { $crate::list::ListArcField::<$typ $(, $id)?>::assert_ref(field) }
78        }
79
80        $crate::list::define_list_arc_field_getter!($($rest)*);
81    };
82
83    ($pub:vis fn $name:ident(&mut self $(<$id:tt>)?) -> &mut $typ:ty { $field:ident }
84     $($rest:tt)*
85    ) => {
86        $pub fn $name<'a>(self: &'a mut $crate::list::ListArc<Self $(, $id)?>) -> &'a mut $typ {
87            let field = &(&**self).$field;
88            // SAFETY: We have a mutable reference to the `ListArc`.
89            unsafe { $crate::list::ListArcField::<$typ $(, $id)?>::assert_mut(field) }
90        }
91
92        $crate::list::define_list_arc_field_getter!($($rest)*);
93    };
94
95    () => {};
96}
97pub use define_list_arc_field_getter;
kernel/list/arc_field.rs

kernel/list/
arc_field.rs
