Constructs a newArc<T>.

§Examples

usestd::sync::Arc;letfive = Arc::new(5);

Constructs a newArc<T> while giving you aWeak<T> to the allocation,to allow you to construct aT which holds a weak pointer to itself.

Generally, a structure circularly referencing itself, either directly orindirectly, should not hold a strong reference to itself to prevent a memory leak.Using this function, you get access to the weak pointer during theinitialization ofT, before theArc<T> is created, such that you canclone and store it inside theT.

new_cyclic first allocates the managed allocation for theArc<T>,then calls your closure, giving it aWeak<T> to this allocation,and only afterwards completes the construction of theArc<T> by placingtheT returned from your closure into the allocation.

Since the newArc<T> is not fully-constructed untilArc<T>::new_cyclicreturns, callingupgrade on the weak reference inside your closure willfail and result in aNone value.

§Panics

Ifdata_fn panics, the panic is propagated to the caller, and thetemporaryWeak<T> is dropped normally.

§Example

usestd::sync::{Arc, Weak};structGadget {    me: Weak<Gadget>,}implGadget {/// Constructs a reference counted Gadget.fnnew() -> Arc<Self> {// `me` is a `Weak<Gadget>` pointing at the new allocation of the        // `Arc` we're constructing.Arc::new_cyclic(|me| {// Create the actual struct here.Gadget { me: me.clone() }        })    }/// Returns a reference counted pointer to Self.fnme(&self) -> Arc<Self> {self.me.upgrade().unwrap()    }}

Constructs a newArc with uninitialized contents.

§Examples

usestd::sync::Arc;letmutfive = Arc::<u32>::new_uninit();// Deferred initialization:Arc::get_mut(&mutfive).unwrap().write(5);letfive =unsafe{ five.assume_init() };assert_eq!(*five,5)

Constructs a newArc with uninitialized contents, with the memorybeing filled with0 bytes.

SeeMaybeUninit::zeroed for examples of correct and incorrect usageof this method.

§Examples

usestd::sync::Arc;letzero = Arc::<u32>::new_zeroed();letzero =unsafe{ zero.assume_init() };assert_eq!(*zero,0)

Constructs a newPin<Arc<T>>. IfT does not implementUnpin, thendata will be pinned in memory and unable to be moved.

Constructs a newPin<Arc<T>>, return an error if allocation fails.

Constructs a newArc<T>, returning an error if allocation fails.

§Examples

#![feature(allocator_api)]usestd::sync::Arc;letfive = Arc::try_new(5)?;

Constructs a newArc with uninitialized contents, returning an errorif allocation fails.

§Examples

#![feature(allocator_api)]usestd::sync::Arc;letmutfive = Arc::<u32>::try_new_uninit()?;// Deferred initialization:Arc::get_mut(&mutfive).unwrap().write(5);letfive =unsafe{ five.assume_init() };assert_eq!(*five,5);

Constructs a newArc with uninitialized contents, with the memorybeing filled with0 bytes, returning an error if allocation fails.

SeeMaybeUninit::zeroed for examples of correct and incorrect usageof this method.

§Examples

#![feature( allocator_api)]usestd::sync::Arc;letzero = Arc::<u32>::try_new_zeroed()?;letzero =unsafe{ zero.assume_init() };assert_eq!(*zero,0);

Maps the value in anArc, reusing the allocation if possible.

f is called on a reference to the value in theArc, and the result is returned, also inanArc.

Note: this is an associated function, which means that you haveto call it asArc::map(a, f) instead ofr.map(a). Thisis so that there is no conflict with a method on the inner type.

§Examples

#![feature(smart_pointer_try_map)]usestd::sync::Arc;letr = Arc::new(7);letnew = Arc::map(r, |i| i +7);assert_eq!(*new,14);

Attempts to map the value in anArc, reusing the allocation if possible.

f is called on a reference to the value in theArc, and if the operation succeeds, theresult is returned, also in anArc.

Note: this is an associated function, which means that you haveto call it asArc::try_map(a, f) instead ofa.try_map(f). Thisis so that there is no conflict with a method on the inner type.

§Examples

#![feature(smart_pointer_try_map)]usestd::sync::Arc;letb = Arc::new(7);letnew = Arc::try_map(b, |&i| u32::try_from(i)).unwrap();assert_eq!(*new,7);

Constructs a newArc<T> in the provided allocator.

§Examples

#![feature(allocator_api)]usestd::sync::Arc;usestd::alloc::System;letfive = Arc::new_in(5, System);

Constructs a newArc with uninitialized contents in the provided allocator.

§Examples

#![feature(get_mut_unchecked)]#![feature(allocator_api)]usestd::sync::Arc;usestd::alloc::System;letmutfive = Arc::<u32,_>::new_uninit_in(System);letfive =unsafe{// Deferred initialization:Arc::get_mut_unchecked(&mutfive).as_mut_ptr().write(5);    five.assume_init()};assert_eq!(*five,5)

Constructs a newArc with uninitialized contents, with the memorybeing filled with0 bytes, in the provided allocator.

SeeMaybeUninit::zeroed for examples of correct and incorrect usageof this method.

§Examples

#![feature(allocator_api)]usestd::sync::Arc;usestd::alloc::System;letzero = Arc::<u32,_>::new_zeroed_in(System);letzero =unsafe{ zero.assume_init() };assert_eq!(*zero,0)

Constructs a newArc<T, A> in the given allocator while giving you aWeak<T, A> to the allocation,to allow you to construct aT which holds a weak pointer to itself.

Generally, a structure circularly referencing itself, either directly orindirectly, should not hold a strong reference to itself to prevent a memory leak.Using this function, you get access to the weak pointer during theinitialization ofT, before theArc<T, A> is created, such that you canclone and store it inside theT.

new_cyclic_in first allocates the managed allocation for theArc<T, A>,then calls your closure, giving it aWeak<T, A> to this allocation,and only afterwards completes the construction of theArc<T, A> by placingtheT returned from your closure into the allocation.

Since the newArc<T, A> is not fully-constructed untilArc<T, A>::new_cyclic_inreturns, callingupgrade on the weak reference inside your closure willfail and result in aNone value.

§Panics

Ifdata_fn panics, the panic is propagated to the caller, and thetemporaryWeak<T> is dropped normally.

§Example

Seenew_cyclic

Constructs a newPin<Arc<T, A>> in the provided allocator. IfT does not implementUnpin,thendata will be pinned in memory and unable to be moved.

Constructs a newPin<Arc<T, A>> in the provided allocator, return an error if allocationfails.

Constructs a newArc<T, A> in the provided allocator, returning an error if allocation fails.

§Examples

#![feature(allocator_api)]usestd::sync::Arc;usestd::alloc::System;letfive = Arc::try_new_in(5, System)?;

Constructs a newArc with uninitialized contents, in the provided allocator, returning anerror if allocation fails.

§Examples

#![feature(allocator_api)]#![feature(get_mut_unchecked)]usestd::sync::Arc;usestd::alloc::System;letmutfive = Arc::<u32,_>::try_new_uninit_in(System)?;letfive =unsafe{// Deferred initialization:Arc::get_mut_unchecked(&mutfive).as_mut_ptr().write(5);    five.assume_init()};assert_eq!(*five,5);

Constructs a newArc with uninitialized contents, with the memorybeing filled with0 bytes, in the provided allocator, returning an error if allocationfails.

SeeMaybeUninit::zeroed for examples of correct and incorrect usageof this method.

§Examples

#![feature(allocator_api)]usestd::sync::Arc;usestd::alloc::System;letzero = Arc::<u32,_>::try_new_zeroed_in(System)?;letzero =unsafe{ zero.assume_init() };assert_eq!(*zero,0);

Returns the inner value, if theArc has exactly one strong reference.

Otherwise, anErr is returned with the sameArc that waspassed in.

This will succeed even if there are outstanding weak references.

It is strongly recommended to useArc::into_inner instead if you don’tkeep theArc in theErr case.Immediately dropping theErr-value, as the expressionArc::try_unwrap(this).ok() does, can cause the strong count todrop to zero and the inner value of theArc to be dropped.For instance, if two threads execute such an expression in parallel,there is a race condition without the possibility of unsafety:The threads could first both check whether they own the last instanceinArc::try_unwrap, determine that they both do not, and then bothdiscard and drop their instance in the call took.In this scenario, the value inside theArc is safely destroyedby exactly one of the threads, but neither thread will ever be ableto use the value.

§Examples

usestd::sync::Arc;letx = Arc::new(3);assert_eq!(Arc::try_unwrap(x),Ok(3));letx = Arc::new(4);let_y = Arc::clone(&x);assert_eq!(*Arc::try_unwrap(x).unwrap_err(),4);

Returns the inner value, if theArc has exactly one strong reference.

Otherwise,None is returned and theArc is dropped.

This will succeed even if there are outstanding weak references.

IfArc::into_inner is called on every clone of thisArc,it is guaranteed that exactly one of the calls returns the inner value.This means in particular that the inner value is not dropped.

Arc::try_unwrap is conceptually similar toArc::into_inner, but itis meant for different use-cases. If used as a direct replacementforArc::into_inner anyway, such as with the expressionArc::try_unwrap(this).ok(), then it doesnot give the same guarantee as described in the previous paragraph.For more information, see the examples below and read the documentationofArc::try_unwrap.

§Examples

Minimal example demonstrating the guarantee thatArc::into_inner gives.

usestd::sync::Arc;letx = Arc::new(3);lety = Arc::clone(&x);// Two threads calling `Arc::into_inner` on both clones of an `Arc`:letx_thread = std::thread::spawn(|| Arc::into_inner(x));lety_thread = std::thread::spawn(|| Arc::into_inner(y));letx_inner_value = x_thread.join().unwrap();lety_inner_value = y_thread.join().unwrap();// One of the threads is guaranteed to receive the inner value:assert!(matches!(    (x_inner_value, y_inner_value),    (None,Some(3)) | (Some(3),None)));// The result could also be `(None, None)` if the threads called// `Arc::try_unwrap(x).ok()` and `Arc::try_unwrap(y).ok()` instead.

A more practical example demonstrating the need forArc::into_inner:

usestd::sync::Arc;// Definition of a simple singly linked list using `Arc`:#[derive(Clone)]structLinkedList<T>(Option<Arc<Node<T>>>);structNode<T>(T,Option<Arc<Node<T>>>);// Dropping a long `LinkedList<T>` relying on the destructor of `Arc`// can cause a stack overflow. To prevent this, we can provide a// manual `Drop` implementation that does the destruction in a loop:impl<T> DropforLinkedList<T> {fndrop(&mutself) {letmutlink =self.0.take();while letSome(arc_node) = link.take() {if letSome(Node(_value, next)) = Arc::into_inner(arc_node) {                link = next;            }        }    }}// Implementation of `new` and `push` omittedimpl<T> LinkedList<T> {/* ... */}// The following code could have still caused a stack overflow// despite the manual `Drop` impl if that `Drop` impl had used// `Arc::try_unwrap(arc).ok()` instead of `Arc::into_inner(arc)`.// Create a long list and clone itletmutx = LinkedList::new();letsize =100000;foriin0..size {    x.push(i);// Adds i to the front of x}lety = x.clone();// Drop the clones in parallelletx_thread = std::thread::spawn(|| drop(x));lety_thread = std::thread::spawn(|| drop(y));x_thread.join().unwrap();y_thread.join().unwrap();

Constructs a new atomically reference-counted slice with uninitialized contents.

§Examples

usestd::sync::Arc;letmutvalues = Arc::<[u32]>::new_uninit_slice(3);// Deferred initialization:letdata = Arc::get_mut(&mutvalues).unwrap();data[0].write(1);data[1].write(2);data[2].write(3);letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [1,2,3])

Constructs a new atomically reference-counted slice with uninitialized contents, with the memory beingfilled with0 bytes.

SeeMaybeUninit::zeroed for examples of correct andincorrect usage of this method.

§Examples

usestd::sync::Arc;letvalues = Arc::<[u32]>::new_zeroed_slice(3);letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [0,0,0])

Converts the reference-counted slice into a reference-counted array.

This operation does not reallocate; the underlying array of the slice is simply reinterpreted as an array type.

IfN is not exactly equal to the length ofself, then this method returnsNone.

Constructs a new atomically reference-counted slice with uninitialized contents in theprovided allocator.

§Examples

#![feature(get_mut_unchecked)]#![feature(allocator_api)]usestd::sync::Arc;usestd::alloc::System;letmutvalues = Arc::<[u32],_>::new_uninit_slice_in(3, System);letvalues =unsafe{// Deferred initialization:Arc::get_mut_unchecked(&mutvalues)[0].as_mut_ptr().write(1);    Arc::get_mut_unchecked(&mutvalues)[1].as_mut_ptr().write(2);    Arc::get_mut_unchecked(&mutvalues)[2].as_mut_ptr().write(3);    values.assume_init()};assert_eq!(*values, [1,2,3])

Constructs a new atomically reference-counted slice with uninitialized contents, with the memory beingfilled with0 bytes, in the provided allocator.

SeeMaybeUninit::zeroed for examples of correct andincorrect usage of this method.

§Examples

#![feature(allocator_api)]usestd::sync::Arc;usestd::alloc::System;letvalues = Arc::<[u32],_>::new_zeroed_slice_in(3, System);letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [0,0,0])

Converts toArc<T>.

§Safety

As withMaybeUninit::assume_init,it is up to the caller to guarantee that the inner valuereally is in an initialized state.Calling this when the content is not yet fully initializedcauses immediate undefined behavior.

§Examples

usestd::sync::Arc;letmutfive = Arc::<u32>::new_uninit();// Deferred initialization:Arc::get_mut(&mutfive).unwrap().write(5);letfive =unsafe{ five.assume_init() };assert_eq!(*five,5)

Constructs a newArc<T> with a clone ofvalue.

§Examples

#![feature(clone_from_ref)]usestd::sync::Arc;lethello: Arc<str> = Arc::clone_from_ref("hello");

Constructs a newArc<T> with a clone ofvalue, returning an error if allocation fails

§Examples

#![feature(clone_from_ref)]#![feature(allocator_api)]usestd::sync::Arc;lethello: Arc<str> = Arc::try_clone_from_ref("hello")?;

Constructs a newArc<T> with a clone ofvalue in the provided allocator.

§Examples

#![feature(clone_from_ref)]#![feature(allocator_api)]usestd::sync::Arc;usestd::alloc::System;lethello: Arc<str, System> = Arc::clone_from_ref_in("hello", System);

Constructs a newArc<T> with a clone ofvalue in the provided allocator, returning an error if allocation fails

§Examples

#![feature(clone_from_ref)]#![feature(allocator_api)]usestd::sync::Arc;usestd::alloc::System;lethello: Arc<str, System> = Arc::try_clone_from_ref_in("hello", System)?;

Converts toArc<[T]>.

§Safety

As withMaybeUninit::assume_init,it is up to the caller to guarantee that the inner valuereally is in an initialized state.Calling this when the content is not yet fully initializedcauses immediate undefined behavior.

§Examples

usestd::sync::Arc;letmutvalues = Arc::<[u32]>::new_uninit_slice(3);// Deferred initialization:letdata = Arc::get_mut(&mutvalues).unwrap();data[0].write(1);data[1].write(2);data[2].write(3);letvalues =unsafe{ values.assume_init() };assert_eq!(*values, [1,2,3])

Constructs anArc<T> from a raw pointer.

The raw pointer must have been previously returned by a call toArc<U>::into_raw with the following requirements:

• IfU is sized, it must have the same size and alignment asT. Thisis trivially true ifU isT.
• IfU is unsized, its data pointer must have the same size andalignment asT. This is trivially true ifArc<U> was constructedthroughArc<T> and then converted toArc<U> through anunsizedcoercion.

Note that ifU orU’s data pointer is notT but has the same sizeand alignment, this is basically like transmuting references ofdifferent types. Seemem::transmute for more informationon what restrictions apply in this case.

The raw pointer must point to a block of memory allocated by the global allocator.

The user offrom_raw has to make sure a specific value ofT is onlydropped once.

This function is unsafe because improper use may lead to memory unsafety,even if the returnedArc<T> is never accessed.

§Examples

usestd::sync::Arc;letx = Arc::new("hello".to_owned());letx_ptr = Arc::into_raw(x);unsafe{// Convert back to an `Arc` to prevent leak.letx = Arc::from_raw(x_ptr);assert_eq!(&*x,"hello");// Further calls to `Arc::from_raw(x_ptr)` would be memory-unsafe.}// The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling!

Convert a slice back into its original array:

usestd::sync::Arc;letx: Arc<[u32]> = Arc::new([1,2,3]);letx_ptr:*const[u32] = Arc::into_raw(x);unsafe{letx: Arc<[u32;3]> = Arc::from_raw(x_ptr.cast::<[u32;3]>());assert_eq!(&*x,&[1,2,3]);}

Consumes theArc, returning the wrapped pointer.

To avoid a memory leak the pointer must be converted back to anArc usingArc::from_raw.

§Examples

usestd::sync::Arc;letx = Arc::new("hello".to_owned());letx_ptr = Arc::into_raw(x);assert_eq!(unsafe{&*x_ptr },"hello");

Increments the strong reference count on theArc<T> associated with theprovided pointer by one.

§Safety

The pointer must have been obtained throughArc::into_raw and must satisfy thesame layout requirements specified inArc::from_raw_in.The associatedArc instance must be valid (i.e. the strong count must be atleast 1) for the duration of this method, andptr must point to a block of memoryallocated by the global allocator.

§Examples

usestd::sync::Arc;letfive = Arc::new(5);unsafe{letptr = Arc::into_raw(five);    Arc::increment_strong_count(ptr);// This assertion is deterministic because we haven't shared    // the `Arc` between threads.letfive = Arc::from_raw(ptr);assert_eq!(2, Arc::strong_count(&five));}

Decrements the strong reference count on theArc<T> associated with theprovided pointer by one.

§Safety

The pointer must have been obtained throughArc::into_raw and must satisfy thesame layout requirements specified inArc::from_raw_in.The associatedArc instance must be valid (i.e. the strong count must be atleast 1) when invoking this method, andptr must point to a block of memoryallocated by the global allocator. This method can be used to release the finalArc and backing storage, butshould not be called after the finalArc has beenreleased.

§Examples

usestd::sync::Arc;letfive = Arc::new(5);unsafe{letptr = Arc::into_raw(five);    Arc::increment_strong_count(ptr);// Those assertions are deterministic because we haven't shared    // the `Arc` between threads.letfive = Arc::from_raw(ptr);assert_eq!(2, Arc::strong_count(&five));    Arc::decrement_strong_count(ptr);assert_eq!(1, Arc::strong_count(&five));}

Returns a reference to the underlying allocator.

Note: this is an associated function, which means that you haveto call it asArc::allocator(&a) instead ofa.allocator(). Thisis so that there is no conflict with a method on the inner type.

Consumes theArc, returning the wrapped pointer and allocator.

To avoid a memory leak the pointer must be converted back to anArc usingArc::from_raw_in.

§Examples

#![feature(allocator_api)]usestd::sync::Arc;usestd::alloc::System;letx = Arc::new_in("hello".to_owned(), System);let(ptr, alloc) = Arc::into_raw_with_allocator(x);assert_eq!(unsafe{&*ptr },"hello");letx =unsafe{ Arc::from_raw_in(ptr, alloc) };assert_eq!(&*x,"hello");

Provides a raw pointer to the data.

The counts are not affected in any way and theArc is not consumed. The pointer is valid foras long as there are strong counts in theArc.

§Examples

usestd::sync::Arc;letx = Arc::new("hello".to_owned());lety = Arc::clone(&x);letx_ptr = Arc::as_ptr(&x);assert_eq!(x_ptr, Arc::as_ptr(&y));assert_eq!(unsafe{&*x_ptr },"hello");

Constructs anArc<T, A> from a raw pointer.

The raw pointer must have been previously returned by a call toArc<U, A>::into_raw with the following requirements:

• IfU is sized, it must have the same size and alignment asT. Thisis trivially true ifU isT.
• IfU is unsized, its data pointer must have the same size andalignment asT. This is trivially true ifArc<U> was constructedthroughArc<T> and then converted toArc<U> through anunsizedcoercion.

Note that ifU orU’s data pointer is notT but has the same sizeand alignment, this is basically like transmuting references ofdifferent types. Seemem::transmute for more informationon what restrictions apply in this case.

The raw pointer must point to a block of memory allocated byalloc

The user offrom_raw has to make sure a specific value ofT is onlydropped once.

This function is unsafe because improper use may lead to memory unsafety,even if the returnedArc<T> is never accessed.

§Examples

#![feature(allocator_api)]usestd::sync::Arc;usestd::alloc::System;letx = Arc::new_in("hello".to_owned(), System);let(x_ptr, alloc) = Arc::into_raw_with_allocator(x);unsafe{// Convert back to an `Arc` to prevent leak.letx = Arc::from_raw_in(x_ptr, System);assert_eq!(&*x,"hello");// Further calls to `Arc::from_raw(x_ptr)` would be memory-unsafe.}// The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling!

Convert a slice back into its original array:

#![feature(allocator_api)]usestd::sync::Arc;usestd::alloc::System;letx: Arc<[u32],_> = Arc::new_in([1,2,3], System);letx_ptr:*const[u32] = Arc::into_raw_with_allocator(x).0;unsafe{letx: Arc<[u32;3],_> = Arc::from_raw_in(x_ptr.cast::<[u32;3]>(), System);assert_eq!(&*x,&[1,2,3]);}

Creates a newWeak pointer to this allocation.

§Examples

usestd::sync::Arc;letfive = Arc::new(5);letweak_five = Arc::downgrade(&five);

Gets the number ofWeak pointers to this allocation.

§Safety

This method by itself is safe, but using it correctly requires extra care.Another thread can change the weak count at any time,including potentially between calling this method and acting on the result.

§Examples

usestd::sync::Arc;letfive = Arc::new(5);let_weak_five = Arc::downgrade(&five);// This assertion is deterministic because we haven't shared// the `Arc` or `Weak` between threads.assert_eq!(1, Arc::weak_count(&five));

Gets the number of strong (Arc) pointers to this allocation.

§Safety

This method by itself is safe, but using it correctly requires extra care.Another thread can change the strong count at any time,including potentially between calling this method and acting on the result.

§Examples

usestd::sync::Arc;letfive = Arc::new(5);let_also_five = Arc::clone(&five);// This assertion is deterministic because we haven't shared// the `Arc` between threads.assert_eq!(2, Arc::strong_count(&five));

Increments the strong reference count on theArc<T> associated with theprovided pointer by one.

§Safety

The pointer must have been obtained throughArc::into_raw and must satisfy thesame layout requirements specified inArc::from_raw_in.The associatedArc instance must be valid (i.e. the strong count must be atleast 1) for the duration of this method, andptr must point to a block of memoryallocated byalloc.

§Examples

#![feature(allocator_api)]usestd::sync::Arc;usestd::alloc::System;letfive = Arc::new_in(5, System);unsafe{let(ptr, _alloc) = Arc::into_raw_with_allocator(five);    Arc::increment_strong_count_in(ptr, System);// This assertion is deterministic because we haven't shared    // the `Arc` between threads.letfive = Arc::from_raw_in(ptr, System);assert_eq!(2, Arc::strong_count(&five));}

Decrements the strong reference count on theArc<T> associated with theprovided pointer by one.

§Safety

The pointer must have been obtained throughArc::into_raw and must satisfy thesame layout requirements specified inArc::from_raw_in.The associatedArc instance must be valid (i.e. the strong count must be atleast 1) when invoking this method, andptr must point to a block of memoryallocated byalloc. This method can be used to release the finalArc and backing storage, butshould not be called after the finalArc has beenreleased.

§Examples

#![feature(allocator_api)]usestd::sync::Arc;usestd::alloc::System;letfive = Arc::new_in(5, System);unsafe{let(ptr, _alloc) = Arc::into_raw_with_allocator(five);    Arc::increment_strong_count_in(ptr, System);// Those assertions are deterministic because we haven't shared    // the `Arc` between threads.letfive = Arc::from_raw_in(ptr, System);assert_eq!(2, Arc::strong_count(&five));    Arc::decrement_strong_count_in(ptr, System);assert_eq!(1, Arc::strong_count(&five));}

Returnstrue if the twoArcs point to the same allocation in a vein similar toptr::eq. This function ignores the metadata ofdyn Trait pointers.

§Examples

usestd::sync::Arc;letfive = Arc::new(5);letsame_five = Arc::clone(&five);letother_five = Arc::new(5);assert!(Arc::ptr_eq(&five,&same_five));assert!(!Arc::ptr_eq(&five,&other_five));

Makes a mutable reference into the givenArc.

If there are otherArc pointers to the same allocation, thenmake_mut willclone the inner value to a new allocation to ensure unique ownership. This is alsoreferred to as clone-on-write.

However, if there are no otherArc pointers to this allocation, but someWeakpointers, then theWeak pointers will be dissociated and the inner value will notbe cloned.

See alsoget_mut, which will fail rather than cloning the inner valueor dissociatingWeak pointers.

§Examples

usestd::sync::Arc;letmutdata = Arc::new(5);*Arc::make_mut(&mutdata) +=1;// Won't clone anythingletmutother_data = Arc::clone(&data);// Won't clone inner data*Arc::make_mut(&mutdata) +=1;// Clones inner data*Arc::make_mut(&mutdata) +=1;// Won't clone anything*Arc::make_mut(&mutother_data)*=2;// Won't clone anything// Now `data` and `other_data` point to different allocations.assert_eq!(*data,8);assert_eq!(*other_data,12);

Weak pointers will be dissociated:

usestd::sync::Arc;letmutdata = Arc::new(75);letweak = Arc::downgrade(&data);assert!(75==*data);assert!(75==*weak.upgrade().unwrap());*Arc::make_mut(&mutdata) +=1;assert!(76==*data);assert!(weak.upgrade().is_none());

If we have the only reference toT then unwrap it. Otherwise, cloneT and return theclone.

Assumingarc_t is of typeArc<T>, this function is functionally equivalent to(*arc_t).clone(), but will avoid cloning the inner value where possible.

§Examples

letinner = String::from("test");letptr = inner.as_ptr();letarc = Arc::new(inner);letinner = Arc::unwrap_or_clone(arc);// The inner value was not clonedassert!(ptr::eq(ptr, inner.as_ptr()));letarc = Arc::new(inner);letarc2 = arc.clone();letinner = Arc::unwrap_or_clone(arc);// Because there were 2 references, we had to clone the inner value.assert!(!ptr::eq(ptr, inner.as_ptr()));// `arc2` is the last reference, so when we unwrap it we get back// the original `String`.letinner = Arc::unwrap_or_clone(arc2);assert!(ptr::eq(ptr, inner.as_ptr()));

Returns a mutable reference into the givenArc, if there areno otherArc orWeak pointers to the same allocation.

ReturnsNone otherwise, because it is not safe tomutate a shared value.

See alsomake_mut, which willclonethe inner value when there are otherArc pointers.

§Examples

usestd::sync::Arc;letmutx = Arc::new(3);*Arc::get_mut(&mutx).unwrap() =4;assert_eq!(*x,4);let_y = Arc::clone(&x);assert!(Arc::get_mut(&mutx).is_none());

Returns a mutable reference into the givenArc,without any check.

See alsoget_mut, which is safe and does appropriate checks.

§Safety

If any otherArc orWeak pointers to the same allocation exist, thenthey must not be dereferenced or have active borrows for the durationof the returned borrow, and their inner type must be exactly the same as theinner type of this Arc (including lifetimes). This is trivially the case if nosuch pointers exist, for example immediately afterArc::new.

§Examples

#![feature(get_mut_unchecked)]usestd::sync::Arc;letmutx = Arc::new(String::new());unsafe{    Arc::get_mut_unchecked(&mutx).push_str("foo")}assert_eq!(*x,"foo");

OtherArc pointers to the same allocation must be to the same type.

#![feature(get_mut_unchecked)]usestd::sync::Arc;letx: Arc<str> = Arc::from("Hello, world!");letmuty: Arc<[u8]> = x.clone().into();unsafe{// this is Undefined Behavior, because x's inner type is str, not [u8]Arc::get_mut_unchecked(&muty).fill(0xff);// 0xff is invalid in UTF-8}println!("{}",&*x);// Invalid UTF-8 in a str

OtherArc pointers to the same allocation must be to the exact same type, including lifetimes.

#![feature(get_mut_unchecked)]usestd::sync::Arc;letx: Arc<&str> = Arc::new("Hello, world!");{lets = String::from("Oh, no!");letmuty: Arc<&str> = x.clone();unsafe{// this is Undefined Behavior, because x's inner type        // is &'long str, not &'short str*Arc::get_mut_unchecked(&muty) =&s;    }}println!("{}",&*x);// Use-after-free

Determine whether this is the unique reference to the underlying data.

Returnstrue if there are no otherArc orWeak pointers to the same allocation;returnsfalse otherwise.

If this function returnstrue, then is guaranteed to be safe to callget_mut_uncheckedon thisArc, so long as no clones occur in between.

§Examples

#![feature(arc_is_unique)]usestd::sync::Arc;letx = Arc::new(3);assert!(Arc::is_unique(&x));lety = Arc::clone(&x);assert!(!Arc::is_unique(&x));drop(y);// Weak references also count, because they could be upgraded at any time.letz = Arc::downgrade(&x);assert!(!Arc::is_unique(&x));

§Pointer invalidation

This function will always return the same value asArc::get_mut(arc).is_some(). However,unlike that operation it does not produce any mutable references to the underlying data,meaning no pointers to the data inside theArc are invalidated by the call. Thus, thefollowing code is valid, even though it would be UB if it usedArc::get_mut:

#![feature(arc_is_unique)]usestd::sync::Arc;letarc = Arc::new(5);letpointer:*consti32 =&*arc;assert!(Arc::is_unique(&arc));assert_eq!(unsafe{*pointer },5);

§Atomic orderings

Concurrent drops to otherArc pointers to the same allocation will synchronize with thiscall - that is, this call performs anAcquire operation on the underlying strong and weakref counts. This ensures that callingget_mut_unchecked is safe.

Note that this operation requires locking the weak ref count, so concurrent calls todowngrade may spin-loop for a short period of time.

Attempts to downcast theArc<dyn Any + Send + Sync> to a concrete type.

§Examples

usestd::any::Any;usestd::sync::Arc;fnprint_if_string(value: Arc<dynAny + Send + Sync>) {if letOk(string) = value.downcast::<String>() {println!("String ({}): {}", string.len(), string);    }}letmy_string ="Hello World".to_string();print_if_string(Arc::new(my_string));print_if_string(Arc::new(0i8));

Downcasts theArc<dyn Any + Send + Sync> to a concrete type.

For a safe alternative seedowncast.

§Examples

#![feature(downcast_unchecked)]usestd::any::Any;usestd::sync::Arc;letx: Arc<dynAny + Send + Sync> = Arc::new(1_usize);unsafe{assert_eq!(*x.downcast_unchecked::<usize>(),1);}

§Safety

The contained value must be of typeT. Calling this methodwith the incorrect type isundefined behavior.

Makes a clone of theArc pointer.

This creates another pointer to the same allocation, increasing thestrong reference count.

§Examples

usestd::sync::Arc;letfive = Arc::new(5);let _= Arc::clone(&five);

Creates an empty[T] inside an Arc

This may or may not share an allocation with other Arcs.

Creates an empty CStr inside an Arc

This may or may not share an allocation with other Arcs.

Creates a newArc<T>, with theDefault value forT.

§Examples

usestd::sync::Arc;letx: Arc<i32> = Default::default();assert_eq!(*x,0);

Creates an empty str inside an Arc

This may or may not share an allocation with other Arcs.

Drops theArc.

This will decrement the strong reference count. If the strong referencecount reaches zero then the only other references (if any) areWeak, so wedrop the inner value.

§Examples

usestd::sync::Arc;structFoo;implDropforFoo {fndrop(&mutself) {println!("dropped!");    }}letfoo  = Arc::new(Foo);letfoo2 = Arc::clone(&foo);drop(foo);// Doesn't print anythingdrop(foo2);// Prints "dropped!"

Allocates a reference-counted slice and fills it by cloningv’s items.

§Example

letoriginal:&[i32] =&[1,2,3];letshared: Arc<[i32]> = Arc::from(original);assert_eq!(&[1,2,3],&shared[..]);

Converts a&CStr into aArc<CStr>,by copying the contents into a newly allocatedArc.

Copies the string into a newly allocatedArc<OsStr>.

Converts aPath into anArc by copying thePath data into a newArc buffer.

Allocates a reference-counted slice and fills it by cloningv’s items.

§Example

letmutoriginal = [1,2,3];letoriginal:&mut[i32] =&mutoriginal;letshared: Arc<[i32]> = Arc::from(original);assert_eq!(&[1,2,3],&shared[..]);

Converts a&mut CStr into aArc<CStr>,by copying the contents into a newly allocatedArc.

Copies the string into a newly allocatedArc<OsStr>.

Converts aPath into anArc by copying thePath data into a newArc buffer.

Allocates a reference-countedstr and copiesv into it.

§Example

letmutoriginal = String::from("eggplant");letoriginal:&mutstr =&mutoriginal;letshared: Arc<str> = Arc::from(original);assert_eq!("eggplant",&shared[..]);

Allocates a reference-countedstr and copiesv into it.

§Example

letshared: Arc<str> = Arc::from("eggplant");assert_eq!("eggplant",&shared[..]);

Converts a[T; N] into anArc<[T]>.

The conversion moves the array into a newly allocatedArc.

§Example

letoriginal: [i32;3] = [1,2,3];letshared: Arc<[i32]> = Arc::from(original);assert_eq!(&[1,2,3],&shared[..]);

Use aWake-able type as aRawWaker.

No heap allocations or atomic operations are used for this conversion.

Use aWake-able type as aWaker.

No heap allocations or atomic operations are used for this conversion.

Converts an atomically reference-counted string slice into a byte slice.

§Example

letstring: Arc<str> = Arc::from("eggplant");letbytes: Arc<[u8]> = Arc::from(string);assert_eq!("eggplant".as_bytes(), bytes.as_ref());

Move a boxed object to a new, reference-counted allocation.

§Example

letunique: Box<str> = Box::from("eggplant");letshared: Arc<str> = Arc::from(unique);assert_eq!("eggplant",&shared[..]);

Converts aCString into anArc<CStr> by moving theCStringdata into a newArc buffer.

Creates an atomically reference-counted pointer from a clone-on-writepointer by copying its content.

§Example

letcow: Cow<'_, str> = Cow::Borrowed("eggplant");letshared: Arc<str> = Arc::from(cow);assert_eq!("eggplant",&shared[..]);

Converts anOsString into anArc<OsStr> by moving theOsStringdata into a newArc buffer.

Converts aPathBuf into anArc<Path> by moving thePathBuf datainto a newArc buffer.

Allocates a reference-countedstr and copiesv into it.

§Example

letunique: String ="eggplant".to_owned();letshared: Arc<str> = Arc::from(unique);assert_eq!("eggplant",&shared[..]);

Converts aT into anArc<T>

The conversion moves the value into anewly allocatedArc. It is equivalent tocallingArc::new(t).

§Example

letx =5;letarc = Arc::new(5);assert_eq!(Arc::from(x), arc);

Allocates a reference-counted slice and movesv’s items into it.

§Example

letunique: Vec<i32> =vec![1,2,3];letshared: Arc<[i32]> = Arc::from(unique);assert_eq!(&[1,2,3],&shared[..]);

Takes each element in theIterator and collects it into anArc<[T]>.

§Performance characteristics

§The general case

In the general case, collecting intoArc<[T]> is done by firstcollecting into aVec<T>. That is, when writing the following:

letevens: Arc<[u8]> = (0..10).filter(|&x| x %2==0).collect();

this behaves as if we wrote:

letevens: Arc<[u8]> = (0..10).filter(|&x| x %2==0)    .collect::<Vec<_>>()// The first set of allocations happens here..into();// A second allocation for `Arc<[T]>` happens here.

This will allocate as many times as needed for constructing theVec<T>and then it will allocate once for turning theVec<T> into theArc<[T]>.

§Iterators of known length

When yourIterator implementsTrustedLen and is of an exact size,a single allocation will be made for theArc<[T]>. For example:

letevens: Arc<[u8]> = (0..10).collect();// Just a single allocation happens here.

Comparison for twoArcs.

The two are compared by callingcmp() on their inner values.

§Examples

usestd::sync::Arc;usestd::cmp::Ordering;letfive = Arc::new(5);assert_eq!(Ordering::Less, five.cmp(&Arc::new(6)));

Equality for twoArcs.

TwoArcs are equal if their inner values are equal, even if they arestored in different allocation.

IfT also implementsEq (implying reflexivity of equality),twoArcs that point to the same allocation are always equal.

§Examples

usestd::sync::Arc;letfive = Arc::new(5);assert!(five == Arc::new(5));

Inequality for twoArcs.

TwoArcs are not equal if their inner values are not equal.

IfT also implementsEq (implying reflexivity of equality),twoArcs that point to the same value are always equal.

§Examples

usestd::sync::Arc;letfive = Arc::new(5);assert!(five != Arc::new(6));

Partial comparison for twoArcs.

The two are compared by callingpartial_cmp() on their inner values.

§Examples

usestd::sync::Arc;usestd::cmp::Ordering;letfive = Arc::new(5);assert_eq!(Some(Ordering::Less), five.partial_cmp(&Arc::new(6)));

Less-than comparison for twoArcs.

The two are compared by calling< on their inner values.

§Examples

usestd::sync::Arc;letfive = Arc::new(5);assert!(five < Arc::new(6));

‘Less than or equal to’ comparison for twoArcs.

The two are compared by calling<= on their inner values.

§Examples

usestd::sync::Arc;letfive = Arc::new(5);assert!(five <= Arc::new(5));

Greater-than comparison for twoArcs.

The two are compared by calling> on their inner values.

§Examples

usestd::sync::Arc;letfive = Arc::new(5);assert!(five > Arc::new(4));

‘Greater than or equal to’ comparison for twoArcs.

The two are compared by calling>= on their inner values.

§Examples

usestd::sync::Arc;letfive = Arc::new(5);assert!(five >= Arc::new(5));

Returns the argument unchanged.

CallsU::from(self).

That is, this conversion is whatever the implementation ofFrom<T> for U chooses to do.