Expand description
Abstracting over accessing parts of stored value.
Sometimes, there’s a big globalish data structure (like a configuration for the whole program). Then there are parts of the program that need access to up-to-date version of their part of the configuration, but for reasons of code separation and reusability, it is not desirable to pass the whole configuration to each of the parts.
This module provides means to grant the parts access to the relevant subsets of such global data structure while masking the fact it is part of the bigger whole from the component.
Note that the cache module has its own Access trait that
serves a similar purpose, but with cached access. The signatures are different, therefore an
incompatible trait.
The general idea
Each part of the code accepts generic Access<T> for the T of its interest. This
provides means to load current version of the structure behind the scenes and get only the
relevant part, without knowing what the big structure is.
For technical reasons, the Access trait is not object safe. If type erasure is desired, it
is possible use the DynAccess instead, which is object safe, but
slightly slower.
For some cases, it is possible to use ArcSwapAny::map. If that is not flexible enough, the
Map type can be created directly.
Note that the Access trait is also implemented for ArcSwapAny itself. Additionally,
there’s the Constant helper type, which is useful mostly for testing
(it doesn’t allow reloading).
Performance
In general, these utilities use ArcSwapAny::load internally and then apply the provided
transformation. This has several consequences:
- Limitations of the
loadapply ‒ including the recommendation to not hold the returned guard object for too long, but long enough to get consistency. - The transformation should be cheap ‒ optimally just borrowing into the structure.
Examples
extern crate arc_swap;
use std::sync::Arc;
use std::thread;
use std::time::Duration;
use arc_swap::ArcSwap;
use arc_swap::access::{Access, Constant, Map};
fn work_with_usize<A: Access<usize> + Send + 'static>(a: A) {
thread::spawn(move || {
loop {
let value = a.load();
println!("{}", *value);
// Not strictly necessary, but dropping the guard can free some resources, like
// slots for tracking what values are still in use. We do it before the sleeping,
// not at the end of the scope.
drop(value);
thread::sleep(Duration::from_millis(50));
}
});
}
// Passing the whole thing directly
// (If we kept another Arc to it, we could change the value behind the scenes)
work_with_usize(Arc::new(ArcSwap::from_pointee(42)));
// Passing a subset of a structure
struct Cfg {
value: usize,
}
let cfg = Arc::new(ArcSwap::from_pointee(Cfg { value: 0 }));
work_with_usize(Map::new(Arc::clone(&cfg), |cfg: &Cfg| &cfg.value));
cfg.store(Arc::new(Cfg { value: 42 }));
// Passing a constant that can't change. Useful mostly for testing purposes.
work_with_usize(Constant(42));