Struct Arc 

pub struct Arc<T, S: Strategy> { /* private fields */ }

Transferable reference counted type.

This type works like a per-affinity (per-thread) sync::Arc. Each affinity gets a unique value that is shared by clones of the Arc, but the ThreadAware implementation ensures that when moving to another affinity, the resulting Arc will point to the value in the destination affinity. See new for information on constructing instances.

ThreadAware of different clones of the Arc result in “deduplication” in the destination affinity. The following example demonstrates this using the counter implemented in the documentation for the ThreadAware trait.

let arc_affinity1 = Arc::<_, PerThread>::new(Counter::new);
let arc_affinity1_clone = arc_affinity1.clone();

arc_affinity1.increment_by(42);
assert_eq!(arc_affinity1.value(), 42);

let arc_affinity2 = arc_affinity1.relocated(affinity1, affinity2);
assert_eq!(arc_affinity2.value(), 0);
assert_eq!(arc_affinity1_clone.value(), 42);

arc_affinity2.increment_by(11);
let arc_affinity2_clone = arc_affinity1_clone.relocated(affinity1, affinity2);
assert_eq!(arc_affinity2_clone.value(), 11);

Implementations

impl<T, S> Arc<T, S>

where T: Send + 'static, S: Strategy,

pub fn new(ctor: fn() -> T) -> Self

Creates a new Arc with the given value and strategy.

This variant takes a zero-argument constructor function (fn() -> T). The constructor is invoked lazily and independently for each processor the first time a PerCore is materialized on that processor (i.e. on the first transfer into that processor). This guarantees that every processor obtains its own freshly created T without requiring T: Clone or T: ThreadAware.

Requirements:

• T must be Send + 'static so it can live in the processor storage.
• The provided function must be pure with respect to per-processor isolation (it should not leak references into other processors). Any captured state should therefore be provided via globally shareable mechanisms or prefer new_with if you need to capture data that itself implements ThreadAware.

When transferring to another affinity which doesn’t yet contain a value, the constructor is called in the destination affinity to create a brand new instance.

For example, the counter type we implemented in the documentation for ThreadAware trait can be used with new by passing the constructor function (note the absence of ()):

let container = Arc::<_, PerThread>::new(Counter::new);
let container_clone = container.clone();
container.increment_by(42);
assert_eq!(container.value(), 42);
assert_eq!(container_clone.value(), 42);

impl<T, S> Arc<T, S>

where T: 'static, S: Strategy,

pub fn new_with<D>(data: D, f: fn(D) -> T) -> Self

where D: ThreadAware + Send + Sync + Clone + 'static,

Creates a new Arc with a closure that will be called once per-processor to create the inner value.

The closure only gets called once for each processor, and it’s called only when a Arc is actually transferred to another processor. The closure behaves like a RelocateFnOnce to ensure it captures only values that are safe to transfer themselves.

This function can be used to create a Arc of a type that itself doesn’t implement ThreadAware because we can ensure that each affinity will get its own, independenty-initialized value:

struct MyStruct {
    inner: sync::Arc<Mutex<i32>>,
}

impl MyStruct {
    fn new() -> Self {
        Self {
            inner: sync::Arc::new(Mutex::new(0)),
        }
    }
}

let container = Arc::<_, PerThread>::new_with((), |_| MyStruct::new());

The constructor can depend on other values that implement ThreadAware (this example uses the Counter defined in ThreadAware documentation):

struct MyStruct;

impl MyStruct {
    fn new(value: i32) -> Self {
        Self
    }
}

let counter = Counter::new();
let container = Arc::<_, PerThread>::new_with(counter, |counter| MyStruct::new(counter.value()));

impl<T, S: Strategy> Arc<T, S>

where T: Clone + 'static + Send,

pub fn from_unaware(value: T) -> Self

Creates a new Arc with the given value.

The value must implement Clone. When transferring to another affinity which doesn’t yet contain a value, a new value is created by cloning the value in current affinity and transferring it to the new affinity.

This is useful for types that do not implement ThreadAware. In such cases, the same value is cloned for each affinity without any relocation logic.

For example, the counter type we implemented in the documentation for ThreadAware trait can be used with new:

let arc = Arc::<_, PerThread>::new(Counter::new);
let arc_clone = arc.clone();
arc.increment_by(42);
assert_eq!(arc.value(), 42);
assert_eq!(arc_clone.value(), 42);

impl<T, S: Strategy> Arc<T, S>

where T: 'static,

pub fn from_storage( storage: Arc<RwLock<Storage<Arc<T>, S>>>, current_affinity: PinnedAffinity, ) -> Self

Creates a new Arc from the given storage and the current affinity.

If the resulting Arc is transferred to an affinity which does not have data in the storage, it will behave like a sync::Arc.

Panics

This may panic if the storage does not contain data for the current affinity.

impl<T, S: Strategy> Arc<T, S>

pub fn into_arc(self) -> Arc<T>

Converts the Arc<T, S> into an sync::Arc<T>.

Trait Implementations

impl<T, S: Strategy> Clone for Arc<T, S>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug, S: Debug + Strategy> Debug for Arc<T, S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, S: Strategy> Deref for Arc<T, S>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: Hash, S: Strategy> Hash for Arc<T, S>

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

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: Ord, S: Strategy> Ord for Arc<T, S>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T: PartialEq, S: Strategy> PartialEq for Arc<T, S>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: PartialOrd, S: Strategy> PartialOrd for Arc<T, S>

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

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T, S: Strategy> ThreadAware for Arc<T, S>

fn relocated(self, source: MemoryAffinity, destination: PinnedAffinity) -> Self

Consume a value and return a value in the destination affinity.

impl<T: Eq, S: Strategy> Eq for Arc<T, S>