minerva 0.2.0

Causal ordering for distributed systems
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

//! The causal stamp and the clocks that mint it.
//!
//! [`Kairos`] packs four fields into one `u128`, in comparison order:
//! physical time (64 bits), a logical counter (16 bits), a caller-defined
//! kairotic tag (16 bits), and station identity (32 bits). The natural
//! integer order of the packed word is the stamp order. `to_bytes` and
//! `from_bytes` give the canonical 17-byte wire form.
//!
//! Two shells mint stamps with Hybrid Logical Clock rules:
//!
//! - [`Clock`] is the thread-safe shell. It commits each advance with one
//!   compare-and-swap. Below the `u64::MAX` physical ceiling a stamp never
//!   decreases, also when the time source steps backward; at the ceiling
//!   the clock pins rather than wraps (the documented saturation edge).
//! - [`LocalClock`] is the single-threaded shell: the same fold through a
//!   `Cell`, with no fences and no retries. It is `!Sync` by construction.
//!
//! [`Clock::observe`] folds a remote stamp in (the HLC receive rule).
//! [`Clock::try_observe`] bounds the forward skew a remote stamp can
//! inject and refuses with [`SkewExceeded`]. [`Clock::now_run`] reserves
//! consecutive send positions in one commitment and returns an affine
//! [`KairosRun`] receipt.
//!
//! The [`TimeSource`] seam supplies physical readings. [`TickCounter`] and
//! [`VirtualTimeSource`] are the deterministic `no_std` sources for tests
//! and simulation. The `chronos` module supplies OS-backed sources with
//! the `std` feature. [`Backoff`] shapes contention retries in the
//! thread-safe shell; strategies count spins and never read time.
//!
//! [`Kairos`]: crate::kairos::Kairos
//! [`Clock`]: crate::kairos::Clock
//! [`LocalClock`]: crate::kairos::LocalClock
//! [`Clock::observe`]: crate::kairos::Clock::observe
//! [`Clock::try_observe`]: crate::kairos::Clock::try_observe
//! [`SkewExceeded`]: crate::kairos::SkewExceeded
//! [`Clock::now_run`]: crate::kairos::Clock::now_run
//! [`KairosRun`]: crate::kairos::KairosRun
//! [`TimeSource`]: crate::kairos::TimeSource
//! [`TickCounter`]: crate::kairos::TickCounter
//! [`VirtualTimeSource`]: crate::kairos::VirtualTimeSource
//! [`Backoff`]: crate::kairos::Backoff

mod backoff;
mod clock;
mod stamp;
#[cfg(test)]
mod tests;
mod time;

pub use backoff::{
    Backoff, BackoffStrategy, ConstantBackoff, ExponentialBackoff, ModelBasedBackoff,
};
pub use clock::{
    Clock, ClockConfig, ClockStats, DynClock, DynLocalClock, InvalidStationId, KairosRun,
    KairosRunIter, LocalClock, SkewExceeded,
};
pub use stamp::{DecodeError, KAIROS_WIRE_LEN, Kairos, ToU16};
pub use time::{TickCounter, TimeSource, VirtualTimeSource};