Struct arc_swap::ArcSwapAny

pub struct ArcSwapAny<T: RefCnt, S: LockStorage = Global> { /* fields omitted */ }

An atomic storage for a reference counted smart pointer like Arc or Option<Arc>.

This is a storage where a smart pointer may live. It can be read and written atomically from several threads, but doesn’t act like a pointer itself.

One can be created from an Arc. To get the pointer back, use the load.

Note

This is the common generic implementation. This allows sharing the same code for storing both Arc and Option<Arc> (and possibly other similar types).

In your code, you most probably want to interact with it through the ArcSwap and ArcSwapOption aliases. However, the methods they share are described here and are applicable to both of them. That’s why the examples here use ArcSwap ‒ but they could as well be written with ArcSwapOption or ArcSwapAny.

Type parameters

• T: The smart pointer to be kept inside. This crate provides implementation for Arc<_> and Option<Arc<_>> (Rc too, but that one is not practically useful). But third party could provide implementations of the RefCnt trait and plug in others.
• S: This describes where the generation lock is stored and how it works (this allows tuning some of the performance trade-offs). See the LockStorage trait.

Examples

let arc = Arc::new(42);
let arc_swap = ArcSwap::from(arc);
assert_eq!(42, **arc_swap.load());
// It can be read multiple times
assert_eq!(42, **arc_swap.load());

// Put a new one in there
let new_arc = Arc::new(0);
assert_eq!(42, *arc_swap.swap(new_arc));
assert_eq!(0, **arc_swap.load());

Implementations

impl<T: RefCnt, S: LockStorage> ArcSwapAny<T, S>

pub fn new(val: T) -> Self

Constructs a new value.

pub fn into_inner(self) -> T

Extracts the value inside.

pub fn load_full(&self) -> T

Loads the value.

This makes another copy of the held pointer and returns it, atomically (it is safe even when other thread stores into the same instance at the same time).

The method is lock-free and wait-free, but usually more expensive than load.

pub fn load_signal_safe(&self) -> Guard<'_, T>

An async-signal-safe version of load

This method uses only restricted set of primitives to be async-signal-safe, so it can be used inside unix signal handlers. It has no advantages outside of them and it has its own downsides, so there’s no reason to use it outside of them.

Warning

While the method itself is lock-free (it will not be blocked by anything other threads do), methods that write are blocked from completion until the returned Guard is dropped. This includes store, compare_and_swap and rcu and destruction of the ArcSwapAny instance.

By default, the locks are shared across all the instances in the program, therefore it blocks writes even to other ArcSwapAny instances. It is possible to use a private lock (which is recommended if you want to do use this method) by using the IndependentArcSwap type alias.

pub fn load(&self) -> Guard<'static, T>

Provides a temporary borrow of the object inside.

This returns a proxy object allowing access to the thing held inside. However, there’s only limited amount of possible cheap proxies in existence for each thread ‒ if more are created, it falls back to equivalent of load_full internally.

This is therefore a good choice to use for eg. searching a data structure or juggling the pointers around a bit, but not as something to store in larger amounts. The rule of thumb is this is suited for local variables on stack, but not in long-living data structures.

Consistency

In case multiple related operations are to be done on the loaded value, it is generally recommended to call load just once and keep the result over calling it multiple times. First, keeping it is usually faster. But more importantly, the value can change between the calls to load, returning different objects, which could lead to logical inconsistency. Keeping the result makes sure the same object is used.

struct Point {
    x: usize,
    y: usize,
}

fn print_broken(p: &ArcSwap<Point>) {
    // This is broken, because the x and y may come from different points,
    // combining into an invalid point that never existed.
    println!("X: {}", p.load().x);
    // If someone changes the content now, between these two loads, we
    // have a problem
    println!("Y: {}", p.load().y);
}

fn print_correct(p: &ArcSwap<Point>) {
    // Here we take a snapshot of one specific point so both x and y come
    // from the same one.
    let point = p.load();
    println!("X: {}", point.x);
    println!("Y: {}", point.y);
}

pub fn store(&self, val: T)

Replaces the value inside this instance.

Further loads will yield the new value. Uses swap internally.

pub fn swap(&self, new: T) -> T

Exchanges the value inside this instance.

Note that this method is not lock-free. In particular, it is possible to block this method by using the load_signal_safe, but load may also block it for very short time (several CPU instructions). If this happens, swap will busy-wait in the meantime.

It is also possible to cause a deadlock (eg. this is an example of broken code):

let shared = ArcSwap::from(Arc::new(42));
let guard = shared.load_signal_safe();
// This will deadlock, because the guard is still active here and swap
// can't pull the value from under its feet.
shared.swap(Arc::new(0));

pub fn compare_and_swap<C: AsRaw<T::Base>>(
    &self,
    current: C,
    new: T
) -> Guard<'_, T>

Swaps the stored Arc if it equals to current.

If the current value of the ArcSwapAny equals to current, the new is stored inside. If not, nothing happens.

The previous value (no matter if the swap happened or not) is returned. Therefore, if the returned value is equal to current, the swap happened. You want to do a pointer-based comparison to determine it.

In other words, if the caller „guesses“ the value of current correctly, it acts like swap, otherwise it acts like load_full (including the limitations).

The current can be specified as &Arc, Guard, &Guards or as a raw pointer.

pub fn rcu<R, F>(&self, f: F) -> T where
    F: FnMut(&T) -> R,
    R: Into<T>, 

Read-Copy-Update of the pointer inside.

This is useful in read-heavy situations with several threads that sometimes update the data pointed to. The readers can just repeatedly use load without any locking. The writer uses this method to perform the update.

In case there’s only one thread that does updates or in case the next version is independent of the previous one, simple swap or store is enough. Otherwise, it may be needed to retry the update operation if some other thread made an update in between. This is what this method does.

Examples

This will not work as expected, because between loading and storing, some other thread might have updated the value.

let cnt = ArcSwap::from_pointee(0);
thread::scope(|scope| {
    for _ in 0..10 {
        scope.spawn(|_| {
           let inner = cnt.load_full();
            // Another thread might have stored some other number than what we have
            // between the load and store.
            cnt.store(Arc::new(*inner + 1));
        });
    }
}).unwrap();
// This will likely fail:
// assert_eq!(10, *cnt.load_full());

This will, but it can call the closure multiple times to retry:

let cnt = ArcSwap::from_pointee(0);
thread::scope(|scope| {
    for _ in 0..10 {
        scope.spawn(|_| cnt.rcu(|inner| **inner + 1));
    }
}).unwrap();
assert_eq!(10, *cnt.load_full());

Due to the retries, you might want to perform all the expensive operations before the rcu. As an example, if there’s a cache of some computations as a map, and the map is cheap to clone but the computations are not, you could do something like this:

fn expensive_computation(x: usize) -> usize {
    x * 2 // Let's pretend multiplication is *really expensive expensive*
}

type Cache = HashMap<usize, usize>;

static CACHE: Lazy<ArcSwap<Cache>> = Lazy::new(|| ArcSwap::default());

fn cached_computation(x: usize) -> usize {
    let cache = CACHE.load();
    if let Some(result) = cache.get(&x) {
        return *result;
    }
    // Not in cache. Compute and store.
    // The expensive computation goes outside, so it is not retried.
    let result = expensive_computation(x);
    CACHE.rcu(|cache| {
        // The cheaper clone of the cache can be retried if need be.
        let mut cache = HashMap::clone(&cache);
        cache.insert(x, result);
        cache
    });
    result
}

assert_eq!(42, cached_computation(21));
assert_eq!(42, cached_computation(21));

The cost of cloning

Depending on the size of cache above, the cloning might not be as cheap. You can however use persistent data structures ‒ each modification creates a new data structure, but it shares most of the data with the old one (which is usually accomplished by using Arcs inside to share the unchanged values). Something like rpds or im might do what you need.

pub fn map<I, R, F>(&self, f: F) -> Map<&Self, I, F> where
    F: Fn(&I) -> &R + Clone,
    Self: Access<I>, 

Provides an access to an up to date projection of the carried data.

Motivation

Sometimes, an application consists of components. Each component has its own configuration structure. The whole configuration contains all the smaller config parts.

For the sake of separation and abstraction, it is not desirable to pass the whole configuration to each of the components. This allows the component to take only access to its own part.

Lifetimes & flexibility

This method is not the most flexible way, as the returned type borrows into the ArcSwap. To provide access into eg. Arc<ArcSwap<T>>, you can create the Map type directly.

Performance

As the provided function is called on each load from the shared storage, it should generally be cheap. It is expected this will usually be just referencing of a field inside the structure.

Examples

extern crate arc_swap;
extern crate crossbeam_utils;

use std::sync::Arc;

use arc_swap::ArcSwap;
use arc_swap::access::Access;

struct Cfg {
    value: usize,
}

fn print_many_times<V: Access<usize>>(value: V) {
    for _ in 0..25 {
        let value = value.load();
        println!("{}", *value);
    }
}

let shared = ArcSwap::from_pointee(Cfg { value: 0 });
let mapped = shared.map(|c: &Cfg| &c.value);
crossbeam_utils::thread::scope(|s| {
    // Will print some zeroes and some twos
    s.spawn(|_| print_many_times(mapped));
    s.spawn(|_| shared.store(Arc::new(Cfg { value: 2 })));
}).expect("Something panicked in a thread");

impl<T, S: LockStorage> ArcSwapAny<Arc<T>, S>

pub fn from_pointee(val: T) -> Self

A convenience constructor directly from the pointed-to value.

Direct equivalent for ArcSwap::new(Arc::new(val)).

pub fn rcu_unwrap<R, F>(&self, f: F) -> T where
    F: FnMut(&T) -> R,
    R: Into<Arc<T>>, 

An rcu which waits to be the sole owner of the original value and unwraps it.

This one works the same way as the rcu method, but works on the inner type instead of Arc. After replacing the original, it waits until there are no other owners of the arc and unwraps it.

Possible use case might be an RCU with a structure that is rather slow to drop ‒ if it was left to random reader (the last one to hold the old value), it could cause a timeout or jitter in a query time. With this, the deallocation is done in the updater thread, therefore outside of the hot path.

Warning

Note that if you store a copy of the Arc somewhere except the ArcSwap itself for extended period of time, this’ll busy-wait the whole time. Unless you need the assurance the Arc is deconstructed here, prefer rcu.

impl<T, S: LockStorage> ArcSwapAny<Option<Arc<T>>, S>

pub fn from_pointee<V: Into<Option<T>>>(val: V) -> Self

A convenience constructor directly from a pointed-to value.

This just allocates the Arc under the hood.

Examples

use arc_swap::ArcSwapOption;

let empty: ArcSwapOption<usize> = ArcSwapOption::from_pointee(None);
assert!(empty.load().is_none());
let non_empty: ArcSwapOption<usize> = ArcSwapOption::from_pointee(42);
assert_eq!(42, **non_empty.load().as_ref().unwrap());

pub fn empty() -> Self

A convenience constructor for an empty value.

This is equivalent to ArcSwapOption::new(None).

Trait Implementations

impl<T: RefCnt, S: LockStorage> Access<T> for ArcSwapAny<T, S>

type Guard = Guard<'static, T>

A guard object containing the value and keeping it alive.

fn load(&self) -> Self::Guard

The loading method.

impl<T, S: LockStorage> Access<T> for ArcSwapAny<Arc<T>, S>

type Guard = DirectDeref<Arc<T>>

A guard object containing the value and keeping it alive.

fn load(&self) -> Self::Guard

The loading method.

impl<T, S: LockStorage> Access<T> for ArcSwapAny<Rc<T>, S>

type Guard = DirectDeref<Rc<T>>

A guard object containing the value and keeping it alive.

fn load(&self) -> Self::Guard

The loading method.

impl<T: RefCnt, S: LockStorage> Clone for ArcSwapAny<T, S>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T, S: LockStorage> Debug for ArcSwapAny<T, S> where
    T: Debug + RefCnt, 

fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl<T: RefCnt + Default, S: LockStorage> Default for ArcSwapAny<T, S>

fn default() -> Self

Returns the “default value” for a type.

impl<T, S: LockStorage> Display for ArcSwapAny<T, S> where
    T: Display + RefCnt, 

fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl<T: RefCnt, S: LockStorage> Drop for ArcSwapAny<T, S>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: RefCnt, S: LockStorage> From<T> for ArcSwapAny<T, S>

fn from(val: T) -> Self

Performs the conversion.