Skip to main content

Crate tsoracle_core

Crate tsoracle_core 

Source
Expand description

§tsoracle-core

Sync algorithm core for the tsoracle timestamp oracle.

No I/O, no async, no tokio. Runtime-neutral, property-testable in microseconds. Anything you need to reason about tsoracle’s timestamp generation lives here — the higher layers (tsoracle-server, tsoracle-client, the consensus drivers) are wiring around this core.

§What’s in the box

  • Allocator — the window allocator. Hands out 46/18-bit-packed Timestamps within a granted window, tracks the leader’s epoch, and exposes the WindowGrant lifecycle used by the server’s leader-watch + fence pipeline.
  • Timestamp — the 64-bit packed representation. PHYSICAL_MS_MAX and LOGICAL_MAX document the bit budget; TimestampError covers the narrow space of invalid encodings.
  • Epoch — the leader-watermark identifier the failover fence checks. Persisted alongside the high water by every ConsensusDriver impl.
  • Clock + SystemClock — the trait for “what time is it” abstraction. clock::testing exposes deterministic fakes for property tests.
  • Bt — backtrace-on-error helper. ZST and no-op unless the bt feature is on; with it on, capture is still gated by RUST_BACKTRACE / RUST_LIB_BACKTRACE.
  • CoreError — the algorithm-level error type. Server, client, and driver crates wrap it in their own variants.

§Feature flags

  • std (default) — enables std-dependent surface (most of it). Disabling gives a no_std core; the public surface shrinks but the allocator + timestamp math still work.
  • serde — derives Serialize / Deserialize on the public types so they cross wire and storage boundaries cleanly.
  • test-clock — exposes the clock::testing module to downstream test code without needing cfg(test) machinery.
  • bt — captures std::backtrace::Backtrace in instrumented error variants. Off by default to keep cold paths free.

§Documentation

Modules§

docs
Long-form documentation for tsoracle-core.

Structs§

Allocator
Bt
Epoch
SystemClock
Default implementation backed by std::time::SystemTime.
Timestamp
TsoPeer
A known peer node and the network endpoint where its TSO service can be reached for follower-redirect hints.
WindowGrant
A contiguous block of count timestamps starting at (physical_ms, logical_start), all sharing one leadership epoch.

Enums§

CommitOutcome
The result of a try_commit_window_extension that passed range validation.
CoreError
IgnoreReason
Why a CommitOutcome::Ignored commit left the durable bound unchanged.
TimestampError

Constants§

LOGICAL_MAX
PHYSICAL_MS_MAX

Traits§

Clock