Struct arc_swap::Cache

pub struct Cache<A, T> { /* fields omitted */ }

Caching handle for ArcSwapAny.

Instead of loading the Arc on every request from the shared storage, this keeps another copy inside itself. Upon request it only cheaply revalidates it is up to date. If it is, access is significantly faster. If it is stale, the load_full is done and the cache value is replaced. Under a read-heavy loads, the measured speedup are 10-25 times, depending on the architecture.

There are, however, downsides:

• The handle needs to be kept around by the caller (usually, one per thread). This is fine if there's one global ArcSwapAny, but starts being tricky with eg. data structures build from them.
• As it keeps a copy of the Arc inside the cache, the old value may be kept alive for longer period of time ‒ it is replaced by the new value on load. You may not want to use this if dropping the old value in timely manner is important (possibly because of releasing large amount of RAM or because of closing file handles).

Examples

use std::sync::Arc;

use arc_swap::{ArcSwap, Cache};

let shared = Arc::new(ArcSwap::from_pointee(42));
// Start 10 worker threads...
for _ in 0..10 {
    let mut cache = Cache::new(Arc::clone(&shared));
    std::thread::spawn(move || {
        // Keep loading it like mad..
        loop {
            let value = cache.load();
            do_something(value);
        }
    });
}
shared.store(Arc::new(12));

Methods

impl<A, T, S> Cache<A, T> where
    A: Deref<Target = ArcSwapAny<T, S>>,
    T: RefCnt,
    S: LockStorage, 

pub fn new(arc_swap: A) -> Self

Creates a new caching handle.

The parameter is something dereferencing into an ArcSwapAny (eg. either to ArcSwap or ArcSwapOption). That can be ArcSwapAny itself, but that's not very useful. But it also can be a reference to it or Arc, which makes it possible to share the ArcSwapAny with multiple caches or access it in non-cached way too.

pub fn arc_swap(&self) -> &A::Target

Gives access to the (possibly shared) cached ArcSwapAny.

pub fn load(&mut self) -> &T

Loads the currently held value.

This first checks if the cached value is up to date. This check is very cheap.

If it is up to date, the cached value is simply returned without additional costs. If it is outdated, a load is done on the underlying shared storage. The newly loaded value is then stored in the cache and returned.

Trait Implementations

impl<A, T, S> From<A> for Cache<A, T> where
    A: Deref<Target = ArcSwapAny<T, S>>,
    T: RefCnt,
    S: LockStorage, 

fn from(arc_swap: A) -> Self

Performs the conversion.

impl<A: Clone, T: Clone> Clone for Cache<A, T>

fn clone(&self) -> Cache<A, T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<A: Debug, T: Debug> Debug for Cache<A, T>

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

Formats the value using the given formatter.