10 //! It is different from the standard library's [`Arc`] in a few ways:
15 //! 5. The object in [`Arc`] is pinned implicitly.
17 //! [`Arc`]: https://doc.rust-lang.org/std/sync/struct.Arc.html
41 /// The reference count is incremented when new instances of [`Arc`] are created, and decremented
46 /// The reference count on an instance of [`Arc`] is always non-zero.
47 /// The object pointed to by [`Arc`] is always pinned.
52 /// use kernel::sync::Arc;
60 /// let obj = Arc::new(Example { a: 10, b: 20 }, GFP_KERNEL)?;
79 /// Using `Arc<T>` as the type of `self`:
82 /// use kernel::sync::Arc;
90 ///     fn take_over(self: Arc<Self>) {
94 ///     fn use_reference(self: &Arc<Self>) {
99 /// let obj = Arc::new(Example { a: 10, b: 20 }, GFP_KERNEL)?;
105 /// Coercion from `Arc<Example>` to `Arc<dyn MyTrait>`:
108 /// use kernel::sync::{Arc, ArcBorrow};
111 ///     // Trait has a function whose `self` type is `Arc<Self>`.
112 ///     fn example1(self: Arc<Self>) {}
121 /// // `obj` has type `Arc<Example>`.
122 /// let obj: Arc<Example> = Arc::new(Example, GFP_KERNEL)?;
124 /// // `coerced` has type `Arc<dyn MyTrait>`.
125 /// let coerced: Arc<dyn MyTrait> = obj;
130 pub struct Arc<T: ?Sized> {  struct
132     // NB: this informs dropck that objects of type `ArcInner<T>` may be used in `<Arc<T> as
134     // `<Arc<T> as Drop>::drop` and the distinction between `T` and `ArcInner<T>` is not presently
151     /// Converts a pointer to the contents of an [`Arc`] into a pointer to the [`ArcInner`].
155     /// `ptr` must have been returned by a previous call to [`Arc::into_raw`], and the `Arc` must
173         // pointer, since it originates from a previous call to `Arc::into_raw` on an `Arc` that is  in container_of()
183 // This is to allow coercion from `Arc<T>` to `Arc<U>` if `T` can be converted to the
186 impl<T: ?Sized + core::marker::Unsize<U>, U: ?Sized> core::ops::CoerceUnsized<Arc<U>> for Arc<T> {}  implementation
188 // This is to allow `Arc<U>` to be dispatched on when `Arc<T>` can be coerced into `Arc<U>`.
190 impl<T: ?Sized + core::marker::Unsize<U>, U: ?Sized> core::ops::DispatchFromDyn<Arc<U>> for Arc<T> …  implementation
192 // SAFETY: It is safe to send `Arc<T>` to another thread when the underlying `T` is `Sync` because
194 // `T` to be `Send` because any thread that has an `Arc<T>` may ultimately access `T` using a
196 unsafe impl<T: ?Sized + Sync + Send> Send for Arc<T> {}  implementation
198 // SAFETY: It is safe to send `&Arc<T>` to another thread when the underlying `T` is `Sync`
200 // it needs `T` to be `Send` because any thread that has a `&Arc<T>` may clone it and get an
201 // `Arc<T>` on that thread, so the thread may ultimately access `T` using a mutable reference when
203 unsafe impl<T: ?Sized + Sync + Send> Sync for Arc<T> {}  implementation
205 impl<T> Arc<T> {  impl
219         // `Arc` object.  in new()
224 impl<T: ?Sized> Arc<T> {  impl
225     /// Constructs a new [`Arc`] from an existing [`ArcInner`].
230     /// count, one of which will be owned by the new [`Arc`] instance.
233         Arc {  in from_inner()
239     /// Convert the [`Arc`] into a raw pointer.
241     /// The raw pointer has ownership of the refcount that this Arc object owned.
249     /// Recreates an [`Arc`] instance previously deconstructed via [`Arc::into_raw`].
253     /// `ptr` must have been returned by a previous call to [`Arc::into_raw`]. Additionally, it
254     /// must not be called more than once for each previous call to [`Arc::into_raw`].
257         // `Arc` that is still valid.  in from_raw()
260         // SAFETY: By the safety requirements we know that `ptr` came from `Arc::into_raw`, so the  in from_raw()
261         // reference count held then will be owned by the new `Arc` object.  in from_raw()
265     /// Returns an [`ArcBorrow`] from the given [`Arc`].
268     /// receiver), but we have an [`Arc`] instead. Getting an [`ArcBorrow`] is free when optimised.
277     /// Compare whether two [`Arc`] pointers reference the same underlying object.
282     /// Converts this [`Arc`] into a [`UniqueArc`], or destroys it if it is not unique.
284     /// When this destroys the `Arc`, it does so while properly avoiding races. This means that
290     /// use kernel::sync::{Arc, UniqueArc};
292     /// let arc = Arc::new(42, GFP_KERNEL)?;
293     /// let unique_arc = arc.into_unique_or_drop();
295     /// // The above conversion should succeed since refcount of `arc` is 1.
304     /// use kernel::sync::{Arc, UniqueArc};
306     /// let arc = Arc::new(42, GFP_KERNEL)?;
307     /// let another = arc.clone();
309     /// let unique_arc = arc.into_unique_or_drop();
311     /// // The above conversion should fail since refcount of `arc` is >1.
322         // If the refcount reaches a non-zero value, then we have destroyed this `Arc` and will  in into_unique_or_drop()
323         // return without further touching the `Arc`. If the refcount reaches zero, then there are  in into_unique_or_drop()
329             // SAFETY: We have exclusive access to the arc, so we can perform unsynchronized  in into_unique_or_drop()
333             // INVARIANT: We own the only refcount to this arc, so we may create a `UniqueArc`. We  in into_unique_or_drop()
334             // must pin the `UniqueArc` because the values was previously in an `Arc`, and they pin  in into_unique_or_drop()
345 impl<T: 'static> ForeignOwnable for Arc<T> {  implementation
359         // a previous call to `Arc::into_foreign`, which guarantees that `ptr` is valid and  in from_foreign()
381 impl<T: ?Sized> Deref for Arc<T> {  implementation
391 impl<T: ?Sized> AsRef<T> for Arc<T> {  implementation
397 impl<T: ?Sized> Clone for Arc<T> {  implementation
408         // SAFETY: We just incremented the refcount. This increment is now owned by the new `Arc`.  in clone()
413 impl<T: ?Sized> Drop for Arc<T> {  implementation
421         // INVARIANT: If the refcount reaches zero, there are no other instances of `Arc`, and  in drop()
434 impl<T: ?Sized> From<UniqueArc<T>> for Arc<T> {  implementation
440 impl<T: ?Sized> From<Pin<UniqueArc<T>>> for Arc<T> {  implementation
442         // SAFETY: The type invariants of `Arc` guarantee that the data is pinned.  in from()
447 /// A borrowed reference to an [`Arc`] instance.
450 /// to use just `&T`, which we can trivially get from an [`Arc<T>`] instance.
453 /// over `&Arc<T>` because the latter results in a double-indirection: a pointer (shared reference)
454 /// to a pointer ([`Arc<T>`]) to the object (`T`). An [`ArcBorrow`] eliminates this double
455 /// indirection while still allowing one to increment the refcount and getting an [`Arc<T>`] when/if
460 /// There are no mutable references to the underlying [`Arc`], and it remains valid for the
466 /// use kernel::sync::{Arc, ArcBorrow};
470 /// fn do_something(e: ArcBorrow<'_, Example>) -> Arc<Example> {
474 /// let obj = Arc::new(Example, GFP_KERNEL)?;
485 /// use kernel::sync::{Arc, ArcBorrow};
498 /// let obj = Arc::new(Example { a: 10, b: 20 }, GFP_KERNEL)?;
541     /// Creates an [`ArcBorrow`] to an [`Arc`] that has previously been deconstructed with
542     /// [`Arc::into_raw`].
546     /// * The provided pointer must originate from a call to [`Arc::into_raw`].
553         // `Arc` that is still valid.  in from_raw()
563 impl<T: ?Sized> From<ArcBorrow<'_, T>> for Arc<T> {  implementation
566         // guarantees that `drop` isn't called, so it's ok that the temporary `Arc` doesn't own the  in from()
568         ManuallyDrop::new(unsafe { Arc::from_inner(b.inner) })  in from()
586 /// It is mutable and can be converted to an [`Arc`] so that it can be shared.
595 /// `Arc<Test>` object (after which point, it cannot be mutated directly). Note that `x.into()`
599 /// use kernel::sync::{Arc, UniqueArc};
606 /// fn test() -> Result<Arc<Example>> {
618 /// followed by a conversion to `Arc<Example>`. This is particularly useful when allocation happens
622 /// use kernel::sync::{Arc, UniqueArc};
629 /// fn test() -> Result<Arc<Example>> {
638 /// `Arc<Example>`; this is useful in scenarios where one needs a pinned reference during
642 /// use kernel::sync::{Arc, UniqueArc};
649 /// fn test() -> Result<Arc<Example>> {
659     inner: Arc<T>,
667             inner: Arc::new(value, flags)?,  in new()
685             inner: unsafe { Arc::from_inner(KBox::leak(inner).into()) },  in new_uninit()
707             // SAFETY: The new `Arc` is taking over `ptr` from `self.inner` (which won't be  in assume_init()
709             inner: unsafe { Arc::from_inner(inner.cast()) },  in assume_init()
756         // SAFETY: By the `Arc` type invariant, there is necessarily a reference to the object, so  in deref_mut()
769 impl<T: fmt::Display + ?Sized> fmt::Display for Arc<T> {  implementation
781 impl<T: fmt::Debug + ?Sized> fmt::Debug for Arc<T> {  implementation