rust/kernel/list/arc.rs

Source file repositories/reference/linux-study-clean/rust/kernel/list/arc.rs

File Facts

System
Linux kernel
Corpus path
rust/kernel/list/arc.rs
Extension
.rs
Size
19427 bytes
Lines
501
Domain
Rust Kernel Layer
Bucket
Rust API Membrane
Inferred role
Rust Kernel Layer: implementation source
Status
source implementation candidate

Why This File Exists

Rust-side wrappers and abstractions around kernel C APIs, ownership contracts, allocation, synchronization, and module integration.

Dependency Surface

Detected Declarations

Annotated Snippet

unsafe fn on_create_list_arc_from_unique(self: ::core::pin::Pin<&mut Self>) {}
            unsafe fn on_drop_list_arc(&self) {}
        }
        $crate::list::impl_list_arc_safe! { $($rest)* }
    };

    (impl$({$($generics:tt)*})? ListArcSafe<$num:tt> for $t:ty {
        tracked_by $field:ident : $fty:ty;
    } $($rest:tt)*) => {
        impl$(<$($generics)*>)? $crate::list::ListArcSafe<$num> for $t {
            unsafe fn on_create_list_arc_from_unique(self: ::core::pin::Pin<&mut Self>) {
                ::pin_init::assert_pinned!($t, $field, $fty, inline);

                // SAFETY: This field is structurally pinned as per the above assertion.
                let field = unsafe {
                    ::core::pin::Pin::map_unchecked_mut(self, |me| &mut me.$field)
                };
                // SAFETY: The caller promises that there is no `ListArc`.
                unsafe {
                    <$fty as $crate::list::ListArcSafe<$num>>::on_create_list_arc_from_unique(field)
                };
            }
            unsafe fn on_drop_list_arc(&self) {
                // SAFETY: The caller promises that there is no `ListArc` reference, and also
                // promises that the tracking thinks there is a `ListArc` reference.
                unsafe { <$fty as $crate::list::ListArcSafe<$num>>::on_drop_list_arc(&self.$field) };
            }
        }
        unsafe impl$(<$($generics)*>)? $crate::list::TryNewListArc<$num> for $t
        where
            $fty: TryNewListArc<$num>,
        {
            fn try_new_list_arc(&self) -> bool {
                <$fty as $crate::list::TryNewListArc<$num>>::try_new_list_arc(&self.$field)
            }
        }
        $crate::list::impl_list_arc_safe! { $($rest)* }
    };

    () => {};
}
pub use impl_list_arc_safe;

/// A wrapper around [`Arc`] that's guaranteed unique for the given id.
///
/// The `ListArc` type can be thought of as a special reference to a refcounted object that owns the
/// permission to manipulate the `next`/`prev` pointers stored in the refcounted object. By ensuring
/// that each object has only one `ListArc` reference, the owner of that reference is assured
/// exclusive access to the `next`/`prev` pointers. When a `ListArc` is inserted into a [`List`],
/// the [`List`] takes ownership of the `ListArc` reference.
///
/// There are various strategies to ensuring that a value has only one `ListArc` reference. The
/// simplest is to convert a [`UniqueArc`] into a `ListArc`. However, the refcounted object could
/// also keep track of whether a `ListArc` exists using a boolean, which could allow for the
/// creation of new `ListArc` references from an [`Arc`] reference. Whatever strategy is used, the
/// relevant tracking is referred to as "the tracking inside `T`", and the [`ListArcSafe`] trait
/// (and its subtraits) are used to update the tracking when a `ListArc` is created or destroyed.
///
/// Note that we allow the case where the tracking inside `T` thinks that a `ListArc` exists, but
/// actually, there isn't a `ListArc`. However, we do not allow the opposite situation where a
/// `ListArc` exists, but the tracking thinks it doesn't. This is because the former can at most
/// result in us failing to create a `ListArc` when the operation could succeed, whereas the latter
/// can result in the creation of two `ListArc` references.
///
/// While this `ListArc` is unique for the given id, there still might exist normal `Arc`
/// references to the object.
///
/// # Invariants
///
/// * Each reference counted object has at most one `ListArc` for each value of `ID`.
/// * The tracking inside `T` is aware that a `ListArc` reference exists.
///
/// [`List`]: crate::list::List
#[repr(transparent)]
#[derive(core::marker::CoercePointee)]
pub struct ListArc<T, const ID: u64 = 0>
where
    T: ListArcSafe<ID> + ?Sized,
{
    arc: Arc<T>,
}

impl<T: ListArcSafe<ID>, const ID: u64> ListArc<T, ID> {
    /// Constructs a new reference counted instance of `T`.
    #[inline]
    pub fn new(contents: T, flags: Flags) -> Result<Self, AllocError> {
        Ok(Self::from(UniqueArc::new(contents, flags)?))
    }

    /// Use the given initializer to in-place initialize a `T`.

Annotation

Implementation Notes