Struct Atom
pub struct Atom<T>{ /* private fields */ }Expand description
An atomically swapped value, from the kovan crate: see its docs.
A single-value container with safe memory reclamation: loads, stores and
swaps are wait-free, and rcu() is lock-free (it retries only
after another thread’s write).
Provides cheap reads via load() and atomic writes
via store(), swap(), and
rcu(). Old values are automatically retired through
kovan’s wait-free reclamation.
Unlike ArcSwap, Atom<T> works with any T: Send + Sync + 'static:
there is no requirement to wrap values in Arc.
§Examples
use kovan::Atom;
// Create and read
let config = Atom::new(vec![1, 2, 3]);
assert_eq!(config.load().len(), 3);
// Atomic update: readers see old or new, never torn
config.store(vec![4, 5, 6, 7]);
assert_eq!(config.load().len(), 4);Implementations§
§impl<T> Atom<T>
impl<T> Atom<T>
pub fn new(val: T) -> Atom<T>
pub fn new(val: T) -> Atom<T>
Creates a new Atom containing val.
The value is heap-allocated and managed by kovan’s reclamation system.
§Examples
use kovan::Atom;
let atom = Atom::new(42);pub fn into_inner(self) -> T
pub fn into_inner(self) -> T
Consumes the Atom and returns the inner value.
This is safe because consuming self guarantees no concurrent access.
§Examples
use kovan::Atom;
let atom = Atom::new(String::from("hello"));
let s = atom.into_inner();
assert_eq!(s, "hello");pub fn load(&self) -> AtomGuard<'_, T>
pub fn load(&self) -> AtomGuard<'_, T>
Loads the current value, returning a guard that dereferences to &T.
This is the cheapest read operation: a pin, one atomic load and an
epoch check against the pin’s cache. The returned [AtomGuard] keeps the value alive;
it will not be reclaimed until the guard is dropped.
§Consistency
Call load() once and reuse the guard for multiple accesses to
ensure you see a consistent snapshot. Calling load() multiple
times may return different values if another thread updated
the Atom in between.
§Examples
use kovan::Atom;
let atom = Atom::new(42);
let val = atom.load();
assert_eq!(*val, 42);pub fn load_clone(&self) -> Twhere
T: Clone,
pub fn load_clone(&self) -> Twhere
T: Clone,
Loads and clones the current value.
Equivalent to atom.load().clone() but expressed as a single call.
Use this when you need an owned copy and T: Clone.
§Examples
use kovan::Atom;
let atom = Atom::new(vec![1, 2, 3]);
let owned: Vec<i32> = atom.load_clone();pub fn peek<R>(&self, f: impl FnOnce(&T) -> R) -> R
pub fn peek<R>(&self, f: impl FnOnce(&T) -> R) -> R
Calls a closure with a reference to the current value.
This is useful when you want to inspect the value without holding onto a guard. The closure runs within a kovan critical section.
§Examples
use kovan::Atom;
let atom = Atom::new(vec![1, 2, 3]);
let len = atom.peek(|v| v.len());
assert_eq!(len, 3);pub fn store(&self, val: T)
pub fn store(&self, val: T)
Atomically replaces the current value.
The old value is retired for safe reclamation: it will be freed once no reader holds a guard referencing it.
§Examples
use kovan::Atom;
let atom = Atom::new(1);
atom.store(2);
assert_eq!(*atom.load(), 2);pub fn swap(&self, val: T) -> Removed<T>
pub fn swap(&self, val: T) -> Removed<T>
Atomically replaces the current value and returns the previous one
wrapped in [Removed<T>].
The old value stays in its node, where readers that loaded it before
the swap still read it, and the returned [Removed<T>] derefs to that
same object. Unlike store(), the old node is not
retired at once: dropping the Removed<T> retires it, and T’s
destructor runs once no reader is left.
§Examples
use kovan::Atom;
let atom = Atom::new(String::from("hello"));
let old = atom.swap(String::from("world"));
assert_eq!(*old, "hello");
assert_eq!(*atom.load(), "world");pub fn compare_and_swap<'a>(
&'a self,
current: &AtomGuard<'_, T>,
new: T,
) -> Result<AtomGuard<'a, T>, T>
pub fn compare_and_swap<'a>( &'a self, current: &AtomGuard<'_, T>, new: T, ) -> Result<AtomGuard<'a, T>, T>
Compare-and-swap: atomically replace the value if it hasn’t changed.
Loads the current pointer, compares it to current’s pointer. If they
match, stores new and retires the old value. Returns Ok(guard) with
the new value on success, or Err(new) returning the rejected value.
§Examples
use kovan::Atom;
let atom = Atom::new(1);
let current = atom.load();
// This succeeds because nobody changed it
assert!(atom.compare_and_swap(¤t, 2).is_ok());
assert_eq!(*atom.load(), 2);pub fn rcu<F>(&self, f: F)
pub fn rcu<F>(&self, f: F)
Read-Copy-Update: atomically apply a transformation.
Loads the current value, calls f(&T) to produce a new value,
then attempts a CAS. If another thread modified the value between
the load and CAS, the operation retries automatically.
The closure f may be called multiple times on contention.
Keep it cheap: do expensive work before calling rcu.
§Examples
use kovan::Atom;
let counter = Atom::new(0u64);
// Thread-safe increment (retries on contention)
counter.rcu(|val| val + 1);
assert_eq!(*counter.load(), 1);pub fn map<'a, R, F>(&'a self, f: F) -> AtomMap<'a, T, R, F>
pub fn map<'a, R, F>(&'a self, f: F) -> AtomMap<'a, T, R, F>
Create a mapped view that projects into a field of T.
Returns an [AtomMap] that loads T and applies f to project
into a sub-field. Useful for passing configuration sub-sections
to components without exposing the full T.
Keep f cheap: it runs on every load.
§Examples
use kovan::Atom;
struct Config { db_port: u16, workers: usize }
let config = Atom::new(Config { db_port: 5432, workers: 4 });
let port_view = config.map(|c| &c.db_port);
assert_eq!(*port_view.load(), 5432);