Struct Orbital 

pub struct Orbital<T: CellType> { /* private fields */ }

One cell, typed. Cheap to clone; every clone is the same place.

Implementations

impl<T: CellType> Orbital<T>

pub fn id(&self) -> CellId

pub fn load(&self) -> Result<T>

pub fn store(&self, value: T) -> Result<()>

pub fn swap(&self, value: T) -> Result<T>

Replace the value and return what it was.

pub fn version(&self) -> Result<u32>

The write count, the thing Self::wait_changed waits on. Take it before reading the value, and the wait misses nothing in between.

pub fn wait_changed(&self, since: u32) -> Result<u32>

Park until the cell has been written since since, then return the count now. Coalescing: ten writes while parked wake the caller once, and Self::load gives the latest. A released cell wakes every waiter with Error::Stale. Blocking; an async runtime wraps it.

pub fn compare_exchange(&self, current: T, new: T) -> Result<Result<T, T>>

Store new only if the cell still holds current. Ok(Ok(previous)) on success, Ok(Err(actual)) when it held something else.

pub fn release(self) -> Result<()>

Give the cell back; this and every other handle to it go stale.

impl Orbital<i64>

pub fn fetch_add(&self, by: i64) -> Result<i64>

Add by (negative to subtract) and return the value after.

pub fn fetch_sub(&self, by: i64) -> Result<i64>

pub fn add_until(&self, by: i64, limit: i64) -> Result<Claim>

Add up to by while the value stays at or under limit, in one compare-and-swap, and say what was taken.

This is the operation a fleet needs to divide a fixed amount of work between processes that cannot see each other. fetch_add followed by a test cannot do it: the add lands before the caller learns it went too far, so N callers overshoot by up to N-1 between them. Here the bound is decided inside the swap, so the value never passes limit however many callers race, and the one that finds less than by left takes the remainder instead of being turned away.

Taking more than one at a time is how the cost comes down: the contended word is touched once per claim rather than once per unit. limit is the ceiling for the total, never for a single call.

Overflow needs no separate guard: a result that cannot pass limit cannot pass i64::MAX either.

A claim is not a lease. What this hands back is gone from the total the moment the swap lands, and nothing gives it back: a caller that takes a hundred, does forty and then dies leaves sixty that nobody will ever do, while the count says all hundred were taken. So by is not only a speed dial, it is the exposure — the most one death can lose. It is the same trade a database sequence makes with its cache size, and it leaves the same kind of gap. Work that must not be lost wants a lease whose owner notices a death, which is orbit-pool, not a counter.

impl Orbital<u64>

pub fn fetch_add(&self, by: u64) -> Result<u64>

pub fn fetch_sub(&self, by: u64) -> Result<u64>

impl Orbital<f64>

pub fn fetch_add(&self, by: f64) -> Result<f64>

Add by and return the value after. A compare-and-swap loop: floats have no fetch-add of their own.

impl Orbital<bool>

pub fn set(&self) -> Result<bool>

Set the flag and return whether it was already set.

pub fn clear(&self) -> Result<bool>

Clear the flag and return whether it was set.

Trait Implementations

impl<T: Clone + CellType> Clone for Orbital<T>

fn clone(&self) -> Orbital<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.