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
43 /// The reference count is incremented when new instances of [`Arc`] are created, and decremented
48 /// The reference count on an instance of [`Arc`] is always non-zero.
49 /// The object pointed to by [`Arc`] is always pinned.
54 /// use kernel::sync::Arc;
62 /// let obj = Arc::new(Example { a: 10, b: 20 }, GFP_KERNEL)?;
81 /// Using `Arc<T>` as the type of `self`:
84 /// use kernel::sync::Arc;
92 ///     fn take_over(self: Arc<Self>) {
96 ///     fn use_reference(self: &Arc<Self>) {
101 /// let obj = Arc::new(Example { a: 10, b: 20 }, GFP_KERNEL)?;
107 /// Coercion from `Arc<Example>` to `Arc<dyn MyTrait>`:
110 /// use kernel::sync::{Arc, ArcBorrow};
113 ///     // Trait has a function whose `self` type is `Arc<Self>`.
114 ///     fn example1(self: Arc<Self>) {}
123 /// // `obj` has type `Arc<Example>`.
124 /// let obj: Arc<Example> = Arc::new(Example, GFP_KERNEL)?;
126 /// // `coerced` has type `Arc<dyn MyTrait>`.
127 /// let coerced: Arc<dyn MyTrait> = obj;
132 pub struct Arc<T: ?Sized> {  struct
134     // NB: this informs dropck that objects of type `ArcInner<T>` may be used in `<Arc<T> as
136     // `<Arc<T> as Drop>::drop` and the distinction between `T` and `ArcInner<T>` is not presently
153     /// Converts a pointer to the contents of an [`Arc`] into a pointer to the [`ArcInner`].
157     /// `ptr` must have been returned by a previous call to [`Arc::into_raw`], and the `Arc` must
175         // pointer, since it originates from a previous call to `Arc::into_raw` on an `Arc` that is  in container_of()
185 // This is to allow coercion from `Arc<T>` to `Arc<U>` if `T` can be converted to the
188 impl<T: ?Sized + core::marker::Unsize<U>, U: ?Sized> core::ops::CoerceUnsized<Arc<U>> for Arc<T> {}  implementation
190 // This is to allow `Arc<U>` to be dispatched on when `Arc<T>` can be coerced into `Arc<U>`.
192 impl<T: ?Sized + core::marker::Unsize<U>, U: ?Sized> core::ops::DispatchFromDyn<Arc<U>> for Arc<T> …  implementation
194 // SAFETY: It is safe to send `Arc<T>` to another thread when the underlying `T` is `Sync` because
196 // `T` to be `Send` because any thread that has an `Arc<T>` may ultimately access `T` using a
198 unsafe impl<T: ?Sized + Sync + Send> Send for Arc<T> {}  implementation
200 // SAFETY: It is safe to send `&Arc<T>` to another thread when the underlying `T` is `Sync`
202 // it needs `T` to be `Send` because any thread that has a `&Arc<T>` may clone it and get an
203 // `Arc<T>` on that thread, so the thread may ultimately access `T` using a mutable reference when
205 unsafe impl<T: ?Sized + Sync + Send> Sync for Arc<T> {}  implementation
207 impl<T> InPlaceInit<T> for Arc<T> {  implementation
227 impl<T> Arc<T> {  implementation
240         // `Arc` object.  in new()
248 impl<T: ?Sized> Arc<T> {  implementation
249     /// Constructs a new [`Arc`] from an existing [`ArcInner`].
254     /// count, one of which will be owned by the new [`Arc`] instance.
257         Arc {  in from_inner()
263     /// Convert the [`Arc`] into a raw pointer.
265     /// The raw pointer has ownership of the refcount that this Arc object owned.
273     /// Return a raw pointer to the data in this arc.
282     /// Recreates an [`Arc`] instance previously deconstructed via [`Arc::into_raw`].
286     /// `ptr` must have been returned by a previous call to [`Arc::into_raw`]. Additionally, it
287     /// must not be called more than once for each previous call to [`Arc::into_raw`].
290         // `Arc` that is still valid.  in from_raw()
293         // SAFETY: By the safety requirements we know that `ptr` came from `Arc::into_raw`, so the  in from_raw()
294         // reference count held then will be owned by the new `Arc` object.  in from_raw()
298     /// Returns an [`ArcBorrow`] from the given [`Arc`].
301     /// receiver), but we have an [`Arc`] instead. Getting an [`ArcBorrow`] is free when optimised.
310     /// Compare whether two [`Arc`] pointers reference the same underlying object.
315     /// Converts this [`Arc`] into a [`UniqueArc`], or destroys it if it is not unique.
317     /// When this destroys the `Arc`, it does so while properly avoiding races. This means that
323     /// use kernel::sync::{Arc, UniqueArc};
325     /// let arc = Arc::new(42, GFP_KERNEL)?;
326     /// let unique_arc = Arc::into_unique_or_drop(arc);
328     /// // The above conversion should succeed since refcount of `arc` is 1.
337     /// use kernel::sync::{Arc, UniqueArc};
339     /// let arc = Arc::new(42, GFP_KERNEL)?;
340     /// let another = arc.clone();
342     /// let unique_arc = Arc::into_unique_or_drop(arc);
344     /// // The above conversion should fail since refcount of `arc` is >1.
355         // If the refcount reaches a non-zero value, then we have destroyed this `Arc` and will  in into_unique_or_drop()
356         // return without further touching the `Arc`. If the refcount reaches zero, then there are  in into_unique_or_drop()
361             // INVARIANT: We own the only refcount to this arc, so we may create a `UniqueArc`. We  in into_unique_or_drop()
362             // must pin the `UniqueArc` because the values was previously in an `Arc`, and they pin  in into_unique_or_drop()
375 unsafe impl<T: 'static> ForeignOwnable for Arc<T> {  implementation
391         // a previous call to `Arc::into_foreign`, which guarantees that `ptr` is valid and  in from_foreign()
413 impl<T: ?Sized> Deref for Arc<T> {  implementation
423 impl<T: ?Sized> AsRef<T> for Arc<T> {  implementation
433 /// # use kernel::sync::Arc;
440 /// let arc = Arc::new(1, GFP_KERNEL)?;
441 /// let shared = Foo(arc.clone());
448 impl<T: ?Sized> Borrow<T> for Arc<T> {  implementation
454 impl<T: ?Sized> Clone for Arc<T> {  implementation
461         // SAFETY: We just incremented the refcount. This increment is now owned by the new `Arc`.  in clone()
466 impl<T: ?Sized> Drop for Arc<T> {  implementation
468         // INVARIANT: If the refcount reaches zero, there are no other instances of `Arc`, and  in drop()
481 impl<T: ?Sized> From<UniqueArc<T>> for Arc<T> {  implementation
487 impl<T: ?Sized> From<Pin<UniqueArc<T>>> for Arc<T> {  implementation
489         // SAFETY: The type invariants of `Arc` guarantee that the data is pinned.  in from()
494 /// A borrowed reference to an [`Arc`] instance.
497 /// to use just `&T`, which we can trivially get from an [`Arc<T>`] instance.
500 /// over `&Arc<T>` because the latter results in a double-indirection: a pointer (shared reference)
501 /// to a pointer ([`Arc<T>`]) to the object (`T`). An [`ArcBorrow`] eliminates this double
502 /// indirection while still allowing one to increment the refcount and getting an [`Arc<T>`] when/if
507 /// There are no mutable references to the underlying [`Arc`], and it remains valid for the
513 /// use kernel::sync::{Arc, ArcBorrow};
517 /// fn do_something(e: ArcBorrow<'_, Example>) -> Arc<Example> {
521 /// let obj = Arc::new(Example, GFP_KERNEL)?;
532 /// use kernel::sync::{Arc, ArcBorrow};
545 /// let obj = Arc::new(Example { a: 10, b: 20 }, GFP_KERNEL)?;
588     /// Creates an [`ArcBorrow`] to an [`Arc`] that has previously been deconstructed with
589     /// [`Arc::into_raw`] or [`Arc::as_ptr`].
593     /// * The provided pointer must originate from a call to [`Arc::into_raw`] or [`Arc::as_ptr`].
600         // `Arc` that is still valid.  in from_raw()
610 impl<T: ?Sized> From<ArcBorrow<'_, T>> for Arc<T> {  implementation
613         // guarantees that `drop` isn't called, so it's ok that the temporary `Arc` doesn't own the  in from()
615         ManuallyDrop::new(unsafe { Arc::from_inner(b.inner) })  in from()
633 /// It is mutable and can be converted to an [`Arc`] so that it can be shared.
642 /// `Arc<Test>` object (after which point, it cannot be mutated directly). Note that `x.into()`
646 /// use kernel::sync::{Arc, UniqueArc};
653 /// fn test() -> Result<Arc<Example>> {
665 /// followed by a conversion to `Arc<Example>`. This is particularly useful when allocation happens
669 /// use kernel::sync::{Arc, UniqueArc};
676 /// fn test() -> Result<Arc<Example>> {
685 /// `Arc<Example>`; this is useful in scenarios where one needs a pinned reference during
689 /// use kernel::sync::{Arc, UniqueArc};
696 /// fn test() -> Result<Arc<Example>> {
706     inner: Arc<T>,
756             inner: Arc::new(value, flags)?,  in new()
773             inner: unsafe { Arc::from_inner(KBox::leak(inner).into()) },  in new_uninit()
795             // SAFETY: The new `Arc` is taking over `ptr` from `self.inner` (which won't be  in assume_init()
797             inner: unsafe { Arc::from_inner(inner.cast()) },  in assume_init()
844         // SAFETY: By the `Arc` type invariant, there is necessarily a reference to the object, so  in deref_mut()
862 /// let arc = UniqueArc::new(1, GFP_KERNEL)?;
863 /// let shared = Foo(arc);
887 /// let arc = UniqueArc::new(1, GFP_KERNEL)?;
888 /// let shared = Foo(arc);
907 impl<T: fmt::Display + ?Sized> fmt::Display for Arc<T> {  implementation
919 impl<T: fmt::Debug + ?Sized> fmt::Debug for Arc<T> {  implementation