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
16 //! [`Arc`]: https://doc.rust-lang.org/std/sync/struct.Arc.html
39 /// A reference-counted pointer to an instance of `T`.
46 /// The reference count on an instance of [`Arc`] is always non-zero.
59 /// // Create a ref-counted instance of `Example`.
144 // dynamically-sized type (DST) `U`.
150 // SAFETY: It is safe to send `Arc<T>` to another thread when the underlying `T` is `Sync` because
156 // SAFETY: It is safe to send `&Arc<T>` to another thread when the underlying `T` is `Sync`
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()
168             // SAFETY: There are no safety requirements for this FFI call.  in try_new()
175         // SAFETY: We just created `inner` with a reference count of 1, which is owned by the new  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()
206     /// # Safety
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()
211         // INVARIANT: By the safety requirements, the invariants hold.  in from_inner()
223     pub fn as_arc_borrow(&self) -> ArcBorrow<'_, T> {  in as_arc_borrow()
224         // SAFETY: The constraint that the lifetime of the shared reference must outlive that of  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()
244         // SAFETY: By the safety requirement of this function, we know that `ptr` came from  in borrow()
248         // SAFETY: The safety requirements of `from_foreign` ensure that the object remains alive  in borrow()
253     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {  in from_foreign()
254         // SAFETY: By the safety requirement of this function, we know that `ptr` came from  in from_foreign()
264     fn deref(&self) -> &Self::Target {  in deref()
265         // SAFETY: By the type invariant, there is necessarily a reference to the object, so it is  in deref()
272     fn as_ref(&self) -> &T {  in as_ref()
278     fn clone(&self) -> Self {  in clone()
280         // SAFETY: By the type invariant, there is necessarily a reference to the object, so it is  in clone()
284         // SAFETY: We just incremented the refcount. This increment is now owned by the new `Arc`.  in clone()
291         // SAFETY: By the type invariant, there is necessarily a reference to the object. We cannot  in drop()
292         // touch `refcount` after it's decremented to a non-zero value because another thread/CPU  in drop()
299         // SAFETY: Also by the type invariant, we are allowed to decrement the refcount.  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()
318         // SAFETY: The type invariants of `Arc` guarantee that the data is pinned.  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()
404     /// # Safety
409     unsafe fn new(inner: NonNull<ArcInner<T>>) -> Self {  in new()
410         // INVARIANT: The safety requirements guarantee the invariants.  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()
433         // SAFETY: By the type invariant, the underlying object is still alive with no mutable  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()
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()
530             // SAFETY: There are no safety requirements for this FFI call.  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()
536             // SAFETY: The pointer from the `Box` is valid.  in try_new_uninit()
544     pub fn write(mut self, value: T) -> UniqueArc<T> {  in write()
546         // SAFETY: We just wrote the value to be initialized.  in write()
552     /// # Safety
556     pub unsafe fn assume_init(self) -> UniqueArc<T> {  in assume_init()
559             // SAFETY: The new `Arc` is taking over `ptr` from `self.inner` (which won't be  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()
567         // SAFETY: The supplied pointer is valid for initialization.  in init_with()
569             // SAFETY: Initialization completed successfully.  in init_with()
575     /// Pin-initialize `self` using the given pin-initializer.
579     ) -> core::result::Result<Pin<UniqueArc<T>>, E> {  in pin_init_with()
580         // SAFETY: The supplied pointer is valid for initialization and we will later pin the value  in pin_init_with()
583             // SAFETY: Initialization completed successfully.  in pin_init_with()
591     fn from(obj: UniqueArc<T>) -> Self {  in from()
592         // SAFETY: It is not possible to move/replace `T` inside a `Pin<UniqueArc<T>>` (unless `T`  in from()
601     fn deref(&self) -> &Self::Target {  in deref()
607     fn deref_mut(&mut self) -> &mut Self::Target {  in deref_mut()
608         // SAFETY: By the `Arc` type invariant, there is necessarily a reference to the object, so  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()