Struct alloc::arc::Arc1.0.0 [] [src]

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

An atomically reference counted wrapper for shared state. Destruction is deterministic, and will occur as soon as the last owner is gone. It is marked as Send because it uses atomic reference counting.

If you do not need thread-safety, and just need shared ownership, consider the Rc<T> type. It is the same as Arc<T>, but does not use atomics, making it both thread-unsafe as well as significantly faster when updating the reference count.

Note: the inherent methods defined on Arc<T> are all associated functions, which means that you have to call them as e.g. Arc::get_mut(&value) instead of value.get_mut(). This is so that there are no conflicts with methods on the inner type T, which are what you want to call in the majority of cases.

Examples

In this example, a large vector of data will be shared by several threads. First we wrap it with a Arc::new and then clone the Arc<T> reference for every thread (which will increase the reference count atomically).

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

fn main() {
    let numbers: Vec<_> = (0..100).collect();
    let shared_numbers = Arc::new(numbers);

    for _ in 0..10 {
        // prepare a copy of reference here and it will be moved to the thread
        let child_numbers = shared_numbers.clone();

        thread::spawn(move || {
            let local_numbers = &child_numbers[..];

            // Work with the local numbers
        });
    }
}Run

You can also share mutable data between threads safely by putting it inside Mutex and then share Mutex immutably with Arc<T> as shown below.

use std::sync::{Arc, Mutex};
use std::thread;

let five = Arc::new(Mutex::new(5));

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

    thread::spawn(move || {
        let mut number = five.lock().unwrap();

        *number += 1;

        println!("{}", *number); // prints 6
    });
}Run

Methods

impl<T> Arc<T>
[src]

Constructs a new Arc<T>.

Examples

use std::sync::Arc;

let five = Arc::new(5);Run

Unwraps the contained value if the Arc<T> has exactly one strong reference.

Otherwise, an Err is returned with the same Arc<T>.

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), Err(Arc::new(4)));Run

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

Downgrades the Arc<T> to a Weak<T> reference.

Examples

use std::sync::Arc;

let five = Arc::new(5);

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

Unstable (arc_counts #28356)

: not clearly useful, and racy

Get the number of weak references to this value.

Unstable (arc_counts #28356)

: not clearly useful, and racy

Get the number of strong references to this value.

Unstable (ptr_eq #36497)

: newly added

Return whether two Arc references point to the same value (not just values that compare 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));Run

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

Make a mutable reference into the given Arc<T>. If the Arc<T> has more than one strong reference, or any weak references, the inner data is cloned.

This is also referred to as a copy-on-write.

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

// Note: data and other_data now point to different numbers
assert_eq!(*data, 8);
assert_eq!(*other_data, 12);
Run

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

Returns a mutable reference to the contained value if the Arc<T> has one strong reference and no weak references.

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());Run

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]

Makes a clone of the Arc<T>.

This increases the strong reference count.

Examples

use std::sync::Arc;

let five = Arc::new(5);

five.clone();Run

Performs copy-assignment from source. Read more

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

The resulting type after dereferencing

The method called to dereference a value

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

Drops the Arc<T>.

This will decrement the strong reference count. If the strong reference count becomes zero and the only other references are Weak<T> ones, drops the inner value.

Examples

use std::sync::Arc;

{
    let five = Arc::new(5);

    // stuff

    drop(five); // explicit drop
}
{
    let five = Arc::new(5);

    // stuff

} // implicit dropRun

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

Equality for two Arc<T>s.

Two Arc<T>s are equal if their inner value are equal.

Examples

use std::sync::Arc;

let five = Arc::new(5);

five == Arc::new(5);Run

Inequality for two Arc<T>s.

Two Arc<T>s are unequal if their inner value are unequal.

Examples

use std::sync::Arc;

let five = Arc::new(5);

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

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

Partial comparison for two Arc<T>s.

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

Examples

use std::sync::Arc;

let five = Arc::new(5);

five.partial_cmp(&Arc::new(5));Run

Less-than comparison for two Arc<T>s.

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

Examples

use std::sync::Arc;

let five = Arc::new(5);

five < Arc::new(5);Run

'Less-than or equal to' comparison for two Arc<T>s.

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

Examples

use std::sync::Arc;

let five = Arc::new(5);

five <= Arc::new(5);Run

Greater-than comparison for two Arc<T>s.

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

Examples

use std::sync::Arc;

let five = Arc::new(5);

five > Arc::new(5);Run

'Greater-than or equal to' comparison for two Arc<T>s.

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

Examples

use std::sync::Arc;

let five = Arc::new(5);

five >= Arc::new(5);Run

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

This method returns an Ordering between self and other. Read more

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

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

Formats the value using the given formatter.

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

Formats the value using the given formatter.

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

Formats the value using the given formatter.

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

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

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

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

Feeds a slice of this type into the state provided.

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

Performs the conversion.

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

Immutably borrows from an owned value. Read more

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

Performs the conversion.