Expand description
subetha-cxc - CXC (Cross-Context Channel): memory-mapped file
primitives for cross-thread, cross-process, and disk-persistent
communication.
The name comes from Douglas Adams’s Hitchhiker’s Guide to the Galaxy: the Sub-Etha Sens-O-Matic uses sub-etheric waves to communicate around conventional channels. CXC does the same thing - it skips the kernel’s conventional channel (named pipes, sockets, IPC handles) and writes directly to user-space memory the kernel page-aliases between participants.
Four cooperating modules:
shared_ring: MPMC lock-free ring backed by an MMFheartbeat: per-process liveness slots in an MMF tablefailover: watchdog that reclaims work from dead processespass_registry: closure registry for cross-process Pass dispatchscheduler: BackgroundScheduler tying the above into an autonomous executor
§The unifying mechanism
Every primitive in this crate uses one mechanism: a file-mapped MMF region. That single mechanism gives:
- Cross-thread communication (threads in one process map the same file; lock-free CAS handles concurrency).
- Cross-process communication (different processes open the same file; the OS page-cache aliases them onto the same physical pages).
- Disk persistence (the MMF is backed by a real file; data survives process death and can be reopened later).
The same byte layout serves all three. There is no separate “shared memory” vs “disk” abstraction; the MMF is both at once.
§Architectural pattern
Bare OS IPC primitives (named pipes, sockets, anonymous shared memory) hide useful metadata: which logical stream a message belongs to, what priority it has, whether the peer is alive, when the data needs to hit disk. The protocol layer here names each of those as a first-class field so the application can reason about (and direct) the substrate’s behaviour.
The win over OS pipes/sockets is the same shape as QUIC over TCP: userspace transport eliminates the kernel from the hot path. A pipe write costs ~20us (CreateFile + WriteFile syscalls); a SharedRing slot publish is ~50-200ns (atomic CAS + fence). That’s a ~100x improvement that vanishes the moment a Mutex enters the picture.
Re-exports§
pub use epoch_barrier::BarrierError;pub use epoch_barrier::EpochBarrier;pub use epoch_barrier::DEFAULT_BARRIER_GRACE_EPOCHS;pub use event_state_log::EventLogError;pub use event_state_log::EventStateLog;pub use failover::FailoverWatchdog;pub use failover::ReclaimReport;pub use failover::DEFAULT_GRACE_EPOCHS;pub use k_tower_cascade::CascadeError;pub use k_tower_cascade::CascadeResolver2;pub use k_tower_cascade::CascadeResolverN;pub use k_tower_cascade::KTowerCascade;pub use k_tower_cascade::NIL_INDEX as CASCADE_NIL_INDEX;pub use lazy_config::LazyConfig;pub use lazy_config::LazyConfigError;pub use owner_lease::LeaseError;pub use owner_lease::LeaseHeader;pub use owner_lease::LeasePayload;pub use owner_lease::OwnerLease;pub use owner_lease::LEASE_FILE_SIZE;pub use owner_lease::LEASE_MAGIC;pub use owner_lease::NO_OWNER;pub use owner_lease::PAYLOAD_BYTES as LEASE_PAYLOAD_BYTES;pub use heartbeat::HeartbeatError;pub use heartbeat::HeartbeatHeader;pub use heartbeat::HeartbeatSlot;pub use heartbeat::HeartbeatSnapshot;pub use heartbeat::HeartbeatTable;pub use heartbeat::EMPTY_PID;pub use heartbeat::HEARTBEAT_MAGIC;pub use heartbeat::IN_FLIGHT_SLOTS;pub use pass_registry::execute as execute_pass;pub use pass_registry::is_registered;pub use pass_registry::register as register_handler;pub use pass_registry::registered_count;pub use pass_registry::unregister as unregister_handler;pub use pass_registry::Pass;pub use pass_registry::PassError;pub use pass_registry::PassHandler;pub use pass_registry::PassResult;pub use priority_fanout::FanoutError;pub use priority_fanout::PriorityFanout;pub use priority_fanout::MAX_PRIORITIES;pub use progress_task::ProgressReporter;pub use progress_task::ProgressTask;pub use progress_task::ProgressTaskError;pub use scheduler::BackgroundScheduler;pub use scheduler::ResultCollector;pub use scheduler::SchedError;pub use scheduler::SubmittedResult;pub use scheduler::Submitter;pub use shared_bit_vec::bit_vec_file_size;pub use shared_bit_vec::BitVecError;pub use shared_bit_vec::BitVecHeader;pub use shared_bit_vec::BITS_PER_WORD;pub use shared_bit_vec::BITVEC_MAGIC;pub use shared_blocked_bloom_filter::BlockedBloomError;pub use shared_bloom_filter::BloomError;pub use shared_bloom_filter::BloomHeader;pub use shared_bloom_filter::BLOOM_MAGIC;pub use shared_broadcast_ring::broadcast_file_size;pub use shared_broadcast_ring::BroadcastError;pub use shared_broadcast_ring::BroadcastHeader;pub use shared_broadcast_ring::BroadcastSlot;pub use shared_broadcast_ring::BROADCAST_MAGIC;pub use shared_broadcast_ring::BROADCAST_PAYLOAD_BYTES;pub use shared_broadcast_ring::MAX_CONSUMERS;pub use shared_cell::CellHeader;pub use shared_cell::CELL_FILE_SIZE;pub use shared_cell::CELL_MAGIC;pub use shared_cell::PAYLOAD_BYTES as CELL_PAYLOAD_BYTES;pub use shared_count_min_sketch::cms_file_size;pub use shared_count_min_sketch::CMSError;pub use shared_count_min_sketch::CMSHeader;pub use shared_count_min_sketch::CMS_MAGIC;pub use dispatch_deque::DequeDispatcher;pub use dispatch_deque::DequeVariant;pub use dispatch_deque::DispatchError;pub use dispatch_deque::DispatcherBuilder;pub use dispatch_deque::WorkloadShape;pub use message_transport::MessageTransport;pub use message_transport::PassSlot;pub use message_transport::TransportError;pub use mmf_dispatcher::MmfDispatcher;pub use mmf_dispatcher::MmfFamily;pub use mmf_dispatcher::MmfWorkloadShape;pub use api::ApiError;pub use api::AutoIpc;pub use api::Channel;pub use api::KvMap;pub use api::WorkStealQueue;pub use adaptive_ipc::AdaptiveIpc;pub use adaptive_ipc::AdaptiveIpcSidecar;pub use adaptive_ipc::PinnedIpc;pub use adaptive_ipc::ProfileSnapshot;pub use shared_deque::deque_file_size;pub use shared_deque::slot_bytes_for;pub use shared_deque::DequeError;pub use shared_deque::DequeHeader;pub use shared_deque::DEQUE_MAGIC;pub use shared_deque_khl::khl_file_size;pub use shared_deque_khl::KhlHeader;pub use shared_deque_khl::KhlSlot;pub use shared_deque_khl::PublishRadius as KhlPublishRadius;pub use shared_deque_khl::PushError as KhlPushError;pub use shared_deque_khl::Steal as KhlSteal;pub use shared_deque_khl::StealResult as KhlStealResult;pub use shared_deque_khl::KHL_ITEMS_PER_SLOT;pub use shared_deque_khl::KHL_MAGIC;pub use shared_deque_khl::KHL_SLOT_SIZE;pub use shared_deque_khpd::khpd_file_size;pub use shared_deque_khpd::FatLineItem;pub use shared_deque_khpd::KhpdHeader;pub use shared_deque_khpd::LineItem;pub use shared_deque_khpd::PublicationLine;pub use shared_deque_khpd::PushError as KhpdPushError;pub use shared_deque_khpd::Steal as KhpdSteal;pub use shared_deque_khpd::StealResult as KhpdStealResult;pub use shared_deque_khpd::KHPD_ITEM_BYTES;pub use shared_deque_khpd::KHPD_LINE_SIZE;pub use shared_deque_khpd::KHPD_MAGIC;pub use shared_deque_khpd::LINE_ITEMS;pub use shared_deque_loh::loh_file_size;pub use shared_deque_loh::LcrqJobSlot;pub use shared_deque_loh::LohHeader;pub use shared_deque_loh::PushError as LohPushError;pub use shared_deque_loh::Steal as LohSteal;pub use shared_deque_loh::StealResult as LohStealResult;pub use shared_deque_loh::DEFAULT_LIFO_CAP as LOH_DEFAULT_LIFO_CAP;pub use shared_deque_loh::LOH_MAGIC;pub use shared_deque_loh::LOH_SLOT_SIZE;pub use shared_deque_urd::urd_file_size;pub use shared_deque_urd::Drain as UrdDrain;pub use shared_deque_urd::DrainResult as UrdDrainResult;pub use shared_deque_urd::Mailbox;pub use shared_deque_urd::PublishError as UrdPublishError;pub use shared_deque_urd::PublishStrategy as UrdPublishStrategy;pub use shared_deque_urd::UrdHeader;pub use shared_deque_urd::WaitStrategy;pub use shared_deque_urd::MAILBOX_ITEMS;pub use shared_deque_urd::URD_MAGIC;pub use shared_deque_urd::URD_MAILBOX_SIZE;pub use shared_fence_clock::fence_clock_file_size;pub use shared_fence_clock::FenceClockError;pub use shared_fence_clock::Hlc;pub use shared_fence_clock::HlcHeader;pub use shared_fence_clock::HlcSlot;pub use shared_fence_clock::HlcSlotSnapshot;pub use shared_fence_clock::FENCE_CLOCK_MAGIC;pub use shared_graph::EdgeIndex;pub use shared_graph::GraphEdge;pub use shared_graph::GraphError;pub use shared_graph::GraphNode;pub use shared_graph::NodeIndex;pub use shared_graph::NIL_INDEX as GRAPH_NIL_INDEX;pub use shared_handle_table::handle_table_file_size;pub use shared_handle_table::slot_offset;pub use shared_handle_table::Handle;pub use shared_handle_table::HandleHeader;pub use shared_handle_table::HandleTableError;pub use shared_handle_table::HANDLE_TABLE_MAGIC;pub use shared_handle_table::NIL_SLOT;pub use shared_handle_table::SLOT_PAYLOAD_BYTES;pub use shared_hash_map::fnv1a_64;pub use shared_hash_map::map_file_size;pub use shared_hash_map::InsertOutcome;pub use shared_hash_map::MapError;pub use shared_hash_map::MapHeader;pub use shared_hash_map::MapSlot;pub use shared_hash_map::MAP_MAGIC;pub use shared_hash_map::MAP_PAYLOAD_BYTES;pub use shared_hash_map::SLOT_EMPTY;pub use shared_hash_map::SLOT_OCCUPIED;pub use shared_hash_map::SLOT_TOMBSTONE;pub use shared_histogram::histogram_file_size;pub use shared_histogram::HistogramError;pub use shared_histogram::HistogramHeader;pub use shared_histogram::HISTOGRAM_MAGIC;pub use shared_hyper_log_log::hll_file_size;pub use shared_hyper_log_log::HLLError;pub use shared_hyper_log_log::HLLHeader;pub use shared_hyper_log_log::HLL_MAGIC;pub use shared_hyper_log_log::MAX_PRECISION as HLL_MAX_PRECISION;pub use shared_hyper_log_log::MIN_PRECISION as HLL_MIN_PRECISION;pub use shared_leader_election::LeaderError;pub use shared_leader_election::LeaderHeader;pub use shared_leader_election::DEFAULT_GRACE_EPOCHS as LEADER_DEFAULT_GRACE_EPOCHS;pub use shared_leader_election::LEADER_FILE_SIZE;pub use shared_leader_election::LEADER_MAGIC;pub use shared_leader_election::NO_LEADER;pub use shared_linked_list::LinkedListError;pub use shared_linked_list::Node as LinkedListNode;pub use shared_linked_list::NodeHandle;pub use shared_linked_list::HEAD_INDEX as LINKED_LIST_HEAD_INDEX;pub use shared_linked_list::NIL_INDEX as LINKED_LIST_NIL_INDEX;pub use shared_lru_cache::LRUError;pub use shared_nan_tagged_value::NaNTaggedType;pub use shared_nan_value::NaNValueType;pub use shared_nan_value::BOXED_MASK;pub use shared_nan_value::BOXED_PREFIX;pub use shared_nan_value::CANONICAL_QNAN;pub use shared_nan_value::PAYLOAD_MASK;pub use shared_nan_value::TAG_BOOL;pub use shared_nan_value::TAG_I32;pub use shared_nan_value::TAG_MASK;pub use shared_nan_value::TAG_NIL;pub use shared_nan_value::TAG_OFFSET_PTR;pub use shared_nan_value::TAG_SHIFT;pub use shared_nan_value::TAG_TAGGED_OFFSET_PTR;pub use shared_nan_value::TAG_U32;pub use shared_once_cell::OnceHeader;pub use shared_once_cell::ONCE_FILE_SIZE;pub use shared_once_cell::ONCE_MAGIC;pub use shared_once_cell::ONCE_PAYLOAD_BYTES;pub use shared_once_cell::STATE_EMPTY;pub use shared_once_cell::STATE_INITIALIZED;pub use shared_once_cell::STATE_INITIALIZING;pub use shared_rate_limiter::RateLimiterError;pub use shared_rate_limiter::RateLimiterHeader;pub use shared_rate_limiter::RATE_LIMITER_MAGIC;pub use shared_region::region_file_size;pub use shared_region::OffsetPtr;pub use shared_region::RegionError;pub use shared_region::RegionHeader;pub use shared_region::NIL_INDEX;pub use shared_region::REGION_MAGIC;pub use shared_reservoir_sampler::reservoir_file_size;pub use shared_reservoir_sampler::ReservoirError;pub use shared_reservoir_sampler::ReservoirHeader;pub use shared_reservoir_sampler::ReservoirSlot;pub use shared_reservoir_sampler::RESERVOIR_MAGIC;pub use shared_reservoir_sampler::RESERVOIR_SLOT_PAYLOAD;pub use shared_ring::ring_file_size;pub use shared_ring::Consumer as SpscConsumer;pub use shared_ring::Producer as SpscProducer;pub use shared_ring::RingError;pub use shared_ring::RingHeader;pub use shared_ring::Slot;pub use shared_ring::PAYLOAD_BYTES;pub use shared_ring::RING_MAGIC;pub use shared_ring::SLOT_SIZE;pub use frame_ring::frame_ring_file_size;pub use frame_ring::FrameClass;pub use frame_ring::FrameRing;pub use frame_ring::LayoutHint;pub use frame_ring::DESC_HEADER_BYTES;pub use frame_ring::FRAME_MAGIC;pub use frame_ring::MIN_SLOT_SIZE;pub use frame_region::frame_region_file_size;pub use frame_region::FrameRegion;pub use frame_region::FRAME_REGION_MAGIC;pub use frame_region::MIN_BLOCK_SIZE;pub use mpsc_ring::MpscConsumer;pub use mpsc_ring::MpscFifoConsumer;pub use mpsc_ring::MpscFifoProducer;pub use mpsc_ring::MpscProducer;pub use mpmc_ring::MpmcConsumer;pub use mpmc_ring::MpmcProducer;pub use adaptive_ring::AdaptiveError;pub use adaptive_ring::AdaptiveRing;pub use adaptive_ring::AdaptiveRingSidecar;pub use adaptive_ring::DefaultOrderingPolicy;pub use adaptive_ring::DefaultRingShapePolicy;pub use adaptive_ring::OrderingPolicy;pub use adaptive_ring::OrderingPolicyObservation;pub use adaptive_ring::PinnedRing;pub use adaptive_ring::PolicyObservation;pub use adaptive_ring::QosRingShapePolicy;pub use adaptive_ring::RingShape;pub use adaptive_ring::RingShapePolicy;pub use adaptive_ring::ADAPTIVE_SPSC_PAYLOAD_BYTES;pub use adaptive_ring::ADAPTIVE_VYUKOV_PAYLOAD_BYTES;pub use adaptive_ring::DRAINER_GRACE_EPOCHS;pub use cache_ops::cldemote;pub use cache_ops::has_cldemote;pub use cache_ops::prefetchw;pub use cache_ops::sfence;pub use mmf_warm::warm_mmap;pub use mmf_warm::warm_region;pub use monitor_wait::monitor_wait_budget_cycles;pub use monitor_wait::monitor_wait_kind;pub use monitor_wait::monitor_wait_u32;pub use monitor_wait::monitor_wait_u32_with;pub use monitor_wait::monitor_wait_u64;pub use monitor_wait::monitor_wait_u64_with;pub use monitor_wait::MonitorWaitKind;pub use monitor_wait::DEFAULT_MONITOR_BUDGET_CYCLES;pub use ordering::default_stamp_kind;pub use ordering::has_invariant_tsc;pub use ordering::ordering_region_size;pub use ordering::OrderingHeader;pub use ordering::OrderingMode;pub use ordering::OrderingRegion;pub use ordering::StampKind;pub use ordering::MONOTONIC_FRESHNESS_GUARD_NANOS;pub use ordering::ORDERING_MAGIC;pub use ordering::STAMPED_PAYLOAD_BYTES;pub use ordering::STAMP_BYTES;pub use ordering::TSC_FRESHNESS_GUARD_CYCLES;pub use qos_policy::Durability;pub use qos_policy::History;pub use qos_policy::Ordering as QosOrdering;pub use qos_policy::QosPolicy;pub use qos_policy::QosSnapshot;pub use qos_policy::Reliability;pub use capacity_adaptive_ring::BackingTarget;pub use capacity_adaptive_ring::CapacityAdaptiveRing;pub use capacity_adaptive_ring::CapacityAdaptiveRingSidecar;pub use capacity_adaptive_ring::CapacityMorphError;pub use capacity_adaptive_ring::CapacityPolicy;pub use capacity_adaptive_ring::CapacityPolicyObservation;pub use capacity_adaptive_ring::DefaultCapacityPolicy;pub use capacity_adaptive_ring::PinnedCapacity;pub use capacity_adaptive_ring::RingConfig;pub use policy_gate::min_samples_for_arity;pub use policy_gate::ConfidenceGate;pub use policy_gate::GateConfig;pub use unified_policy::UnifiedObservation;pub use unified_policy::UnifiedPolicy;pub use unified_policy::UnifiedSidecar;pub use unified_policy::UnifiedWeights;pub use phase_estimator::PhaseConfig;pub use phase_estimator::PhaseEstimator;pub use capacity_broadcast_ring::BroadcastCapacityMorphError;pub use capacity_broadcast_ring::CapacityBroadcastRing;pub use capacity_broadcast_ring::PinnedBroadcastCapacity;pub use capacity_pubsub_ring::CapacityPubSubRing;pub use capacity_pubsub_ring::CapacityPubSubSubscriber;pub use capacity_pubsub_ring::PubSubCapacityMorphError;pub use blocking_spsc_ring::BlockingError;pub use blocking_spsc_ring::BlockingSpscRing;pub use blocking_spsc_ring::PhaseRecvStats;pub use blocking_mpsc_ring::BlockingMpscConsumer;pub use blocking_mpsc_ring::BlockingMpscProducer;pub use blocking_mpsc_ring::BlockingMpscRing;pub use blocking_mpmc_ring::BlockingMpmcConsumer;pub use blocking_mpmc_ring::BlockingMpmcProducer;pub use blocking_mpmc_ring::BlockingMpmcRing;pub use cross_process_waker::CrossProcessWaker;pub use cross_process_waker::WakerError;pub use cross_process_waker::WakerToken;pub use cross_process_waker::MAX_WAITERS_DEFAULT;pub use cross_process_waker::WAKER_MAGIC;pub use cross_process_waker::waker_region_size;pub use shared_condvar::CondvarError;pub use async_ring::AsyncRecv;pub use async_ring::AsyncSend;pub use async_ring::AsyncSpscRing;pub use blocking_semaphore::BlockingPermit;pub use blocking_semaphore::BlockingSemaphore;pub use blocking_semaphore::BlockingSemaphoreError;pub use blocking_rw_lock::BlockingReadGuard;pub use blocking_rw_lock::BlockingRWLock;pub use blocking_rw_lock::BlockingRWLockError;pub use blocking_rw_lock::BlockingWriteGuard;pub use locale_adaptive_ring::DefaultLocalePolicy;pub use locale_adaptive_ring::Locale;pub use locale_adaptive_ring::LocaleAdaptiveRing;pub use locale_adaptive_ring::LocaleAdaptiveRingSidecar;pub use locale_adaptive_ring::LocalePolicy;pub use locale_adaptive_ring::LocalePolicyObservation;pub use locale_adaptive_ring::PinnedLocale;pub use shared_rw_lock::ReadGuard;pub use shared_rw_lock::RWLockError;pub use shared_rw_lock::RWLockHeader;pub use shared_rw_lock::WriteGuard;pub use shared_rw_lock::RWLOCK_MAGIC;pub use shared_semaphore::Permit;pub use shared_semaphore::SemaphoreError;pub use shared_btree_map::BTreeError;pub use shared_string_arena::arena_file_size;pub use shared_string_arena::ArenaError;pub use shared_string_arena::ArenaHeader;pub use shared_string_arena::StringRef;pub use shared_string_arena::ARENA_MAGIC;pub use shared_time_point::tile_file_size;pub use shared_time_point::TileError;pub use shared_time_point::TileHeader;pub use shared_time_point::VersionedSlot;pub use shared_time_point::SLOT_PAYLOAD;pub use shared_time_point::TILE_CAP;pub use shared_time_point::TIME_POINT_MAGIC;pub use shared_topology_map::topology_file_size;pub use shared_topology_map::TopologyError;pub use shared_topology_map::TopologyHeader;pub use shared_topology_map::TopologyKind;pub use shared_topology_map::TopologyStats;pub use shared_topology_map::DEFAULT_FAN_IN_THRESHOLD;pub use shared_topology_map::DEFAULT_FAN_OUT_THRESHOLD;pub use shared_topology_map::TOPOLOGY_MAGIC;pub use shared_treiber_stack::stack_file_size;pub use shared_treiber_stack::StackError;pub use shared_treiber_stack::StackHeader;pub use shared_treiber_stack::STACK_MAGIC;pub use shared_treiber_stack::STACK_NIL;pub use shared_universal::Strategy as UniversalStrategy;pub use shared_universal::UniversalError;pub use shared_universal::UniversalHeader;pub use shared_universal::UNIVERSAL_MAGIC;pub use shared_vec::vec_file_size;pub use shared_vec::VecError;pub use shared_vec::VecHeader;pub use shared_vec::VecSlot;pub use shared_vec::VEC_MAGIC;pub use shared_vec::VEC_PAYLOAD_BYTES;pub use shared_versioned_chain::versioned_chain_file_size;pub use shared_versioned_chain::ChainError;pub use shared_versioned_chain::ChainHeader;pub use shared_versioned_chain::VersionNode;pub use shared_versioned_chain::NIL_NODE;pub use shared_versioned_chain::NODE_PAYLOAD_BYTES;pub use shared_versioned_chain::VERSIONED_CHAIN_MAGIC;pub use tagged_offset_ptr::TaggedOffsetPtr;pub use tagged_offset_ptr::TaggedPtrError;
Modules§
- adaptive_
ipc AdaptiveIpc<T>: runtime profile-and-migrate IPC, kernel-bypass preserved end-to-end, hot path optimised to ~zero overhead vs direct dispatch.- adaptive_
ring AdaptiveRing- shape-morphing ring with a pinned-handle layer.- api
- Top-level user-facing IPC API.
- async_
ring AsyncSpscRing:Future-shaped async adapter on top ofcrate::blocking_spsc_ring::BlockingSpscRing.- bbr
- BBR congestion control for the RLC transport’s send path.
- blocking_
mpmc_ ring BlockingMpmcRing: composed-SPSC MPMC grid with cross-process futex-shapedsend_blocking/recv_blocking.- blocking_
mpsc_ ring BlockingMpscRing: composed-SPSC MPSC fan-in with cross-process futex-shapedsend_blocking/recv_blocking.- blocking_
rw_ lock BlockingRWLock: cross-process reader-writer lock with a kernel-park slow path viaCrossProcessWaker.- blocking_
semaphore BlockingSemaphore: cross-process counting semaphore with a kernel-park slow path viaCrossProcessWaker.- blocking_
spsc_ ring BlockingSpscRing: SPSC ring with cross-process futex-shapedrecv_blocking(timeout)/send_blocking(timeout).- burst_
model_ sensor - Gilbert-Elliott burst-loss model fitted online from the loss trace, giving a REAL mean burst length instead of a jitter-ratio heuristic.
- cache_
ops - Cache-line stewardship: instruction-level hints the compiler never emits on its own.
- cached_
clock - Process-global cached wall clock.
- capacity_
adaptive_ ring CapacityAdaptiveRing: runtime-resizable wrapper aroundAdaptiveRingthat adds capacity-axis morphing to the polymorphic substrate.- capacity_
broadcast_ ring CapacityBroadcastRing: runtime-resizable wrapper aroundSharedBroadcastRingthat adds the capacity-axis morph to the broadcast (1P/NC fan-out) primitive.- capacity_
pubsub_ ring CapacityPubSubRing: runtime-resizable wrapper aroundPubSubRingthat adds the capacity-axis morph to the pub/sub (1P/NC absolute-position) primitive.- compressed_
udp - Schema-aware structural compression wrapped around the reliable-UDP transport at the item boundary.
- control_
frame - The control plane as a QUIC-style frame container.
- control_
table - The atomic control table: the lock-free bridge between the slow sensor/controller loop and the fast per-packet data path.
- cpu_
affinity - Cross-platform CPU core pinning for controlled measurements.
- cross_
process_ waker CrossProcessWaker: a futex-shaped wait/wake primitive sitting in shared memory (MMF or named-shm), portable across Linux / Windows / macOS / FreeBSD.- dgram
dgram: a pluggable datagram backend for the RLC transport.- dispatch_
deque DequeDispatcher- per-call routing across the MMF-deque family.- epoch_
barrier EpochBarrier- multi-process phase synchronization with heartbeat-driven dead-peer exclusion.- event_
state_ log EventStateLog<Event, State>- event-sourced state with materialized view.- failover
FailoverWatchdog- scans the heartbeat table and reclaims in-flight work whose owning process has stopped beating.- fd_
handoff fd_handoff: live cross-process handle handoff (cross-platform).- fec
- Forward error correction over GF(256): systematic Cauchy Reed-Solomon erasure coding.
- forecast_
sensor - Item 16: Sprout-style stochastic forecast of the deliverable rate.
- frame_
region FrameRegion- concurrent fixed-block payload region for the self-describing offset path shared by everyAdaptiveRingshape.- frame_
ring FrameRing- self-describing variable-payload SPSC ring.- fusion
- Sensor fusion: turn loss / burstiness / delay-trend readings into a
coding decision, behind a swappable
FusionPolicyso the arbitration strategy is chosen empirically rather than hard-coded. - heartbeat
- Per-process heartbeat slots stored in an MMF.
- hugepages
hugepages: Linux-only hugepage-backed mmap helper.- interleave
- Block interleaving: a sender-side transmit-order permutation that converts a burst loss into a spread loss the per-block FEC can recover.
- k_
tower_ cascade KTowerCascade<T, const DEPTH: usize>- recursive pow2-of-pow2 pointer encoding, the userspace MMU primitive.- kernel_
async_ ring kernel_async_ring: the kernel async-I/O ring (io_uring on Linux, IoRing on Windows, POSIX aio on FreeBSD / macOS) exposed as a substrate ring primitive.- lazy_
config LazyConfig<T>- thundering-herd-proof distributed config fetch.- link_
sensor - Cross-platform link-quality sensing: the radio / interface stats the adaptive controller reads to anticipate loss before the in-band loss estimate sees it.
- locale_
adaptive_ ring LocaleAdaptiveRing: same-host locale-axis morph for the ring family.- locale_
vsock locale_vsock: host-VM byte streaming that bypasses the network stack (cross-platform).- loss_
class_ sensor - Loss-class sensor: congestion-vs-wireless loss differentiation.
- message_
transport MessageTransport- byte-slice transport trait for theBackgroundScheduler, abstracting overSharedRing(MPMC) andSharedDeque<PassSlot>(SPMC work-stealing).- mmf_
dispatcher MmfDispatcher- per-call routing across the MMF primitive families.- mmf_
warm - MMF warm-up: prefault a freshly mapped region in one call instead of paying a page fault per 4 KiB on first touch.
- monitor_
wait - Monitor-based wait tier: hardware MONITOR/MWAIT-class waiting between the spin tier and the kernel-park tier.
- mpmc_
ring SharedRingMpmc- composed multi-producer / multi-consumer ring built from N independent Lamport SPSC rings, with M consumers partitioning the rings round-robin.- mpsc_
ring SharedRingMpsc- composed multi-producer / single-consumer ring built from N independent Lamport SPSC rings.- net_
bridge net_bridge: a TCP bridge with NO async runtime. One connection ferries a producer ring on one host to a consumer ring on another, using blockingstd::netsockets on dedicated threads.- net_
events - Active OS path-event observer: a background watcher that fires the instant the kernel’s route table, an interface carrier, or the path MTU changes - ahead of any loss.
- net_
tune - Linux TCP socket tuning for the bridge data paths. Each knob is
a direct
setsockopt; all are advisory (failures are ignored - the socket works untuned) and the whole module is a no-op off Linux. - ordering
- Ordering substrate for
AdaptiveRing: push stamps, the cross-process ordering header, per-producer watermarks, and the single-drainer lease. - owner_
lease OwnerLease<T>- cross-process Mutex with auto-failover.- pass_
registry - Closure registry for cross-process
Pass<F>dispatch. - path_
model_ sensor - BBR-style passive path model: bottleneck bandwidth, round-trip propagation delay, and the bandwidth-delay product, all recovered from the ACK stream the reliable-UDP sender already drives - no probe traffic.
- path_
sensor - Path sensing from the peer’s TTL / ECN observations.
- peer_
directory PeerDirectory- the shared topology substrate behind the automaticAdaptiveRing.- periodicity_
sensor - Item 17: LEO periodic-handover detection from the OWD trace.
- phase_
estimator - Consumer-local arrival-phase estimator for predictive waiting.
- policy_
gate - Confidence gating for sidecar policy decisions.
- priority_
fanout PriorityFanout- tiered work queue with O(1) priority selection.- progress_
task ProgressTask<R>- distributed work with live cross-process progress visibility.- protocol_
direct_ file DirectFileRing: non-mmap positioned-I/O ring that bypasses the OS page cache (cross-platform).- protocol_
pubsub PubSubRing: one-producer many-subscriber broadcast primitive with per-subscriber positions.- qos_
policy QosPolicy: DDS-inspired Quality-of-Service knobs that sidecar policies read as input alongside peer counts and workload shape.- reactor
reactor: the bridge that makes a SubEtha ring a first-class async source ACROSS processes, not just across threads.- reliable_
udp - Sens-O-Matic protocol: a reliable-UDP transport, FEC-primary, ARQ-fallback.
- reorder
- Consumer-side exact-delivery reorder buffer for the best-effort
MergeByStamp(merge_tsc) ordering mode. - replay_
positions SubscriberPosition: Aeron-inspired MMF-resident position counter for resumable cross-process subscribers.- ring_
contract RingContract- the declared operation envelope for a ring.- ring_
executor RingExecutor: an async executor whose READY QUEUE is built from SubEtha rings. The future’s handle rides through a ring; the ring IS the scheduler, not a data channel beside one.- rlc_
control - Adaptive control for the sliding-window RLC code: turn the fused channel
assessment (
crate::fusion::SensorSnapshot) into RLC coding parameters - the window size, the repair cadence (code rate), and the coefficient density - then hold them steady with immediate-up / conservative-down hysteresis so the knobs do not flap on a noisy channel. - rlc_fec
- Sliding-window Random Linear Code (RLC) forward erasure correction: a convolutional erasure code that interleaves repair symbols with the source symbols over a sliding window, so an isolated loss is recovered from the next repair without waiting for a block boundary.
- rtt_
shape_ sensor - Link-type fingerprint from the SHAPE of the RTT distribution - no new packets, no OS wireless read.
- salvage
- Intra-packet salvage: recover a packet the kernel would discard for a CRC failure, instead of treating it as a total loss.
- scheduler
BackgroundScheduler- autonomous Pass executor backed bySharedRing+HeartbeatTable+FailoverWatchdog+ thepass_registryclosure table.- schema_
codec - Schema-aware structural compression for fixed-width bridge slots.
- sens_
rlc - Sens-O-Matic transport carrying the sliding-window RLC erasure code (the
adaptive, optionally-TLS code; the block Reed-Solomon code lives in
udp_bridge). The RLC coding internals are inrlc_fec/rlc_control. Sens-O-Matic transport carrying the sliding-window RLC erasure code. Sens-O-Matic is the reliable FEC-UDP protocol; the erasure code is its swappable detail (like a cipher suite). This module is the variant that carries the sliding-window Random Linear Code (crate::rlc_fec): it ships items as source symbols with interleaved RLC repair symbols, recovering an isolated loss without a retransmit round trip. A NAK-driven ARQ floor guarantees eventual delivery for losses the coding window cannot cover. The public types areSensOMaticRlcSender/SensOMaticRlcReceiver. - sens_
unified - Unified Sens-O-Matic endpoint: one transport carrying both erasure codes, switching RLC <-> RS mid-stream on the loss the receiver feeds back (the loss-driven auto-switch, with operator override). Unified Sens-O-Matic endpoint: one transport that carries BOTH erasure codes and switches between them mid-stream on the loss the receiver already measures and feeds back.
- sharded_
udp - Sharded reliable-UDP: N independent Sens-O-Matic streams, each on its own thread, distributing the WHOLE data path (encode + flow + send on the way out, recv + decode + deliver on the way in) across N cores.
- shared_
async_ pointer SharedAsyncPointer<T>- cross-process lazy / speculative resolution wrapping aSharedOnceCell<T>.- shared_
atomic SharedAtomic<T>- cross-process atomic counter / flag.- shared_
bit_ vec SharedBitVec- cross-process bit-packed boolean array.- shared_
blocked_ bloom_ filter SharedBlockedBloomFilter- cache-blocked cross-process Bloom filter.- shared_
bloom_ filter SharedBloomFilter- cross-process probabilistic set membership.- shared_
broadcast_ ring SharedBroadcastRing- single-producer, multi-consumer pub/sub ring backed by an MMF.- shared_
btree_ map SharedBTreeMap- cross-process MMF B-tree ordered map.- shared_
cell SharedCell<T>- cross-process single-value cell using the SeqLock protocol over a memory-mapped file.- shared_
condvar SharedCondvar: cross-process condition variable built on top ofCrossProcessWaker.- shared_
count_ min_ sketch SharedCountMinSketch- cross-process probabilistic frequency estimator.- shared_
deque SharedDeque<T>- cross-thread / cross-process Chase-Lev work- stealing deque backed by a memory-mapped file.- shared_
deque_ fcl SharedDequeFcl- Fat Chase-Lev: counter-only Chase-Lev withK_inner = 3items per slot.- shared_
deque_ khl SharedDequeKhl- K-axis Hierarchical LCRQ deque, MMF-backed.- shared_
deque_ khpd SharedDequeKhpd- K-axis Hierarchical Publication Deque, MMF-backed.- shared_
deque_ loh SharedDequeLoh- LCRQ-on-LIFO Hybrid deque, MMF-backed.- shared_
deque_ urd SharedDequeUrd- UMWAIT Rendezvous Deque, MMF-backed.- shared_
fence_ clock SharedFenceClock- Hybrid Logical Clock (HLC) lifted to cross-process MMF.- shared_
graph SharedGraph<N, E>- cross-process directed graph with arbitrary out-degree.- shared_
handle_ table SharedHandleTable<T>- cross-process ECS-style slotmap.- shared_
hash_ map SharedHashMap<K, V>- cross-process open-addressed hash map backed by a single MMF file.- shared_
histogram SharedHistogram- cross-process bucketed counter for distribution tracking.- shared_
hyper_ log_ log SharedHyperLogLog- cross-process probabilistic distinct-count estimator.- shared_
leader_ election SharedLeaderElection- cross-process leader election with lowest-live-PID semantics and heartbeat-driven failover.- shared_
linked_ list SharedLinkedList<T>- cross-process doubly-linked list with O(1) handle-based removal.- shared_
lru_ cache SharedLRUCache<K, V>- cross-process LRU cache.- shared_
nan_ tagged_ value SharedNaNTaggedValue- NaN-boxed value where the pointer payload is aTaggedOffsetPtr.- shared_
nan_ value SharedNaNValue- 64-bit NaN-boxed heterogeneous value cell.- shared_
once_ cell SharedOnceCell<T>- cross-process init-once cell.- shared_
rate_ limiter SharedRateLimiter- cross-process token-bucket rate limiter.- shared_
region SharedRegion<T>- cross-process typed arena with position- independentOffsetPtr<T>references.- shared_
reservoir_ sampler SharedReservoirSampler<T>- cross-process uniform random sampling via Vitter’s Algorithm R.- shared_
ring SharedRing<P>- cross-thread / cross-process lock-free MPMC ring backed by a memory-mapped file.- shared_
rw_ lock SharedRWLock- cross-process reader-writer lock with writer priority.- shared_
semaphore SharedSemaphore- cross-process counting semaphore.- shared_
string_ arena SharedStringArena- append-only position-independent string pool backed by an MMF.- shared_
time_ point SharedTimePointTile<T>- cross-process BSPA + Versioned tile with AVX2 SIMD snapshot-isolation scan.- shared_
topology_ map SharedTopologyMap- K_process axis observer + recommendation substrate for cross-process message-flow topology selection.- shared_
treiber_ stack SharedTreiberStack<T>- cross-process lock-free LIFO stack.- shared_
umbra_ pointer SharedUmbraPointer<T>- cross-process content-prefixed pointer.- shared_
universal SharedUniversal<T>- Layer-2 cross-process container that migrates between Shared* backings as the workload shape changes.- shared_
vec SharedVec<T>- cross-process bounded indexable sequence.- shared_
versioned_ chain SharedVersionedChain<T>- cross-process MVCC linked list.- shm_
file ShmFile: cross-platform RAM-resident named shared-memory backing.- sidecar_
ops - Per-primitive op_kind constants for sidecar observations.
- spsc_
ring SpscRingCore- Lamport 1983 single-producer / single-consumer ring backed by a memory-mapped file.- stream_
mux - Slice 5: stream multiplexing over one connection.
- tagged_
offset_ ptr TaggedOffsetPtr<T, const TAG_BITS: u32>- high-bit-stealing variant ofOffsetPtr.- task_
pool TaskPool: a minimal bounded async executor, no external runtime.- temporal_
sensor - Temporal sensing: a purely in-band channel estimator built from send / receive timing alone.
- tower
- Cross-block (segment) outer code: the second FEC rung.
- trace_
sensor - Item 14: Trace mini-traceroute on the control stream + path asymmetry.
- udp_
bridge - Sens-O-Matic bridge: ordered, lossless item delivery over
std::net::UdpSocketwith no TLS and no async runtime. - unified_
policy - Unified cost-function policy for the capacity-adaptive ring.
- virtual_
endpoint VirtualEndpoint: substrate-level endpoint identity that resolves to either a localLocaleAdaptiveRingor a remote-via-QUIC target at runtime.- waker_
ring WakerRing: a thread-free async ring. The producer fires the consumer task’sWakerdirectly on push - no worker thread per awaiting task, no reactor, no syscall on the wake path.- wbest_
sensor - Item 13: WBest available-bandwidth estimator (receiver side).
Macros§
- register_
pass - Macro helper for static-registry style registration. Each
participating binary should call
register_pass!(ID, "name", |args| { ... })at startup.