rust/kernel/list/arc.rs

   1 // SPDX-License-Identifier: GPL-2.0
   2
   3 // Copyright (C) 2024 Google LLC.
   4
   5 //! A wrapper around `Arc` for linked lists.
   6
   7 use crate::alloc::{AllocError, Flags};
   8 use crate::prelude::*;
   9 use crate::sync::{Arc, ArcBorrow, UniqueArc};
  10 use core::marker::PhantomPinned;
  11 use core::ops::Deref;
  12 use core::pin::Pin;
  13 use core::sync::atomic::{AtomicBool, Ordering};
  14
  15 /// Declares that this type has some way to ensure that there is exactly one `ListArc` instance for
  16 /// this id.
  17 ///
  18 /// Types that implement this trait should include some kind of logic for keeping track of whether
  19 /// a [`ListArc`] exists or not. We refer to this logic as "the tracking inside `T`".
  20 ///
  21 /// We allow the case where the tracking inside `T` thinks that a [`ListArc`] exists, but actually,
  22 /// there isn't a [`ListArc`]. However, we do not allow the opposite situation where a [`ListArc`]
  23 /// exists, but the tracking thinks it doesn't. This is because the former can at most result in us
  24 /// failing to create a [`ListArc`] when the operation could succeed, whereas the latter can result
  25 /// in the creation of two [`ListArc`] references. Only the latter situation can lead to memory
  26 /// safety issues.
  27 ///
  28 /// A consequence of the above is that you may implement the tracking inside `T` by not actually
  29 /// keeping track of anything. To do this, you always claim that a [`ListArc`] exists, even if
  30 /// there isn't one. This implementation is allowed by the above rule, but it means that
  31 /// [`ListArc`] references can only be created if you have ownership of *all* references to the
  32 /// refcounted object, as you otherwise have no way of knowing whether a [`ListArc`] exists.
  33 pub trait ListArcSafe<const ID: u64 = 0> {
  34     /// Informs the tracking inside this type that it now has a [`ListArc`] reference.
  35     ///
  36     /// This method may be called even if the tracking inside this type thinks that a `ListArc`
  37     /// reference exists. (But only if that's not actually the case.)
  38     ///
  39     /// # Safety
  40     ///
  41     /// Must not be called if a [`ListArc`] already exist for this value.
  42     unsafe fn on_create_list_arc_from_unique(self: Pin<&mut Self>);
  43
  44     /// Informs the tracking inside this type that there is no [`ListArc`] reference anymore.
  45     ///
  46     /// # Safety
  47     ///
  48     /// Must only be called if there is no [`ListArc`] reference, but the tracking thinks there is.
  49     unsafe fn on_drop_list_arc(&self);
  50 }
  51
  52 /// Declares that this type is able to safely attempt to create `ListArc`s at any time.
  53 ///
  54 /// # Safety
  55 ///
  56 /// The guarantees of `try_new_list_arc` must be upheld.
  57 pub unsafe trait TryNewListArc<const ID: u64 = 0>: ListArcSafe<ID> {
  58     /// Attempts to convert an `Arc<Self>` into an `ListArc<Self>`. Returns `true` if the
  59     /// conversion was successful.
  60     ///
  61     /// This method should not be called directly. Use [`ListArc::try_from_arc`] instead.
  62     ///
  63     /// # Guarantees
  64     ///
  65     /// If this call returns `true`, then there is no [`ListArc`] pointing to this value.
  66     /// Additionally, this call will have transitioned the tracking inside `Self` from not thinking
  67     /// that a [`ListArc`] exists, to thinking that a [`ListArc`] exists.
  68     fn try_new_list_arc(&self) -> bool;
  69 }
  70
  71 /// Declares that this type supports [`ListArc`].
  72 ///
  73 /// This macro supports a few different strategies for implementing the tracking inside the type:
  74 ///
  75 /// * The `untracked` strategy does not actually keep track of whether a [`ListArc`] exists. When
  76 ///   using this strategy, the only way to create a [`ListArc`] is using a [`UniqueArc`].
  77 /// * The `tracked_by` strategy defers the tracking to a field of the struct. The user much specify
  78 ///   which field to defer the tracking to. The field must implement [`ListArcSafe`]. If the field
  79 ///   implements [`TryNewListArc`], then the type will also implement [`TryNewListArc`].
  80 ///
  81 /// The `tracked_by` strategy is usually used by deferring to a field of type
  82 /// [`AtomicTracker`]. However, it is also possible to defer the tracking to another struct
  83 /// using also using this macro.
  84 #[macro_export]
  85 macro_rules! impl_list_arc_safe {
  86     (impl$({$($generics:tt)*})? ListArcSafe<$num:tt> for $t:ty { untracked; } $($rest:tt)*) => {
  87         impl$(<$($generics)*>)? $crate::list::ListArcSafe<$num> for $t {
  88             unsafe fn on_create_list_arc_from_unique(self: ::core::pin::Pin<&mut Self>) {}
  89             unsafe fn on_drop_list_arc(&self) {}
  90         }
  91         $crate::list::impl_list_arc_safe! { $($rest)* }
  92     };
  93
  94     (impl$({$($generics:tt)*})? ListArcSafe<$num:tt> for $t:ty {
  95         tracked_by $field:ident : $fty:ty;
  96     } $($rest:tt)*) => {
  97         impl$(<$($generics)*>)? $crate::list::ListArcSafe<$num> for $t {
  98             unsafe fn on_create_list_arc_from_unique(self: ::core::pin::Pin<&mut Self>) {
  99                 $crate::assert_pinned!($t, $field, $fty, inline);
 100
 101                 // SAFETY: This field is structurally pinned as per the above assertion.
 102                 let field = unsafe {
 103                     ::core::pin::Pin::map_unchecked_mut(self, |me| &mut me.$field)
 104                 };
 105                 // SAFETY: The caller promises that there is no `ListArc`.
 106                 unsafe {
 107                     <$fty as $crate::list::ListArcSafe<$num>>::on_create_list_arc_from_unique(field)
 108                 };
 109             }
 110             unsafe fn on_drop_list_arc(&self) {
 111                 // SAFETY: The caller promises that there is no `ListArc` reference, and also
 112                 // promises that the tracking thinks there is a `ListArc` reference.
 113                 unsafe { <$fty as $crate::list::ListArcSafe<$num>>::on_drop_list_arc(&self.$field) };
 114             }
 115         }
 116         unsafe impl$(<$($generics)*>)? $crate::list::TryNewListArc<$num> for $t
 117         where
 118             $fty: TryNewListArc<$num>,
 119         {
 120             fn try_new_list_arc(&self) -> bool {
 121                 <$fty as $crate::list::TryNewListArc<$num>>::try_new_list_arc(&self.$field)
 122             }
 123         }
 124         $crate::list::impl_list_arc_safe! { $($rest)* }
 125     };
 126
 127     () => {};
 128 }
 129 pub use impl_list_arc_safe;
 130
 131 /// A wrapper around [`Arc`] that's guaranteed unique for the given id.
 132 ///
 133 /// The `ListArc` type can be thought of as a special reference to a refcounted object that owns the
 134 /// permission to manipulate the `next`/`prev` pointers stored in the refcounted object. By ensuring
 135 /// that each object has only one `ListArc` reference, the owner of that reference is assured
 136 /// exclusive access to the `next`/`prev` pointers. When a `ListArc` is inserted into a [`List`],
 137 /// the [`List`] takes ownership of the `ListArc` reference.
 138 ///
 139 /// There are various strategies to ensuring that a value has only one `ListArc` reference. The
 140 /// simplest is to convert a [`UniqueArc`] into a `ListArc`. However, the refcounted object could
 141 /// also keep track of whether a `ListArc` exists using a boolean, which could allow for the
 142 /// creation of new `ListArc` references from an [`Arc`] reference. Whatever strategy is used, the
 143 /// relevant tracking is referred to as "the tracking inside `T`", and the [`ListArcSafe`] trait
 144 /// (and its subtraits) are used to update the tracking when a `ListArc` is created or destroyed.
 145 ///
 146 /// Note that we allow the case where the tracking inside `T` thinks that a `ListArc` exists, but
 147 /// actually, there isn't a `ListArc`. However, we do not allow the opposite situation where a
 148 /// `ListArc` exists, but the tracking thinks it doesn't. This is because the former can at most
 149 /// result in us failing to create a `ListArc` when the operation could succeed, whereas the latter
 150 /// can result in the creation of two `ListArc` references.
 151 ///
 152 /// While this `ListArc` is unique for the given id, there still might exist normal `Arc`
 153 /// references to the object.
 154 ///
 155 /// # Invariants
 156 ///
 157 /// * Each reference counted object has at most one `ListArc` for each value of `ID`.
 158 /// * The tracking inside `T` is aware that a `ListArc` reference exists.
 159 ///
 160 /// [`List`]: crate::list::List
 161 #[repr(transparent)]
 162 #[cfg_attr(CONFIG_RUSTC_HAS_COERCE_POINTEE, derive(core::marker::CoercePointee))]
 163 pub struct ListArc<T, const ID: u64 = 0>
 164 where
 165     T: ListArcSafe<ID> + ?Sized,
 166 {
 167     arc: Arc<T>,
 168 }
 169
 170 impl<T: ListArcSafe<ID>, const ID: u64> ListArc<T, ID> {
 171     /// Constructs a new reference counted instance of `T`.
 172     #[inline]
 173     pub fn new(contents: T, flags: Flags) -> Result<Self, AllocError> {
 174         Ok(Self::from(UniqueArc::new(contents, flags)?))
 175     }
 176
 177     /// Use the given initializer to in-place initialize a `T`.
 178     ///
 179     /// If `T: !Unpin` it will not be able to move afterwards.
 180     // We don't implement `InPlaceInit` because `ListArc` is implicitly pinned. This is similar to
 181     // what we do for `Arc`.
 182     #[inline]
 183     pub fn pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> Result<Self, E>
 184     where
 185         E: From<AllocError>,
 186     {
 187         Ok(Self::from(UniqueArc::try_pin_init(init, flags)?))
 188     }
 189
 190     /// Use the given initializer to in-place initialize a `T`.
 191     ///
 192     /// This is equivalent to [`ListArc<T>::pin_init`], since a [`ListArc`] is always pinned.
 193     #[inline]
 194     pub fn init<E>(init: impl Init<T, E>, flags: Flags) -> Result<Self, E>
 195     where
 196         E: From<AllocError>,
 197     {
 198         Ok(Self::from(UniqueArc::try_init(init, flags)?))
 199     }
 200 }
 201
 202 impl<T, const ID: u64> From<UniqueArc<T>> for ListArc<T, ID>
 203 where
 204     T: ListArcSafe<ID> + ?Sized,
 205 {
 206     /// Convert a [`UniqueArc`] into a [`ListArc`].
 207     #[inline]
 208     fn from(unique: UniqueArc<T>) -> Self {
 209         Self::from(Pin::from(unique))
 210     }
 211 }
 212
 213 impl<T, const ID: u64> From<Pin<UniqueArc<T>>> for ListArc<T, ID>
 214 where
 215     T: ListArcSafe<ID> + ?Sized,
 216 {
 217     /// Convert a pinned [`UniqueArc`] into a [`ListArc`].
 218     #[inline]
 219     fn from(mut unique: Pin<UniqueArc<T>>) -> Self {
 220         // SAFETY: We have a `UniqueArc`, so there is no `ListArc`.
 221         unsafe { T::on_create_list_arc_from_unique(unique.as_mut()) };
 222         let arc = Arc::from(unique);
 223         // SAFETY: We just called `on_create_list_arc_from_unique` on an arc without a `ListArc`,
 224         // so we can create a `ListArc`.
 225         unsafe { Self::transmute_from_arc(arc) }
 226     }
 227 }
 228
 229 impl<T, const ID: u64> ListArc<T, ID>
 230 where
 231     T: ListArcSafe<ID> + ?Sized,
 232 {
 233     /// Creates two `ListArc`s from a [`UniqueArc`].
 234     ///
 235     /// The two ids must be different.
 236     #[inline]
 237     pub fn pair_from_unique<const ID2: u64>(unique: UniqueArc<T>) -> (Self, ListArc<T, ID2>)
 238     where
 239         T: ListArcSafe<ID2>,
 240     {
 241         Self::pair_from_pin_unique(Pin::from(unique))
 242     }
 243
 244     /// Creates two `ListArc`s from a pinned [`UniqueArc`].
 245     ///
 246     /// The two ids must be different.
 247     #[inline]
 248     pub fn pair_from_pin_unique<const ID2: u64>(
 249         mut unique: Pin<UniqueArc<T>>,
 250     ) -> (Self, ListArc<T, ID2>)
 251     where
 252         T: ListArcSafe<ID2>,
 253     {
 254         build_assert!(ID != ID2);
 255
 256         // SAFETY: We have a `UniqueArc`, so there is no `ListArc`.
 257         unsafe { <T as ListArcSafe<ID>>::on_create_list_arc_from_unique(unique.as_mut()) };
 258         // SAFETY: We have a `UniqueArc`, so there is no `ListArc`.
 259         unsafe { <T as ListArcSafe<ID2>>::on_create_list_arc_from_unique(unique.as_mut()) };
 260
 261         let arc1 = Arc::from(unique);
 262         let arc2 = Arc::clone(&arc1);
 263
 264         // SAFETY: We just called `on_create_list_arc_from_unique` on an arc without a `ListArc`
 265         // for both IDs (which are different), so we can create two `ListArc`s.
 266         unsafe {
 267             (
 268                 Self::transmute_from_arc(arc1),
 269                 ListArc::transmute_from_arc(arc2),
 270             )
 271         }
 272     }
 273
 274     /// Try to create a new `ListArc`.
 275     ///
 276     /// This fails if this value already has a `ListArc`.
 277     pub fn try_from_arc(arc: Arc<T>) -> Result<Self, Arc<T>>
 278     where
 279         T: TryNewListArc<ID>,
 280     {
 281         if arc.try_new_list_arc() {
 282             // SAFETY: The `try_new_list_arc` method returned true, so we made the tracking think
 283             // that a `ListArc` exists. This lets us create a `ListArc`.
 284             Ok(unsafe { Self::transmute_from_arc(arc) })
 285         } else {
 286             Err(arc)
 287         }
 288     }
 289
 290     /// Try to create a new `ListArc`.
 291     ///
 292     /// This fails if this value already has a `ListArc`.
 293     pub fn try_from_arc_borrow(arc: ArcBorrow<'_, T>) -> Option<Self>
 294     where
 295         T: TryNewListArc<ID>,
 296     {
 297         if arc.try_new_list_arc() {
 298             // SAFETY: The `try_new_list_arc` method returned true, so we made the tracking think
 299             // that a `ListArc` exists. This lets us create a `ListArc`.
 300             Some(unsafe { Self::transmute_from_arc(Arc::from(arc)) })
 301         } else {
 302             None
 303         }
 304     }
 305
 306     /// Try to create a new `ListArc`.
 307     ///
 308     /// If it's not possible to create a new `ListArc`, then the `Arc` is dropped. This will never
 309     /// run the destructor of the value.
 310     pub fn try_from_arc_or_drop(arc: Arc<T>) -> Option<Self>
 311     where
 312         T: TryNewListArc<ID>,
 313     {
 314         match Self::try_from_arc(arc) {
 315             Ok(list_arc) => Some(list_arc),
 316             Err(arc) => Arc::into_unique_or_drop(arc).map(Self::from),
 317         }
 318     }
 319
 320     /// Transmutes an [`Arc`] into a `ListArc` without updating the tracking inside `T`.
 321     ///
 322     /// # Safety
 323     ///
 324     /// * The value must not already have a `ListArc` reference.
 325     /// * The tracking inside `T` must think that there is a `ListArc` reference.
 326     #[inline]
 327     unsafe fn transmute_from_arc(arc: Arc<T>) -> Self {
 328         // INVARIANT: By the safety requirements, the invariants on `ListArc` are satisfied.
 329         Self { arc }
 330     }
 331
 332     /// Transmutes a `ListArc` into an [`Arc`] without updating the tracking inside `T`.
 333     ///
 334     /// After this call, the tracking inside `T` will still think that there is a `ListArc`
 335     /// reference.
 336     #[inline]
 337     fn transmute_to_arc(self) -> Arc<T> {
 338         // Use a transmute to skip destructor.
 339         //
 340         // SAFETY: ListArc is repr(transparent).
 341         unsafe { core::mem::transmute(self) }
 342     }
 343
 344     /// Convert ownership of this `ListArc` into a raw pointer.
 345     ///
 346     /// The returned pointer is indistinguishable from pointers returned by [`Arc::into_raw`]. The
 347     /// tracking inside `T` will still think that a `ListArc` exists after this call.
 348     #[inline]
 349     pub fn into_raw(self) -> *const T {
 350         Arc::into_raw(Self::transmute_to_arc(self))
 351     }
 352
 353     /// Take ownership of the `ListArc` from a raw pointer.
 354     ///
 355     /// # Safety
 356     ///
 357     /// * `ptr` must satisfy the safety requirements of [`Arc::from_raw`].
 358     /// * The value must not already have a `ListArc` reference.
 359     /// * The tracking inside `T` must think that there is a `ListArc` reference.
 360     #[inline]
 361     pub unsafe fn from_raw(ptr: *const T) -> Self {
 362         // SAFETY: The pointer satisfies the safety requirements for `Arc::from_raw`.
 363         let arc = unsafe { Arc::from_raw(ptr) };
 364         // SAFETY: The value doesn't already have a `ListArc` reference, but the tracking thinks it
 365         // does.
 366         unsafe { Self::transmute_from_arc(arc) }
 367     }
 368
 369     /// Converts the `ListArc` into an [`Arc`].
 370     #[inline]
 371     pub fn into_arc(self) -> Arc<T> {
 372         let arc = Self::transmute_to_arc(self);
 373         // SAFETY: There is no longer a `ListArc`, but the tracking thinks there is.
 374         unsafe { T::on_drop_list_arc(&arc) };
 375         arc
 376     }
 377
 378     /// Clone a `ListArc` into an [`Arc`].
 379     #[inline]
 380     pub fn clone_arc(&self) -> Arc<T> {
 381         self.arc.clone()
 382     }
 383
 384     /// Returns a reference to an [`Arc`] from the given [`ListArc`].
 385     ///
 386     /// This is useful when the argument of a function call is an [`&Arc`] (e.g., in a method
 387     /// receiver), but we have a [`ListArc`] instead.
 388     ///
 389     /// [`&Arc`]: Arc
 390     #[inline]
 391     pub fn as_arc(&self) -> &Arc<T> {
 392         &self.arc
 393     }
 394
 395     /// Returns an [`ArcBorrow`] from the given [`ListArc`].
 396     ///
 397     /// This is useful when the argument of a function call is an [`ArcBorrow`] (e.g., in a method
 398     /// receiver), but we have an [`Arc`] instead. Getting an [`ArcBorrow`] is free when optimised.
 399     #[inline]
 400     pub fn as_arc_borrow(&self) -> ArcBorrow<'_, T> {
 401         self.arc.as_arc_borrow()
 402     }
 403
 404     /// Compare whether two [`ListArc`] pointers reference the same underlying object.
 405     #[inline]
 406     pub fn ptr_eq(this: &Self, other: &Self) -> bool {
 407         Arc::ptr_eq(&this.arc, &other.arc)
 408     }
 409 }
 410
 411 impl<T, const ID: u64> Deref for ListArc<T, ID>
 412 where
 413     T: ListArcSafe<ID> + ?Sized,
 414 {
 415     type Target = T;
 416
 417     #[inline]
 418     fn deref(&self) -> &Self::Target {
 419         self.arc.deref()
 420     }
 421 }
 422
 423 impl<T, const ID: u64> Drop for ListArc<T, ID>
 424 where
 425     T: ListArcSafe<ID> + ?Sized,
 426 {
 427     #[inline]
 428     fn drop(&mut self) {
 429         // SAFETY: There is no longer a `ListArc`, but the tracking thinks there is by the type
 430         // invariants on `Self`.
 431         unsafe { T::on_drop_list_arc(&self.arc) };
 432     }
 433 }
 434
 435 impl<T, const ID: u64> AsRef<Arc<T>> for ListArc<T, ID>
 436 where
 437     T: ListArcSafe<ID> + ?Sized,
 438 {
 439     #[inline]
 440     fn as_ref(&self) -> &Arc<T> {
 441         self.as_arc()
 442     }
 443 }
 444
 445 // This is to allow coercion from `ListArc<T>` to `ListArc<U>` if `T` can be converted to the
 446 // dynamically-sized type (DST) `U`.
 447 #[cfg(not(CONFIG_RUSTC_HAS_COERCE_POINTEE))]
 448 impl<T, U, const ID: u64> core::ops::CoerceUnsized<ListArc<U, ID>> for ListArc<T, ID>
 449 where
 450     T: ListArcSafe<ID> + core::marker::Unsize<U> + ?Sized,
 451     U: ListArcSafe<ID> + ?Sized,
 452 {
 453 }
 454
 455 // This is to allow `ListArc<U>` to be dispatched on when `ListArc<T>` can be coerced into
 456 // `ListArc<U>`.
 457 #[cfg(not(CONFIG_RUSTC_HAS_COERCE_POINTEE))]
 458 impl<T, U, const ID: u64> core::ops::DispatchFromDyn<ListArc<U, ID>> for ListArc<T, ID>
 459 where
 460     T: ListArcSafe<ID> + core::marker::Unsize<U> + ?Sized,
 461     U: ListArcSafe<ID> + ?Sized,
 462 {
 463 }
 464
 465 /// A utility for tracking whether a [`ListArc`] exists using an atomic.
 466 ///
 467 /// # Invariant
 468 ///
 469 /// If the boolean is `false`, then there is no [`ListArc`] for this value.
 470 #[repr(transparent)]
 471 pub struct AtomicTracker<const ID: u64 = 0> {
 472     inner: AtomicBool,
 473     // This value needs to be pinned to justify the INVARIANT: comment in `AtomicTracker::new`.
 474     _pin: PhantomPinned,
 475 }
 476
 477 impl<const ID: u64> AtomicTracker<ID> {
 478     /// Creates a new initializer for this type.
 479     pub fn new() -> impl PinInit<Self> {
 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`.
 482         Self {
 483             inner: AtomicBool::new(false),
 484             _pin: PhantomPinned,
 485         }
 486     }
 487
 488     fn project_inner(self: Pin<&mut Self>) -> &mut AtomicBool {
 489         // SAFETY: The `inner` field is not structurally pinned, so we may obtain a mutable
 490         // reference to it even if we only have a pinned reference to `self`.
 491         unsafe { &mut Pin::into_inner_unchecked(self).inner }
 492     }
 493 }
 494
 495 impl<const ID: u64> ListArcSafe<ID> for AtomicTracker<ID> {
 496     unsafe fn on_create_list_arc_from_unique(self: Pin<&mut Self>) {
 497         // INVARIANT: We just created a ListArc, so the boolean should be true.
 498         *self.project_inner().get_mut() = true;
 499     }
 500
 501     unsafe fn on_drop_list_arc(&self) {
 502         // INVARIANT: We just dropped a ListArc, so the boolean should be false.
 503         self.inner.store(false, Ordering::Release);
 504     }
 505 }
 506
 507 // SAFETY: If this method returns `true`, then by the type invariant there is no `ListArc` before
 508 // this call, so it is okay to create a new `ListArc`.
 509 //
 510 // The acquire ordering will synchronize with the release store from the destruction of any
 511 // previous `ListArc`, so if there was a previous `ListArc`, then the destruction of the previous
 512 // `ListArc` happens-before the creation of the new `ListArc`.
 513 unsafe impl<const ID: u64> TryNewListArc<ID> for AtomicTracker<ID> {
 514     fn try_new_list_arc(&self) -> bool {
 515         // INVARIANT: If this method returns true, then the boolean used to be false, and is no
 516         // longer false, so it is okay for the caller to create a new [`ListArc`].
 517         self.inner
 518             .compare_exchange(false, true, Ordering::Acquire, Ordering::Relaxed)
 519             .is_ok()
 520     }
 521 }