10 //! It is different from the standard library's [`Arc`] in a few ways:
16 //! [`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::try_new(Example { a: 10, b: 20 })?;
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::try_new(Example { a: 10, b: 20 })?;
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::try_new(Example)?;
124 /// // `coerced` has type `Arc<dyn MyTrait>`.
125 /// let coerced: Arc<dyn MyTrait> = obj;
128 pub struct Arc<T: ?Sized> {  struct
140 // This is to allow [`Arc`] (and variants) to be used as the type of `self`.
141 impl<T: ?Sized> core::ops::Receiver for Arc<T> {}  implementation
143 // This is to allow coercion from `Arc<T>` to `Arc<U>` if `T` can be converted to the
145 impl<T: ?Sized + Unsize<U>, U: ?Sized> core::ops::CoerceUnsized<Arc<U>> for Arc<T> {}  implementation
147 // This is to allow `Arc<U>` to be dispatched on when `Arc<T>` can be coerced into `Arc<U>`.
148 impl<T: ?Sized + Unsize<U>, U: ?Sized> core::ops::DispatchFromDyn<Arc<U>> for Arc<T> {}  implementation
150 // SAFETY: It is safe to send `Arc<T>` to another thread when the underlying `T` is `Sync` because
152 // `T` to be `Send` because any thread that has an `Arc<T>` may ultimately access `T` using a
154 unsafe impl<T: ?Sized + Sync + Send> Send for Arc<T> {}  implementation
156 // SAFETY: It is safe to send `&Arc<T>` to another thread when the underlying `T` is `Sync`
158 // it needs `T` to be `Send` because any thread that has a `&Arc<T>` may clone it and get an
159 // `Arc<T>` on that thread, so the thread may ultimately access `T` using a mutable reference when
161 unsafe impl<T: ?Sized + Sync + Send> Sync for Arc<T> {}  implementation
163 impl<T> Arc<T> {  implementation
176         // `Arc` object.  in try_new()
193     /// This is equivalent to [`Arc<T>::pin_init`], since an [`Arc`] is always pinned.
203 impl<T: ?Sized> Arc<T> {  impl
204     /// Constructs a new [`Arc`] from an existing [`ArcInner`].
209     /// count, one of which will be owned by the new [`Arc`] instance.
212         Arc {  in from_inner()
218     /// Convert the [`Arc`] into a raw pointer.
220     /// The raw pointer has ownership of the refcount that this Arc object owned.
228     /// Recreates an [`Arc`] instance previously deconstructed via [`Arc::into_raw`].
232     /// `ptr` must have been returned by a previous call to [`Arc::into_raw`]. Additionally, it
233     /// must not be called more than once for each previous call to [`Arc::into_raw`].
251         // pointer, since it originates from a previous call to `Arc::into_raw` and is still valid.  in from_raw()
255         // SAFETY: By the safety requirements we know that `ptr` came from `Arc::into_raw`, so the  in from_raw()
256         // reference count held then will be owned by the new `Arc` object.  in from_raw()
260     /// Returns an [`ArcBorrow`] from the given [`Arc`].
263     /// receiver), but we have an [`Arc`] instead. Getting an [`ArcBorrow`] is free when optimised.
272     /// Compare whether two [`Arc`] pointers reference the same underlying object.
278 impl<T: 'static> ForeignOwnable for Arc<T> {  implementation
287         // a previous call to `Arc::into_foreign`.  in borrow()
297         // a previous call to `Arc::into_foreign`, which guarantees that `ptr` is valid and  in from_foreign()
303 impl<T: ?Sized> Deref for Arc<T> {  implementation
313 impl<T: ?Sized> AsRef<T> for Arc<T> {  implementation
319 impl<T: ?Sized> Clone for Arc<T> {  implementation
326         // SAFETY: We just incremented the refcount. This increment is now owned by the new `Arc`.  in clone()
331 impl<T: ?Sized> Drop for Arc<T> {  implementation
339         // INVARIANT: If the refcount reaches zero, there are no other instances of `Arc`, and  in drop()
352 impl<T: ?Sized> From<UniqueArc<T>> for Arc<T> {  implementation
358 impl<T: ?Sized> From<Pin<UniqueArc<T>>> for Arc<T> {  implementation
360         // SAFETY: The type invariants of `Arc` guarantee that the data is pinned.  in from()
365 /// A borrowed reference to an [`Arc`] instance.
368 /// to use just `&T`, which we can trivially get from an `Arc<T>` instance.
371 /// over `&Arc<T>` because the latter results in a double-indirection: a pointer (shared reference)
372 /// to a pointer (`Arc<T>`) to the object (`T`). An [`ArcBorrow`] eliminates this double
373 /// indirection while still allowing one to increment the refcount and getting an `Arc<T>` when/if
378 /// There are no mutable references to the underlying [`Arc`], and it remains valid for the
384 /// use kernel::sync::{Arc, ArcBorrow};
388 /// fn do_something(e: ArcBorrow<'_, Example>) -> Arc<Example> {
392 /// let obj = Arc::try_new(Example)?;
403 /// use kernel::sync::{Arc, ArcBorrow};
416 /// let obj = Arc::try_new(Example { a: 10, b: 20 })?;
460 impl<T: ?Sized> From<ArcBorrow<'_, T>> for Arc<T> {  implementation
463         // guarantees that `drop` isn't called, so it's ok that the temporary `Arc` doesn't own the  in from()
465         ManuallyDrop::new(unsafe { Arc::from_inner(b.inner) })  in from()
483 /// It is mutable and can be converted to an [`Arc`] so that it can be shared.
492 /// `Arc<Test>` object (after which point, it cannot be mutated directly). Note that `x.into()`
496 /// use kernel::sync::{Arc, UniqueArc};
503 /// fn test() -> Result<Arc<Example>> {
515 /// followed by a conversion to `Arc<Example>`. This is particularly useful when allocation happens
519 /// use kernel::sync::{Arc, UniqueArc};
526 /// fn test() -> Result<Arc<Example>> {
535 /// `Arc<Example>`; this is useful in scenarios where one needs a pinned reference during
539 /// use kernel::sync::{Arc, UniqueArc};
546 /// fn test() -> Result<Arc<Example>> {
556     inner: Arc<T>,
564             inner: Arc::try_new(value)?,  in try_new()
579             inner: unsafe { Arc::from_inner(Box::leak(inner).into()) },  in try_new_uninit()
601             // SAFETY: The new `Arc` is taking over `ptr` from `self.inner` (which won't be  in assume_init()
603             inner: unsafe { Arc::from_inner(inner.cast()) },  in assume_init()
650         // SAFETY: By the `Arc` type invariant, there is necessarily a reference to the object, so  in deref_mut()
663 impl<T: fmt::Display + ?Sized> fmt::Display for Arc<T> {  implementation
675 impl<T: fmt::Debug + ?Sized> fmt::Debug for Arc<T> {  implementation