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

pub struct Arc<T: ?Sized> {
    // some 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.

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
        });
    }
}

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
    });
}

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

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

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

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

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

fn weak_count(this: &Self) -> usize

Unstable (arc_counts #28356)

: not clearly useful, and racy

Get the number of weak references to this value.

fn strong_count(this: &Self) -> usize

Unstable (arc_counts #28356)

: not clearly useful, and racy

Get the number of strong references to this value.

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

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

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

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

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

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

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<T>.

This increases 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<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 drop

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

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

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

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

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

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

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

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

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

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

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

'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);

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

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

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

'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);

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

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

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]

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>

Returns the "default value" for a type. Read more

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.