kernel/list/arc.rs

5 //! A wrapper around `Arc` for linked lists.
10 use crate::sync::{Arc, ArcBorrow, UniqueArc};
58     /// Attempts to convert an `Arc<Self>` into an `ListArc<Self>`. Returns `true` if the
131 /// A wrapper around [`Arc`] that's guaranteed unique for the given id.
142 /// creation of new `ListArc` references from an [`Arc`] reference. Whatever strategy is used, the
152 /// While this `ListArc` is unique for the given id, there still might exist normal `Arc`
167     arc: Arc<T>,
181     // what we do for `Arc`.
222         let arc = Arc::from(unique);
223         // SAFETY: We just called `on_create_list_arc_from_unique` on an arc without a `ListArc`,
225         unsafe { Self::transmute_from_arc(arc) }
261         let arc1 = Arc::from(unique);
262         let arc2 = Arc::clone(&arc1);
264         // SAFETY: We just called `on_create_list_arc_from_unique` on an arc without a `ListArc`
277     pub fn try_from_arc(arc: Arc<T>) -> Result<Self, Arc<T>>
281         if arc.try_new_list_arc() {
284             Ok(unsafe { Self::transmute_from_arc(arc) })
286             Err(arc)
293     pub fn try_from_arc_borrow(arc: ArcBorrow<'_, T>) -> Option<Self>
297         if arc.try_new_list_arc() {
300             Some(unsafe { Self::transmute_from_arc(Arc::from(arc)) })
308     /// If it's not possible to create a new `ListArc`, then the `Arc` is dropped. This will never
310     pub fn try_from_arc_or_drop(arc: Arc<T>) -> Option<Self>
314         match Self::try_from_arc(arc) {
316             Err(arc) => Arc::into_unique_or_drop(arc).map(Self::from),
320     /// Transmutes an [`Arc`] into a `ListArc` without updating the tracking inside `T`.
327     unsafe fn transmute_from_arc(arc: Arc<T>) -> Self {
329         Self { arc }
332     /// Transmutes a `ListArc` into an [`Arc`] without updating the tracking inside `T`.
337     fn transmute_to_arc(self) -> Arc<T> {
346     /// The returned pointer is indistinguishable from pointers returned by [`Arc::into_raw`]. The
350         Arc::into_raw(Self::transmute_to_arc(self))
357     /// * `ptr` must satisfy the safety requirements of [`Arc::from_raw`].
362         // SAFETY: The pointer satisfies the safety requirements for `Arc::from_raw`.
363         let arc = unsafe { Arc::from_raw(ptr) };
366         unsafe { Self::transmute_from_arc(arc) }
369     /// Converts the `ListArc` into an [`Arc`].
371     pub fn into_arc(self) -> Arc<T> {
372         let arc = Self::transmute_to_arc(self);
374         unsafe { T::on_drop_list_arc(&arc) };
375         arc
378     /// Clone a `ListArc` into an [`Arc`].
380     pub fn clone_arc(&self) -> Arc<T> {
381         self.arc.clone()
384     /// Returns a reference to an [`Arc`] from the given [`ListArc`].
386     /// This is useful when the argument of a function call is an [`&Arc`] (e.g., in a method
389     /// [`&Arc`]: Arc
391     pub fn as_arc(&self) -> &Arc<T> {
392         &self.arc
398     /// receiver), but we have an [`Arc`] instead. Getting an [`ArcBorrow`] is free when optimised.
401         self.arc.as_arc_borrow()
407         Arc::ptr_eq(&this.arc, &other.arc)
419         self.arc.deref()
431         unsafe { T::on_drop_list_arc(&self.arc) };
435 impl<T, const ID: u64> AsRef<Arc<T>> for ListArc<T, ID>
440     fn as_ref(&self) -> &Arc<T> {
480         // INVARIANT: Pin-init initializers can't be used on an existing `Arc`, so this value will
481         // not be constructed in an `Arc` that already has a `ListArc`.