Struct Arc

1.36.0 · source

pub struct Arc<T: ?Sized, A: Allocator = Global> { /* private fields */ }

Expand description

A thread-safe reference-counting pointer. ‘Arc’ stands for ‘Atomically Reference Counted’.

The type Arc<T> provides shared ownership of a value of type T, allocated in the heap. Invoking clone on Arc produces a new Arc instance, which points to the same allocation on the heap as the source Arc, while increasing a reference count. When the last Arc pointer to a given allocation is destroyed, the value stored in that allocation (often referred to as “inner value”) is also dropped.

Shared references in Rust disallow mutation by default, and Arc is no exception: you cannot generally obtain a mutable reference to something inside an Arc. If you need to mutate through an Arc, use Mutex, RwLock, or one of the Atomic types.

Note: This type is only available on platforms that support atomic loads and stores of pointers, which includes all platforms that support the std crate but not all those which only support alloc. This may be detected at compile time using #[cfg(target_has_atomic = "ptr")].

§Thread Safety

Unlike Rc<T>, Arc<T> uses atomic operations for its reference counting. This means that it is thread-safe. The disadvantage is that atomic operations are more expensive than ordinary memory accesses. If you are not sharing reference-counted allocations between threads, consider using Rc<T> for lower overhead. Rc<T> is a safe default, because the compiler will catch any attempt to send an Rc<T> between threads. However, a library might choose Arc<T> in order to give library consumers more flexibility.

Arc<T> will implement Send and Sync as long as the T implements Send and Sync. Why can’t you put a non-thread-safe type T in an Arc<T> to make it thread-safe? This may be a bit counter-intuitive at first: after all, isn’t the point of Arc<T> thread safety? The key is this: Arc<T> makes it thread safe to have multiple ownership of the same data, but it doesn’t add thread safety to its data. Consider Arc<RefCell<T>>. RefCell<T> isn’t Sync, and if Arc<T> was always Send, Arc<RefCell<T>> would be as well. But then we’d have a problem: RefCell<T> is not thread safe; it keeps track of the borrowing count using non-atomic operations.

In the end, this means that you may need to pair Arc<T> with some sort of std::sync type, usually Mutex<T>.

§Breaking cycles with `Weak`

The downgrade method can be used to create a non-owning Weak pointer. A Weak pointer can be upgraded to an Arc, but this will return None if the value stored in the allocation has already been dropped. In other words, Weak pointers do not keep the value inside the allocation alive; however, they do keep the allocation (the backing store for the value) alive.

A cycle between Arc pointers will never be deallocated. For this reason, Weak is used to break cycles. For example, a tree could have strong Arc pointers from parent nodes to children, and Weak pointers from children back to their parents.

§Cloning references

Creating a new reference from an existing reference-counted pointer is done using the Clone trait implemented for Arc<T> and Weak<T>.

use std::sync::Arc;
let foo = Arc::new(vec![1.0, 2.0, 3.0]);
// The two syntaxes below are equivalent.
let a = foo.clone();
let b = Arc::clone(&foo);
// a, b, and foo are all Arcs that point to the same memory location

§`Deref` behavior

Arc<T> automatically dereferences to T (via the Deref trait), so you can call T’s methods on a value of type Arc<T>. To avoid name clashes with T’s methods, the methods of Arc<T> itself are associated functions, called using fully qualified syntax:

use std::sync::Arc;

let my_arc = Arc::new(());
let my_weak = Arc::downgrade(&my_arc);

Arc<T>’s implementations of traits like Clone may also be called using fully qualified syntax. Some people prefer to use fully qualified syntax, while others prefer using method-call syntax.

use std::sync::Arc;

let arc = Arc::new(());
// Method-call syntax
let arc2 = arc.clone();
// Fully qualified syntax
let arc3 = Arc::clone(&arc);

Weak<T> does not auto-dereference to T, because the inner value may have already been dropped.

§Examples

Sharing some immutable data between threads:

use std::sync::Arc;
use std::thread;

let five = Arc::new(5);

for _ in 0..10 {
    let five = Arc::clone(&five);

    thread::spawn(move || {
        println!("{five:?}");
    });
}

Sharing a mutable AtomicUsize:

use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::thread;

let val = Arc::new(AtomicUsize::new(5));

for _ in 0..10 {
    let val = Arc::clone(&val);

    thread::spawn(move || {
        let v = val.fetch_add(1, Ordering::Relaxed);
        println!("{v:?}");
    });
}

See the rc documentation for more examples of reference counting in general.

Struct ArcCopy item path

§Thread Safety

§Breaking cycles with Weak

§Cloning references

§Deref behavior

§Examples

Implementations§

impl<T> Arc<T>

pub fn new(data: T) -> Arc<T>

§Examples

pub fn new_cyclic<F>(data_fn: F) -> Arc<T>where F: FnOnce(&Weak<T>) -> T,

§Panics

§Example

pub fn new_uninit() -> Arc<MaybeUninit<T>>

§Examples

pub fn new_zeroed() -> Arc<MaybeUninit<T>>

§Examples

pub fn pin(data: T) -> Pin<Arc<T>>

pub fn try_pin(data: T) -> Result<Pin<Arc<T>>, AllocError>

pub fn try_new(data: T) -> Result<Arc<T>, AllocError>

§Examples

pub fn try_new_uninit() -> Result<Arc<MaybeUninit<T>>, AllocError>

§Examples

pub fn try_new_zeroed() -> Result<Arc<MaybeUninit<T>>, AllocError>

§Examples

impl<T, A: Allocator> Arc<T, A>

pub fn new_in(data: T, alloc: A) -> Arc<T, A>

§Examples

pub fn new_uninit_in(alloc: A) -> Arc<MaybeUninit<T>, A>

§Examples

pub fn new_zeroed_in(alloc: A) -> Arc<MaybeUninit<T>, A>

§Examples

pub fn new_cyclic_in<F>(data_fn: F, alloc: A) -> Arc<T, A>where F: FnOnce(&Weak<T, A>) -> T,

§Panics

§Example

pub fn pin_in(data: T, alloc: A) -> Pin<Arc<T, A>>where A: 'static,

pub fn try_pin_in(data: T, alloc: A) -> Result<Pin<Arc<T, A>>, AllocError>where A: 'static,

pub fn try_new_in(data: T, alloc: A) -> Result<Arc<T, A>, AllocError>

§Examples

pub fn try_new_uninit_in(alloc: A) -> Result<Arc<MaybeUninit<T>, A>, AllocError>

§Examples

pub fn try_new_zeroed_in(alloc: A) -> Result<Arc<MaybeUninit<T>, A>, AllocError>

§Examples

pub fn try_unwrap(this: Self) -> Result<T, Self>

§Examples

pub fn into_inner(this: Self) -> Option<T>

§Examples

impl<T> Arc<[T]>

pub fn new_uninit_slice(len: usize) -> Arc<[MaybeUninit<T>]>

§Examples

pub fn new_zeroed_slice(len: usize) -> Arc<[MaybeUninit<T>]>

§Examples

impl<T, A: Allocator> Arc<[T], A>

pub fn new_uninit_slice_in(len: usize, alloc: A) -> Arc<[MaybeUninit<T>], A>

§Examples

pub fn new_zeroed_slice_in(len: usize, alloc: A) -> Arc<[MaybeUninit<T>], A>

§Examples

impl<T, A: Allocator> Arc<MaybeUninit<T>, A>

pub unsafe fn assume_init(self) -> Arc<T, A>

§Safety

§Examples

impl<T, A: Allocator> Arc<[MaybeUninit<T>], A>

pub unsafe fn assume_init(self) -> Arc<[T], A>

§Safety

§Examples

impl<T: ?Sized> Arc<T>

pub unsafe fn from_raw(ptr: *const T) -> Self

§Examples

pub unsafe fn increment_strong_count(ptr: *const T)

§Safety

§Examples

pub unsafe fn decrement_strong_count(ptr: *const T)

§Safety

§Examples

impl<T: ?Sized, A: Allocator> Arc<T, A>

pub fn allocator(this: &Self) -> &A

pub fn into_raw(this: Self) -> *const T

§Examples

pub fn into_raw_with_allocator(this: Self) -> (*const T, A)

§Examples

Struct Arc

§Breaking cycles with `Weak`

§`Deref` behavior

pub fn new_cyclic<F>(data_fn: F) -> Arc<T>
where F: FnOnce(&Weak<T>) -> T,

pub fn new_cyclic_in<F>(data_fn: F, alloc: A) -> Arc<T, A>
where F: FnOnce(&Weak<T, A>) -> T,

pub fn pin_in(data: T, alloc: A) -> Pin<Arc<T, A>>
where A: 'static,

pub fn try_pin_in(data: T, alloc: A) -> Result<Pin<Arc<T, A>>, AllocError>
where A: 'static,

pub fn downgrade(this: &Self) -> Weak<T, A>
where A: Clone,

pub unsafe fn increment_strong_count_in(ptr: *const T, alloc: A)
where A: Clone,

pub fn downcast<T>(self) -> Result<Arc<T, A>, Self>
where T: Any + Send + Sync,

pub unsafe fn downcast_unchecked<T>(self) -> Arc<T, A>
where T: Any + Send + Sync,