pub struct ListArc<T, const ID: u64 = 0>where
T: ListArcSafe<ID> + ?Sized,{ /* private fields */ }Expand description
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
ListArcfor each value ofID. - The tracking inside
Tis aware that aListArcreference exists.
Implementations§
Source§impl<T: ListArcSafe<ID>, const ID: u64> ListArc<T, ID>
impl<T: ListArcSafe<ID>, const ID: u64> ListArc<T, ID>
Sourcepub fn new(contents: T, flags: Flags) -> Result<Self, AllocError>
pub fn new(contents: T, flags: Flags) -> Result<Self, AllocError>
Constructs a new reference counted instance of T.
Sourcepub fn pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> Result<Self, E>where
E: From<AllocError>,
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.
Sourcepub fn init<E>(init: impl Init<T, E>, flags: Flags) -> Result<Self, E>where
E: From<AllocError>,
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.
Source§impl<T, const ID: u64> ListArc<T, ID>where
T: ListArcSafe<ID> + ?Sized,
impl<T, const ID: u64> ListArc<T, ID>where
T: ListArcSafe<ID> + ?Sized,
Sourcepub fn pair_from_unique<const ID2: u64>(
unique: UniqueArc<T>,
) -> (Self, ListArc<T, ID2>)where
T: ListArcSafe<ID2>,
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.
Sourcepub fn pair_from_pin_unique<const ID2: u64>(
unique: Pin<UniqueArc<T>>,
) -> (Self, ListArc<T, ID2>)where
T: ListArcSafe<ID2>,
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.
Sourcepub fn try_from_arc(arc: Arc<T>) -> Result<Self, Arc<T>>where
T: TryNewListArc<ID>,
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.
Sourcepub fn try_from_arc_borrow(arc: ArcBorrow<'_, T>) -> Option<Self>where
T: TryNewListArc<ID>,
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.
Sourcepub fn try_from_arc_or_drop(arc: Arc<T>) -> Option<Self>where
T: TryNewListArc<ID>,
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.
Sourcepub fn into_raw(self) -> *const T
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.
Sourcepub unsafe fn from_raw(ptr: *const T) -> Self
pub unsafe fn from_raw(ptr: *const T) -> Self
Take ownership of the ListArc from a raw pointer.
§Safety
ptrmust satisfy the safety requirements ofArc::from_raw.- The value must not already have a
ListArcreference. - The tracking inside
Tmust think that there is aListArcreference.