1 // SPDX-License-Identifier: GPL-2.0
3 //! A reference-counted pointer.
5 //! This module implements a way for users to create reference-counted objects and pointers to
7 //! underlying object when it reaches zero. It is also safe to use concurrently from multiple
16 //! [`Arc`]: https://doc.rust-lang.org/std/sync/struct.Arc.html
39 /// A reference-counted pointer to an instance of `T`.
42 /// when they are dropped. When the count reaches zero, the underlying `T` is also dropped.
46 /// The reference count on an instance of [`Arc`] is always non-zero.
59 /// // Create a ref-counted instance of `Example`.
75 /// // The refcount drops to zero when `cloned` goes out of scope, and the memory is freed.
144 // dynamically-sized type (DST) `U`.
153 // mutable reference when the reference count reaches zero and `T` is dropped.
160 // the reference count reaches zero and `T` is dropped.
165     pub fn try_new(contents: T) -> Result<Self, AllocError> {  in try_new()
166         // INVARIANT: The refcount is initialised to a non-zero value.  in try_new()
180     /// Use the given initializer to in-place initialize a `T`.
184     pub fn pin_init<E>(init: impl PinInit<T, E>) -> error::Result<Self>  in pin_init()
191     /// Use the given initializer to in-place initialize a `T`.
195     pub fn init<E>(init: impl Init<T, E>) -> error::Result<Self>  in init()
208     /// The caller must ensure that `inner` points to a valid location and has a non-zero reference
210     unsafe fn from_inner(inner: NonNull<ArcInner<T>>) -> Self {  in from_inner()
223     pub fn as_arc_borrow(&self) -> ArcBorrow<'_, T> {  in as_arc_borrow()
231     pub fn ptr_eq(this: &Self, other: &Self) -> bool {  in ptr_eq()
239     fn into_foreign(self) -> *const core::ffi::c_void {  in into_foreign()
243     unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> ArcBorrow<'a, T> {  in borrow()
253     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {  in from_foreign()
264     fn deref(&self) -> &Self::Target {  in deref()
272     fn as_ref(&self) -> &T {  in as_ref()
278     fn clone(&self) -> Self {  in clone()
279         // INVARIANT: C `refcount_inc` saturates the refcount, so it cannot overflow to zero.  in clone()
292         // touch `refcount` after it's decremented to a non-zero value because another thread/CPU  in drop()
293         // may concurrently decrement it to zero and free it. It is ok to have a raw pointer to  in drop()
297         // INVARIANT: If the refcount reaches zero, there are no other instances of `Arc`, and  in drop()
302             // The count reached zero, we must free the memory.  in drop()
304             // SAFETY: The pointer was initialised from the result of `Box::leak`.  in drop()
311     fn from(item: UniqueArc<T>) -> Self {  in from()
317     fn from(item: Pin<UniqueArc<T>>) -> Self {  in from()
329 /// over `&Arc<T>` because the latter results in a double-indirection: a pointer (shared reference)
346 /// fn do_something(e: ArcBorrow<'_, Example>) -> Arc<Example> {
394     fn clone(&self) -> Self {  in clone()
409     unsafe fn new(inner: NonNull<ArcInner<T>>) -> Self {  in new()
419     fn from(b: ArcBorrow<'_, T>) -> Self {  in from()
420         // SAFETY: The existence of `b` guarantees that the refcount is non-zero. `ManuallyDrop`  in from()
432     fn deref(&self) -> &Self::Target {  in deref()
461 /// fn test() -> Result<Arc<Example>> {
471 /// In the following example we first allocate memory for a ref-counted `Example` but we don't
484 /// fn test() -> Result<Arc<Example>> {
504 /// fn test() -> Result<Arc<Example>> {
519     pub fn try_new(value: T) -> Result<Self, AllocError> {  in try_new()
521             // INVARIANT: The newly-created object has a ref-count of 1.  in try_new()
526     /// Tries to allocate a new [`UniqueArc`] instance whose contents are not initialised yet.
527     pub fn try_new_uninit() -> Result<UniqueArc<MaybeUninit<T>>, AllocError> {  in try_new_uninit()
528         // INVARIANT: The refcount is initialised to a non-zero value.  in try_new_uninit()
532             data <- init::uninit::<T, AllocError>(),  in try_new_uninit()
535             // INVARIANT: The newly-created object has a ref-count of 1.  in try_new_uninit()
544     pub fn write(mut self, value: T) -> UniqueArc<T> {  in write()
556     pub unsafe fn assume_init(self) -> UniqueArc<T> {  in assume_init()
566     pub fn init_with<E>(mut self, init: impl Init<T, E>) -> core::result::Result<UniqueArc<T>, E> {  in init_with()
575     /// Pin-initialize `self` using the given pin-initializer.
579     ) -> core::result::Result<Pin<UniqueArc<T>>, E> {  in pin_init_with()
591     fn from(obj: UniqueArc<T>) -> Self {  in from()
601     fn deref(&self) -> &Self::Target {  in deref()
607     fn deref_mut(&mut self) -> &mut Self::Target {  in deref_mut()
616     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {  in fmt()
622     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {  in fmt()
628     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {  in fmt()
634     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {  in fmt()