alloc::arc::Arc - Rust
Description: API documentation for the Rust `Arc` struct in crate `alloc`.
Keywords: rust, rustlang, rust-lang, Arc

# Struct alloc::arc::Arc 1.0.0 [−] [src]

    pub struct Arc<T: ?Sized> { /* fields omitted */ }

A thread-safe reference-counting pointer.

The type `Arc<T>` provides shared ownership of a value of type `T`, allocated in the heap. Invoking `clone` on `Arc` produces a new pointer to the same value in the heap. When the last `Arc` pointer to a given value is destroyed, the pointed-to value is also destroyed.

Shared references in Rust disallow mutation by default, and `Arc` is no exception. If you need to mutate through an `Arc`, use `Mutex`, `RwLock`, or one of the `Atomic` types.

`Arc` uses atomic operations for reference counting, so `Arc`s can be sent between threads. In other words, `Arc<T>` implements `Send` as long as `T` implements `Send` and `Sync`. The disadvantage is that atomic operations are more expensive than ordinary memory accesses. If you are not sharing reference-counted values between threads, consider using `rc::Rc` for lower overhead. `Rc` is a safe default, because the compiler will catch any attempt to send an `Rc` between threads. However, a library might choose `Arc` in order to give library consumers more flexibility.

The `downgrade` method can be used to create a non-owning `Weak` pointer. A `Weak` pointer can be `upgrade`d to an `Arc`, but this will return `None` if the value has already been dropped.

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.

`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 function-like syntax:

    use std::sync::Arc;
    let my_arc = Arc::new(());

    Arc::downgrade(&my_arc);

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

# 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 = five.clone();

        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 = val.clone();

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

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

## Methods

### `impl<T> Arc<T>`
[src]

#### `fn new(data: T) -> Arc<T>`

Constructs a new `Arc<T>`.

# Examples

    use std::sync::Arc;

    let five = Arc::new(5);

#### `fn try_unwrap(this: Self) -> Result<T, Self>`
1.4.0

Returns the contained value, if the `Arc` has exactly one strong reference.

Otherwise, an `Err` is returned with the same `Arc` that was passed in.

This will succeed even if there are outstanding weak references.

# Examples

    use std::sync::Arc;

    let x = Arc::new(3);
    assert_eq!(Arc::try_unwrap(x), Ok(3));

    let x = Arc::new(4);
    let _y = x.clone();
    assert_eq!(*Arc::try_unwrap(x).unwrap_err(), 4);

### `impl<T: ?Sized> Arc<T>`
[src]

#### `fn downgrade(this: &Self) -> Weak<T>`
1.4.0

Creates a new `Weak` pointer to this value.

# Examples

    use std::sync::Arc;

    let five = Arc::new(5);

    let weak_five = Arc::downgrade(&five);

#### `fn weak_count(this: &Self) -> usize`

Unstable (`arc_counts` #28356)

: not clearly useful, and racy

Gets the number of `Weak` pointers to this value.

Be careful how you use this information, because another thread may change the weak count at any time.

# Examples

    #![feature(arc_counts)]

    use std::sync::Arc;

    let five = 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));

#### `fn strong_count(this: &Self) -> usize`

Unstable (`arc_counts` #28356)

: not clearly useful, and racy

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

Be careful how you use this information, because another thread may change the strong count at any time.

# Examples

    #![feature(arc_counts)]

    use std::sync::Arc;

    let five = Arc::new(5);
    let _also_five = five.clone();

    // This assertion is deterministic because we haven't shared
    // the `Arc` between threads.
    assert_eq!(2, Arc::strong_count(&five));

#### `fn ptr_eq(this: &Self, other: &Self) -> bool`

Unstable (`ptr_eq` #36497)

: newly added

Returns true if the two `Arc`s point to the same value (not just values that compare as equal).

# Examples

    #![feature(ptr_eq)]

    use std::sync::Arc;

    let five = Arc::new(5);
    let same_five = five.clone();
    let other_five = Arc::new(5);

    assert!(Arc::ptr_eq(&five, &same_five));
    assert!(!Arc::ptr_eq(&five, &other_five));

### `impl<T: Clone> Arc<T>`
[src]

#### `fn make_mut(this: &mut Self) -> &mut T`
1.4.0

Makes a mutable reference into the given `Arc`.

If there are other `Arc` or `Weak` pointers to the same value, then `make_mut` will invoke `clone` on the inner value to ensure unique ownership. This is also referred to as clone-on-write.

See also `get_mut`, which will fail rather than cloning.

# Examples

    use std::sync::Arc;

    let mut data = Arc::new(5);

    *Arc::make_mut(&mut data) += 1;         // Won't clone anything
    let mut other_data = data.clone();      // Won't clone inner data
    *Arc::make_mut(&mut data) += 1;         // Clones inner data
    *Arc::make_mut(&mut data) += 1;         // Won't clone anything
    *Arc::make_mut(&mut other_data) *= 2;   // Won't clone anything

    // Now `data` and `other_data` point to different values.
    assert_eq!(*data, 8);
    assert_eq!(*other_data, 12);

### `impl<T: ?Sized> Arc<T>`
[src]

#### `fn get_mut(this: &mut Self) -> Option<&mut T>`
1.4.0

Returns a mutable reference to the inner value, if there are no other `Arc` or `Weak` pointers to the same value.

Returns `None` otherwise, because it is not safe to mutate a shared value.

See also `make_mut`, which will `clone` the inner value when it's shared.

# Examples

    use std::sync::Arc;

    let mut x = Arc::new(3);
    *Arc::get_mut(&mut x).unwrap() = 4;
    assert_eq!(*x, 4);

    let _y = x.clone();
    assert!(Arc::get_mut(&mut x).is_none());

## Trait Implementations

### `impl<T: ?Sized + Sync + Send> Send for Arc<T>`
[src]

### `impl<T: ?Sized + Sync + Send> Sync for Arc<T>`
[src]

### `impl<T: ?Sized + Unsize<U>, U: ?Sized> CoerceUnsized<Arc<U>> for Arc<T>`
[src]

### `impl<T: ?Sized> Clone for Arc<T>`
[src]

#### `fn clone(&self) -> Arc<T>`

Makes a clone of the `Arc` pointer.

This creates another pointer to the same inner value, increasing the strong reference count.

# Examples

    use std::sync::Arc;

    let five = Arc::new(5);

    five.clone();

#### `fn clone_from(&mut self, source: &Self)`

Performs copy-assignment from `source`. Read more

### `impl<T: ?Sized> Deref for Arc<T>`
[src]

#### `type Target = T`

The resulting type after dereferencing

#### `fn deref(&self) -> &T`

The method called to dereference a value

### `impl<T: ?Sized> Drop for Arc<T>`
[src]

#### `fn drop(&mut self)`

Drops the `Arc`.

This will decrement the strong reference count. If the strong reference count reaches zero then the only other references (if any) are `Weak`, so we `drop` the inner value.

# Examples

    use std::sync::Arc;

    struct Foo;

    impl Drop for Foo {
        fn drop(&mut self) {
            println!("dropped!");
        }
    }

    let foo  = Arc::new(Foo);
    let foo2 = foo.clone();

    drop(foo);    // Doesn't print anything
    drop(foo2);   // Prints "dropped!"

### `impl<T: ?Sized + PartialEq> PartialEq for Arc<T>`
[src]

#### `fn eq(&self, other: &Arc<T>) -> bool`

Equality for two `Arc`s.

Two `Arc`s are equal if their inner values are equal.

# Examples

    use std::sync::Arc;

    let five = Arc::new(5);

    assert!(five == Arc::new(5));

#### `fn ne(&self, other: &Arc<T>) -> bool`

Inequality for two `Arc`s.

Two `Arc`s are unequal if their inner values are unequal.

# Examples

    use std::sync::Arc;

    let five = Arc::new(5);

    assert!(five != Arc::new(6));

### `impl<T: ?Sized + PartialOrd> PartialOrd for Arc<T>`
[src]

#### `fn partial_cmp(&self, other: &Arc<T>) -> Option<Ordering>`

Partial comparison for two `Arc`s.

The two are compared by calling `partial_cmp()` on their inner values.

# Examples

    use std::sync::Arc;
    use std::cmp::Ordering;

    let five = Arc::new(5);

    assert_eq!(Some(Ordering::Less), five.partial_cmp(&Arc::new(6)));

#### `fn lt(&self, other: &Arc<T>) -> bool`

Less-than comparison for two `Arc`s.

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

# Examples

    use std::sync::Arc;

    let five = Arc::new(5);

    assert!(five < Arc::new(6));

#### `fn le(&self, other: &Arc<T>) -> bool`

'Less than or equal to' comparison for two `Arc`s.

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

# Examples

    use std::sync::Arc;

    let five = Arc::new(5);

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

#### `fn gt(&self, other: &Arc<T>) -> bool`

Greater-than comparison for two `Arc`s.

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

# Examples

    use std::sync::Arc;

    let five = Arc::new(5);

    assert!(five > Arc::new(4));

#### `fn ge(&self, other: &Arc<T>) -> bool`

'Greater than or equal to' comparison for two `Arc`s.

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

# Examples

    use std::sync::Arc;

    let five = Arc::new(5);

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

### `impl<T: ?Sized + Ord> Ord for Arc<T>`
[src]

#### `fn cmp(&self, other: &Arc<T>) -> Ordering`

Comparison for two `Arc`s.

The two are compared by calling `cmp()` on their inner values.

# Examples

    use std::sync::Arc;
    use std::cmp::Ordering;

    let five = Arc::new(5);

    assert_eq!(Ordering::Less, five.cmp(&Arc::new(6)));

### `impl<T: ?Sized + Eq> Eq for Arc<T>`
[src]

### `impl<T: ?Sized + Display> Display for Arc<T>`
[src]

#### `fn fmt(&self, f: &mut Formatter) -> Result`

Formats the value using the given formatter.

### `impl<T: ?Sized + Debug> Debug for Arc<T>`
[src]

#### `fn fmt(&self, f: &mut Formatter) -> Result`

Formats the value using the given formatter.

### `impl<T: ?Sized> Pointer for Arc<T>`
[src]

#### `fn fmt(&self, f: &mut Formatter) -> Result`

Formats the value using the given formatter.

### `impl<T: Default> Default for Arc<T>`
[src]

#### `fn default() -> Arc<T>`

Creates a new `Arc<T>`, with the `Default` value for `T`.

# Examples

    use std::sync::Arc;

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

### `impl<T: ?Sized + Hash> Hash for Arc<T>`
[src]

#### `fn hash<H: Hasher>(&self, state: &mut H)`

Feeds this value into the state given, updating the hasher as necessary.

#### `fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher`
1.3.0

Feeds a slice of this type into the state provided.

### `impl<T> From<T> for Arc<T>`
1.6.0
[src]

#### `fn from(t: T) -> Self`

Performs the conversion.

### `impl<T: ?Sized> Borrow<T> for Arc<T>`
[src]

#### `fn borrow(&self) -> &T`

Immutably borrows from an owned value. Read more

### `impl<T: ?Sized> AsRef<T> for Arc<T>`
1.5.0
[src]

#### `fn as_ref(&self) -> &T`

Performs the conversion.

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)