orbit_rs/
lib.rs

1//! # `orbit-rs` — fleet-aware shared-memory rings
2//!
3//! See the repository `VISION.md` for the broader design direction.
4//!
5//! ## What this crate is
6//!
7//! Fleet-shared, network-aware ring storage — the same-host tier between
8//! APCu (per-worker) and Redis (cross-host).
9//!
10//! ```text
11//! local var       — register-fast,    no sharing
12//! APCu            — process-fast,     per-worker
13//! Orbit           — fleet-shared,     same-host    ← here
14//! Redis           — cluster-shared,   cross-host
15//! PostgreSQL      — durable,          cross-time
16//! ```
17//!
18//! ## What this crate is NOT
19//!
20//! - **Not bound to any application framework.** The crate exposes
21//!   runtime primitives; framework-specific wiring belongs in adapter
22//!   crates above it.
23//! - **Not a service.** Orbit has its own fleet handle, but no
24//!   application lifecycle.
25//! - **Not a database or message broker.** The crate exposes rings and
26//!   small substrates such as `OrbitCache`; product-facing services live
27//!   in adapters above it.
28//!
29//! ## Three Musketeers
30//!
31//! > *Hepimiz birimiz, birimiz hepimiz. — Dumas*
32//! >
33//! > *All for one, one for all.*
34//!
35//! Every process in the fleet is an equal member. There is no master,
36//! no worker — only peers. Whatever role distinction matters to the
37//! embedder is the embedder's concern; not Orbit's.
38//!
39//! ## Status — first light (V0)
40//!
41//! V0 ships the ring API surface plus POSIX shared-memory backing on
42//! Unix. Higher-level data shapes should build on rings/cache directly
43//! instead of adding one-off shared cells here.
44
45pub mod cache;
46pub mod contest;
47pub mod error;
48pub mod event;
49pub mod fleet;
50pub mod orbital;
51pub mod ring;
52#[cfg(unix)]
53pub mod shm;
54pub mod tick;
55pub mod typed;
56
57pub mod id {
58    //! Re-export of the standalone `netid64` primitive.
59
60    pub use netid64::{NetId64, ParseNetId64Error};
61}
62
63#[cfg(unix)]
64pub mod ring_shm {
65    //! Compatibility module for the pre-`ring::shm` layout.
66    pub use crate::ring::shm::*;
67}
68
69#[cfg(unix)]
70pub use cache::{CACHE_PAYLOAD_MAX, OrbitCache, OrbitCacheEntry, OrbitCacheRead};
71pub use contest::guard::{
72    CONTEST_FRAME_KIND_CLAIM, CONTEST_FRAME_KIND_RELEASE, CONTEST_PAYLOAD_MAX, CONTEST_RING_KIND,
73    Claim, Contest, ContestOwner, ContestRecord, ContestSubject, ContestType, Guard, Holder,
74};
75pub use error::{Error, Result};
76pub use event::{
77    EVENT_PAYLOAD_MAX, EVENT_RING_KIND, OrbitEvent, OrbitEventBus, OrbitEventCursor, OrbitEventPoll,
78};
79pub use fleet::{
80    DEFAULT_RING_CAPACITY, FLEET_HEARTBEAT_RING_KIND, Fleet, FleetHeartbeat, FleetHeartbeatRecord,
81    FleetHeartbeatSnapshot, NodeId,
82};
83pub use id::{NetId64, ParseNetId64Error};
84pub use orbital::Orbital;
85pub use ring::cursor::{RingCursor, RingFrameSource, RingLoss, RingPoll, poll_ring};
86pub use ring::{Frame, Ring};
87pub use tick::OrbitEpoch;
88pub use typed::OrbitTyped;
orbit_rs/lib.rs

orbit_rs/
lib.rs
