Struct kernel::list::ListArc

pub struct ListArc<T, const ID: u64 = 0>
where
    T: ListArcSafe<ID> + ?Sized,
{ /* private fields */ }

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.

Implementations

impl<T: ListArcSafe<ID>, const ID: u64> ListArc<T, ID>

pub fn new(contents: T, flags: Flags) -> Result<Self, AllocError>

Constructs a new reference counted instance of T.

pub fn pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> Result<Self, E>

where E: From<AllocError>,

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

If T: !Unpin it will not be able to move afterwards.

pub fn init<E>(init: impl Init<T, E>, flags: Flags) -> Result<Self, E>

where E: From<AllocError>,

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

This is equivalent to ListArc<T>::pin_init, since a ListArc is always pinned.

impl<T, const ID: u64> ListArc<T, ID>

where T: ListArcSafe<ID> + ?Sized,

pub fn pair_from_unique<const ID2: u64>( unique: UniqueArc<T> ) -> (Self, ListArc<T, ID2>)

where T: ListArcSafe<ID2>,

Creates two ListArcs from a UniqueArc.

The two ids must be different.

pub fn pair_from_pin_unique<const ID2: u64>( unique: Pin<UniqueArc<T>> ) -> (Self, ListArc<T, ID2>)

where T: ListArcSafe<ID2>,

Creates two ListArcs from a pinned UniqueArc.

The two ids must be different.

pub fn try_from_arc(arc: Arc<T>) -> Result<Self, Arc<T>>

where T: TryNewListArc<ID>,

Try to create a new ListArc.

This fails if this value already has a ListArc.

pub fn try_from_arc_borrow(arc: ArcBorrow<'_, T>) -> Option<Self>

where T: TryNewListArc<ID>,

Try to create a new ListArc.

This fails if this value already has a ListArc.

pub fn try_from_arc_or_drop(arc: Arc<T>) -> Option<Self>

where T: TryNewListArc<ID>,

Try to create a new ListArc.

If it’s not possible to create a new ListArc, then the Arc is dropped. This will never run the destructor of the value.

pub fn into_raw(self) -> *const T

Convert ownership of this ListArc into a raw pointer.

The returned pointer is indistinguishable from pointers returned by Arc::into_raw. The tracking inside T will still think that a ListArc exists after this call.

pub unsafe fn from_raw(ptr: *const T) -> Self

Take ownership of the ListArc from a raw pointer.

Safety

• ptr must satisfy the safety requirements of Arc::from_raw.
• The value must not already have a ListArc reference.
• The tracking inside T must think that there is a ListArc reference.

pub fn into_arc(self) -> Arc<T>

Converts the ListArc into an Arc.

pub fn clone_arc(&self) -> Arc<T>

Clone a ListArc into an Arc.

pub fn as_arc(&self) -> &Arc<T>

Returns a reference to an Arc from the given ListArc.

This is useful when the argument of a function call is an &Arc (e.g., in a method receiver), but we have a ListArc instead.

pub fn as_arc_borrow(&self) -> ArcBorrow<'_, T>

Returns an ArcBorrow from the given ListArc.

This is useful when the argument of a function call is an ArcBorrow (e.g., in a method receiver), but we have an Arc instead. Getting an ArcBorrow is free when optimised.

pub fn ptr_eq(this: &Self, other: &Self) -> bool

Compare whether two ListArc pointers reference the same underlying object.

Trait Implementations

impl<T, const ID: u64> AsRef<Arc<T>> for ListArc<T, ID>

where T: ListArcSafe<ID> + ?Sized,

fn as_ref(&self) -> &Arc<T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T, const ID: u64> Deref for ListArc<T, ID>

where T: ListArcSafe<ID> + ?Sized,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T, const ID: u64> Drop for ListArc<T, ID>

where T: ListArcSafe<ID> + ?Sized,

fn drop(&mut self)

Executes the destructor for this type.

impl<T, const ID: u64> From<Pin<UniqueArc<T>>> for ListArc<T, ID>

where T: ListArcSafe<ID> + ?Sized,

fn from(unique: Pin<UniqueArc<T>>) -> Self

Convert a pinned UniqueArc into a ListArc.

impl<T, const ID: u64> From<UniqueArc<T>> for ListArc<T, ID>

where T: ListArcSafe<ID> + ?Sized,

fn from(unique: UniqueArc<T>) -> Self

Convert a UniqueArc into a ListArc.

impl<T, U, const ID: u64> CoerceUnsized<ListArc<U, ID>> for ListArc<T, ID>

where T: ListArcSafe<ID> + Unsize<U> + ?Sized, U: ListArcSafe<ID> + ?Sized,

impl<T, U, const ID: u64> DispatchFromDyn<ListArc<U, ID>> for ListArc<T, ID>

where T: ListArcSafe<ID> + Unsize<U> + ?Sized, U: ListArcSafe<ID> + ?Sized,