subetha_cxc/
lib.rs

1//! `subetha-cxc` - CXC (Cross-Context Channel): memory-mapped file
2//! primitives for cross-thread, cross-process, and disk-persistent
3//! communication.
4//!
5//! The name comes from Douglas Adams's *Hitchhiker's Guide to the
6//! Galaxy*: the Sub-Etha Sens-O-Matic uses sub-etheric waves to
7//! communicate **around** conventional channels. CXC does the same
8//! thing - it skips the kernel's conventional channel (named pipes,
9//! sockets, IPC handles) and writes directly to user-space memory
10//! the kernel page-aliases between participants.
11//!
12//! Four cooperating modules:
13//! - [`shared_ring`]: MPMC lock-free ring backed by an MMF
14//! - [`heartbeat`]: per-process liveness slots in an MMF table
15//! - [`failover`]: watchdog that reclaims work from dead processes
16//! - [`pass_registry`]: closure registry for cross-process Pass dispatch
17//! - [`scheduler`]: BackgroundScheduler tying the above into an
18//!   autonomous executor
19//!
20//! # The unifying mechanism
21//!
22//! Every primitive in this crate uses one mechanism: a file-mapped
23//! MMF region. That single mechanism gives:
24//!
25//! 1. **Cross-thread** communication (threads in one process map the
26//!    same file; lock-free CAS handles concurrency).
27//! 2. **Cross-process** communication (different processes open the
28//!    same file; the OS page-cache aliases them onto the same
29//!    physical pages).
30//! 3. **Disk persistence** (the MMF is backed by a real file; data
31//!    survives process death and can be reopened later).
32//!
33//! The same byte layout serves all three. There is no separate
34//! "shared memory" vs "disk" abstraction; the MMF is both at once.
35//!
36//! # Architectural pattern
37//!
38//! Bare OS IPC primitives (named pipes, sockets, anonymous shared
39//! memory) hide useful metadata: which logical stream a message
40//! belongs to, what priority it has, whether the peer is alive,
41//! when the data needs to hit disk. The protocol layer here names
42//! each of those as a first-class field so the application can
43//! reason about (and direct) the substrate's behaviour.
44//!
45//! The win over OS pipes/sockets is the same shape as QUIC over
46//! TCP: userspace transport eliminates the kernel from the hot
47//! path. A pipe write costs ~20us (CreateFile + WriteFile
48//! syscalls); a SharedRing slot publish is ~50-200ns (atomic CAS +
49//! fence). That's a ~100x improvement that vanishes the moment a
50//! Mutex enters the picture.
51
52pub mod sidecar_ops;
53
54pub mod cached_clock;
55pub mod epoch_barrier;
56pub mod event_state_log;
57pub mod failover;
58pub mod k_tower_cascade;
59pub mod heartbeat;
60pub mod lazy_config;
61pub mod owner_lease;
62pub mod pass_registry;
63pub mod priority_fanout;
64pub mod progress_task;
65pub mod reorder;
66pub mod scheduler;
67pub mod shared_async_pointer;
68pub mod shared_atomic;
69pub mod shared_bit_vec;
70pub mod shared_blocked_bloom_filter;
71pub mod shared_bloom_filter;
72pub mod shared_btree_map;
73pub mod shared_broadcast_ring;
74pub mod shared_cell;
75pub mod shared_count_min_sketch;
76pub mod adaptive_ipc;
77pub mod api;
78pub mod dispatch_deque;
79pub mod message_transport;
80pub mod mmf_dispatcher;
81pub mod shared_deque;
82pub mod shared_deque_fcl;
83pub mod shared_deque_khl;
84pub mod shared_deque_khpd;
85pub mod shared_deque_loh;
86pub mod shared_deque_urd;
87pub mod shared_fence_clock;
88pub mod shared_graph;
89pub mod shared_handle_table;
90pub mod shared_hash_map;
91pub mod shared_histogram;
92pub mod shared_hyper_log_log;
93pub mod shared_leader_election;
94pub mod shared_linked_list;
95pub mod shared_lru_cache;
96pub mod shared_nan_tagged_value;
97pub mod shared_nan_value;
98pub mod shared_once_cell;
99pub mod shared_rate_limiter;
100pub mod shared_region;
101pub mod shared_reservoir_sampler;
102pub mod cpu_affinity;
103pub mod task_pool;
104pub mod waker_ring;
105pub mod ring_executor;
106pub mod reactor;
107pub mod net_bridge;
108pub mod shared_ring;
109pub mod spsc_ring;
110pub mod frame_ring;
111pub mod frame_region;
112pub mod mpsc_ring;
113pub mod mpmc_ring;
114pub mod adaptive_ring;
115pub mod ring_contract;
116pub mod capacity_adaptive_ring;
117pub mod policy_gate;
118pub mod unified_policy;
119pub mod phase_estimator;
120pub mod capacity_broadcast_ring;
121pub mod capacity_pubsub_ring;
122pub mod async_ring;
123pub mod blocking_spsc_ring;
124pub mod blocking_mpsc_ring;
125pub mod blocking_mpmc_ring;
126pub mod blocking_rw_lock;
127pub mod blocking_semaphore;
128#[cfg(feature = "tcp-bridge")]
129pub mod blocking_tcp_bridge;
130pub mod bbr;
131pub mod cache_ops;
132pub mod control_frame;
133pub mod control_table;
134pub mod fec;
135pub mod rlc_fec;
136pub mod rlc_control;
137#[cfg(feature = "tls")]
138pub mod rlc_crypto;
139pub mod dgram;
140/// Sens-O-Matic transport carrying the sliding-window RLC erasure code (the
141/// adaptive, optionally-TLS code; the block Reed-Solomon code lives in
142/// [`udp_bridge`]). The RLC coding internals are in [`rlc_fec`] / [`rlc_control`].
143pub mod sens_rlc;
144/// Unified Sens-O-Matic endpoint: one transport carrying both erasure codes,
145/// switching RLC <-> RS mid-stream on the loss the receiver feeds back (the
146/// loss-driven auto-switch, with operator override).
147pub mod sens_unified;
148pub mod fusion;
149pub mod interleave;
150pub mod link_sensor;
151pub mod compressed_udp;
152pub mod reliable_udp;
153pub mod salvage;
154pub mod schema_codec;
155pub mod sharded_udp;
156pub mod path_sensor;
157pub mod path_model_sensor;
158pub mod net_events;
159pub mod stream_mux;
160pub mod wbest_sensor;
161pub mod trace_sensor;
162pub mod forecast_sensor;
163pub mod periodicity_sensor;
164pub mod rtt_shape_sensor;
165pub mod burst_model_sensor;
166pub mod loss_class_sensor;
167pub mod temporal_sensor;
168pub mod tower;
169pub mod udp_bridge;
170pub mod cross_process_waker;
171pub mod shared_condvar;
172pub mod locale_adaptive_ring;
173mod mmf_attach;
174pub mod mmf_warm;
175pub mod monitor_wait;
176pub mod net_tune;
177pub mod ordering;
178pub mod peer_directory;
179pub mod protocol_pubsub;
180pub mod qos_policy;
181pub mod replay_positions;
182pub mod shm_file;
183pub mod virtual_endpoint;
184#[cfg(target_os = "linux")]
185pub mod hugepages;
186#[cfg(windows)]
187pub mod large_pages;
188#[cfg(any(target_os = "freebsd", target_os = "macos"))]
189pub mod super_pages;
190#[cfg(any(target_os = "linux", windows))]
191pub mod locale_vsock;
192#[cfg(any(unix, windows))]
193pub mod protocol_direct_file;
194#[cfg(any(unix, windows))]
195pub mod fd_handoff;
196#[cfg(any(target_os = "linux", windows, target_os = "freebsd", target_os = "macos"))]
197pub mod kernel_async_ring;
198#[cfg(all(
199    any(target_os = "linux", windows, target_os = "freebsd", target_os = "macos"),
200    feature = "wire-locale"
201))]
202pub mod locale_wire;
203#[cfg(feature = "quic-bridge")]
204pub mod quic_bridge;
205#[cfg(feature = "quic-bridge")]
206pub mod sens_quic;
207#[cfg(feature = "tcp-bridge")]
208pub mod tcp_bridge;
209#[cfg(feature = "tcp-tls-bridge")]
210pub mod tcp_tls_bridge;
211pub mod shared_rw_lock;
212pub mod shared_semaphore;
213pub mod shared_string_arena;
214pub mod shared_time_point;
215pub mod shared_topology_map;
216pub mod shared_treiber_stack;
217pub mod shared_umbra_pointer;
218pub mod shared_universal;
219pub mod shared_vec;
220pub mod shared_versioned_chain;
221pub mod tagged_offset_ptr;
222
223pub use epoch_barrier::{BarrierError, EpochBarrier, DEFAULT_BARRIER_GRACE_EPOCHS};
224pub use event_state_log::{EventLogError, EventStateLog};
225pub use failover::{FailoverWatchdog, ReclaimReport, DEFAULT_GRACE_EPOCHS};
226pub use k_tower_cascade::{
227    CascadeError, CascadeResolver2, CascadeResolverN, KTowerCascade,
228    NIL_INDEX as CASCADE_NIL_INDEX,
229};
230pub use lazy_config::{LazyConfig, LazyConfigError};
231pub use owner_lease::{
232    LeaseError, LeaseHeader, LeasePayload, OwnerLease,
233    LEASE_FILE_SIZE, LEASE_MAGIC, NO_OWNER,
234    PAYLOAD_BYTES as LEASE_PAYLOAD_BYTES,
235};
236pub use heartbeat::{
237    HeartbeatError, HeartbeatHeader, HeartbeatSlot, HeartbeatSnapshot,
238    HeartbeatTable, EMPTY_PID, HEARTBEAT_MAGIC, IN_FLIGHT_SLOTS,
239};
240pub use pass_registry::{
241    execute as execute_pass, is_registered, register as register_handler,
242    registered_count, unregister as unregister_handler,
243    Pass, PassError, PassHandler, PassResult,
244};
245pub use priority_fanout::{FanoutError, PriorityFanout, MAX_PRIORITIES};
246pub use progress_task::{ProgressReporter, ProgressTask, ProgressTaskError};
247pub use scheduler::{
248    BackgroundScheduler, ResultCollector, SchedError, SubmittedResult,
249    Submitter,
250};
251pub use shared_async_pointer::{SharedAsyncError, SharedAsyncPointer};
252pub use shared_atomic::{
253    SharedAtomicBool, SharedAtomicError, SharedAtomicU32, SharedAtomicU64,
254};
255pub use shared_bit_vec::{
256    bit_vec_file_size, BitVecError, BitVecHeader, SharedBitVec,
257    BITS_PER_WORD, BITVEC_MAGIC,
258};
259pub use shared_blocked_bloom_filter::{
260    BlockedBloomError, SharedBlockedBloomFilter,
261};
262pub use shared_bloom_filter::{
263    BloomError, BloomHeader, SharedBloomFilter, BLOOM_MAGIC,
264};
265pub use shared_broadcast_ring::{
266    broadcast_file_size, BroadcastError, BroadcastHeader, BroadcastSlot,
267    SharedBroadcastRing, BROADCAST_MAGIC, BROADCAST_PAYLOAD_BYTES,
268    MAX_CONSUMERS,
269};
270pub use shared_cell::{
271    CellHeader, SharedCell, SharedCellError, CELL_FILE_SIZE, CELL_MAGIC,
272    PAYLOAD_BYTES as CELL_PAYLOAD_BYTES,
273};
274pub use shared_count_min_sketch::{
275    cms_file_size, CMSError, CMSHeader, SharedCountMinSketch, CMS_MAGIC,
276};
277pub use dispatch_deque::{
278    DequeDispatcher, DequeVariant, DispatchError, DispatcherBuilder, WorkloadShape,
279};
280pub use message_transport::{MessageTransport, PassSlot, TransportError};
281pub use mmf_dispatcher::{MmfDispatcher, MmfFamily, MmfWorkloadShape};
282pub use api::{ApiError, AutoIpc, Channel, KvMap, WorkStealQueue};
283pub use adaptive_ipc::{
284    AdaptiveIpc, AdaptiveIpcSidecar, PinnedIpc, ProfileSnapshot,
285};
286pub use shared_deque::{
287    deque_file_size, slot_bytes_for, DequeError, DequeHeader, SharedDeque, DEQUE_MAGIC,
288};
289pub use shared_deque_fcl::SharedDequeFcl;
290pub use shared_deque_khl::{
291    khl_file_size, KhlHeader, KhlSlot, PublishRadius as KhlPublishRadius,
292    PushError as KhlPushError, SharedDequeKhl, Steal as KhlSteal,
293    StealResult as KhlStealResult, KHL_ITEMS_PER_SLOT, KHL_MAGIC, KHL_SLOT_SIZE,
294};
295pub use shared_deque_khpd::{
296    khpd_file_size, FatLineItem, KhpdHeader, LineItem, PublicationLine,
297    PushError as KhpdPushError, SharedDequeKhpd, Steal as KhpdSteal,
298    StealResult as KhpdStealResult, KHPD_ITEM_BYTES, KHPD_LINE_SIZE, KHPD_MAGIC,
299    LINE_ITEMS,
300};
301pub use shared_deque_loh::{
302    loh_file_size, LcrqJobSlot, LohHeader, PushError as LohPushError,
303    SharedDequeLoh, Steal as LohSteal, StealResult as LohStealResult,
304    DEFAULT_LIFO_CAP as LOH_DEFAULT_LIFO_CAP, LOH_MAGIC, LOH_SLOT_SIZE,
305};
306pub use shared_deque_urd::{
307    urd_file_size, Drain as UrdDrain, DrainResult as UrdDrainResult, Mailbox,
308    PublishError as UrdPublishError, PublishStrategy as UrdPublishStrategy,
309    SharedDequeUrd, UrdHeader, WaitStrategy, MAILBOX_ITEMS, URD_MAGIC, URD_MAILBOX_SIZE,
310};
311pub use shared_fence_clock::{
312    fence_clock_file_size, FenceClockError, Hlc, HlcHeader, HlcSlot,
313    HlcSlotSnapshot, SharedFenceClock, FENCE_CLOCK_MAGIC,
314};
315pub use shared_graph::{
316    EdgeIndex, GraphEdge, GraphError, GraphNode, NodeIndex, SharedGraph,
317    NIL_INDEX as GRAPH_NIL_INDEX,
318};
319pub use shared_handle_table::{
320    handle_table_file_size, slot_offset, Handle, HandleHeader, HandleTableError,
321    SharedHandleTable, SharedSlot, HANDLE_TABLE_MAGIC, NIL_SLOT, SLOT_PAYLOAD_BYTES,
322};
323pub use shared_hash_map::{
324    fnv1a_64, map_file_size, InsertOutcome, MapError, MapHeader, MapSlot,
325    SharedHashMap, MAP_MAGIC, MAP_PAYLOAD_BYTES,
326    SLOT_EMPTY, SLOT_OCCUPIED, SLOT_TOMBSTONE,
327};
328pub use shared_histogram::{
329    histogram_file_size, HistogramError, HistogramHeader, SharedHistogram,
330    HISTOGRAM_MAGIC,
331};
332pub use shared_hyper_log_log::{
333    hll_file_size, HLLError, HLLHeader, SharedHyperLogLog,
334    HLL_MAGIC, MAX_PRECISION as HLL_MAX_PRECISION,
335    MIN_PRECISION as HLL_MIN_PRECISION,
336};
337pub use shared_leader_election::{
338    LeaderError, LeaderHeader, SharedLeaderElection,
339    DEFAULT_GRACE_EPOCHS as LEADER_DEFAULT_GRACE_EPOCHS,
340    LEADER_FILE_SIZE, LEADER_MAGIC, NO_LEADER,
341};
342pub use shared_linked_list::{
343    LinkedListError, Node as LinkedListNode, NodeHandle, SharedLinkedList,
344    HEAD_INDEX as LINKED_LIST_HEAD_INDEX, NIL_INDEX as LINKED_LIST_NIL_INDEX,
345};
346pub use shared_lru_cache::{LRUError, SharedLRUCache};
347pub use shared_nan_tagged_value::{NaNTaggedType, SharedNaNTaggedValue};
348pub use shared_nan_value::{
349    NaNValueType, SharedNaNValue,
350    BOXED_MASK, BOXED_PREFIX, CANONICAL_QNAN, PAYLOAD_MASK,
351    TAG_BOOL, TAG_I32, TAG_MASK, TAG_NIL, TAG_OFFSET_PTR, TAG_SHIFT,
352    TAG_TAGGED_OFFSET_PTR, TAG_U32,
353};
354pub use shared_once_cell::{
355    OnceHeader, SharedOnceCell, SharedOnceError, ONCE_FILE_SIZE, ONCE_MAGIC,
356    ONCE_PAYLOAD_BYTES, STATE_EMPTY, STATE_INITIALIZED, STATE_INITIALIZING,
357};
358pub use shared_rate_limiter::{
359    RateLimiterError, RateLimiterHeader, SharedRateLimiter, RATE_LIMITER_MAGIC,
360};
361pub use shared_region::{
362    region_file_size, OffsetPtr, RegionError, RegionHeader, SharedRegion,
363    NIL_INDEX, REGION_MAGIC,
364};
365pub use shared_reservoir_sampler::{
366    reservoir_file_size, ReservoirError, ReservoirHeader, ReservoirSlot,
367    SharedReservoirSampler, RESERVOIR_MAGIC, RESERVOIR_SLOT_PAYLOAD,
368};
369pub use shared_ring::{
370    ring_file_size, Consumer as SpscConsumer, LazySharedRing, Producer as SpscProducer,
371    RingError, RingHeader, SharedRing, SharedRingSpsc, Slot, PAYLOAD_BYTES,
372    RING_MAGIC, SLOT_SIZE,
373};
374pub use frame_ring::{
375    frame_ring_file_size, FrameClass, FrameRing, LayoutHint,
376    DESC_HEADER_BYTES, FRAME_MAGIC, MIN_SLOT_SIZE,
377};
378pub use frame_region::{
379    frame_region_file_size, FrameRegion, FRAME_REGION_MAGIC, MIN_BLOCK_SIZE,
380};
381pub use mpsc_ring::{
382    MpscConsumer, MpscFifoConsumer, MpscFifoProducer, MpscProducer,
383    SharedRingMpsc, SharedRingMpscFifo,
384};
385pub use mpmc_ring::{MpmcConsumer, MpmcProducer, SharedRingMpmc};
386pub use adaptive_ring::{
387    AdaptiveError, AdaptiveRing, AdaptiveRingSidecar, DefaultOrderingPolicy,
388    DefaultRingShapePolicy, OrderingPolicy, OrderingPolicyObservation,
389    PinnedRing, PolicyObservation, QosRingShapePolicy, RingShape,
390    RingShapePolicy, ADAPTIVE_SPSC_PAYLOAD_BYTES,
391    ADAPTIVE_VYUKOV_PAYLOAD_BYTES, DRAINER_GRACE_EPOCHS,
392};
393pub use cache_ops::{cldemote, has_cldemote, prefetchw, sfence};
394pub use mmf_warm::{warm_mmap, warm_region};
395pub use monitor_wait::{
396    monitor_wait_budget_cycles, monitor_wait_kind, monitor_wait_u32,
397    monitor_wait_u32_with, monitor_wait_u64, monitor_wait_u64_with,
398    MonitorWaitKind, DEFAULT_MONITOR_BUDGET_CYCLES,
399};
400pub use ordering::{
401    default_stamp_kind, has_invariant_tsc, ordering_region_size,
402    OrderingHeader, OrderingMode, OrderingRegion, StampKind,
403    MONOTONIC_FRESHNESS_GUARD_NANOS, ORDERING_MAGIC, STAMPED_PAYLOAD_BYTES,
404    STAMP_BYTES, TSC_FRESHNESS_GUARD_CYCLES,
405};
406pub use qos_policy::{
407    Durability, History, Ordering as QosOrdering, QosPolicy, QosSnapshot,
408    Reliability,
409};
410pub use capacity_adaptive_ring::{
411    BackingTarget, CapacityAdaptiveRing, CapacityAdaptiveRingSidecar,
412    CapacityMorphError, CapacityPolicy, CapacityPolicyObservation,
413    DefaultCapacityPolicy, PinnedCapacity, RingConfig,
414};
415pub use policy_gate::{min_samples_for_arity, ConfidenceGate, GateConfig};
416pub use unified_policy::{
417    UnifiedObservation, UnifiedPolicy, UnifiedSidecar, UnifiedWeights,
418};
419pub use phase_estimator::{PhaseConfig, PhaseEstimator};
420pub use capacity_broadcast_ring::{
421    BroadcastCapacityMorphError, CapacityBroadcastRing, PinnedBroadcastCapacity,
422};
423pub use capacity_pubsub_ring::{
424    CapacityPubSubRing, CapacityPubSubSubscriber, PubSubCapacityMorphError,
425};
426pub use blocking_spsc_ring::{BlockingError, BlockingSpscRing, PhaseRecvStats};
427pub use blocking_mpsc_ring::{
428    BlockingMpscConsumer, BlockingMpscProducer, BlockingMpscRing,
429};
430pub use blocking_mpmc_ring::{
431    BlockingMpmcConsumer, BlockingMpmcProducer, BlockingMpmcRing,
432};
433pub use cross_process_waker::{
434    CrossProcessWaker, WakerError, WakerToken, MAX_WAITERS_DEFAULT, WAKER_MAGIC,
435    waker_region_size,
436};
437pub use shared_condvar::{CondvarError, SharedCondvar};
438pub use async_ring::{AsyncRecv, AsyncSend, AsyncSpscRing};
439pub use blocking_semaphore::{
440    BlockingPermit, BlockingSemaphore, BlockingSemaphoreError,
441};
442pub use blocking_rw_lock::{
443    BlockingReadGuard, BlockingRWLock, BlockingRWLockError, BlockingWriteGuard,
444};
445pub use locale_adaptive_ring::{
446    DefaultLocalePolicy, Locale, LocaleAdaptiveRing, LocaleAdaptiveRingSidecar,
447    LocalePolicy, LocalePolicyObservation, PinnedLocale,
448};
449pub use shared_rw_lock::{
450    ReadGuard, RWLockError, RWLockHeader, SharedRWLock, WriteGuard, RWLOCK_MAGIC,
451};
452pub use shared_semaphore::{Permit, SemaphoreError, SharedSemaphore};
453pub use shared_btree_map::{BTreeError, SharedBTreeMap};
454pub use shared_string_arena::{
455    arena_file_size, ArenaError, ArenaHeader, SharedStringArena, StringRef,
456    ARENA_MAGIC,
457};
458pub use shared_time_point::{
459    tile_file_size, SharedTimePointTile, TileError, TileHeader, VersionedSlot,
460    SLOT_PAYLOAD, TILE_CAP, TIME_POINT_MAGIC,
461};
462pub use shared_topology_map::{
463    topology_file_size, SharedTopologyMap, TopologyError, TopologyHeader,
464    TopologyKind, TopologyStats, DEFAULT_FAN_IN_THRESHOLD,
465    DEFAULT_FAN_OUT_THRESHOLD, TOPOLOGY_MAGIC,
466};
467pub use shared_treiber_stack::{
468    stack_file_size, SharedTreiberStack, StackError, StackHeader,
469    STACK_MAGIC, STACK_NIL,
470};
471pub use shared_umbra_pointer::SharedUmbraPointer;
472pub use shared_universal::{
473    SharedUniversal, Strategy as UniversalStrategy, UniversalError,
474    UniversalHeader, UNIVERSAL_MAGIC,
475};
476pub use shared_vec::{
477    vec_file_size, SharedVec, VecError, VecHeader, VecSlot,
478    VEC_MAGIC, VEC_PAYLOAD_BYTES,
479};
480pub use shared_versioned_chain::{
481    versioned_chain_file_size, ChainError, ChainHeader, SharedVersionedChain,
482    VersionNode, NIL_NODE, NODE_PAYLOAD_BYTES, VERSIONED_CHAIN_MAGIC,
483};
484pub use tagged_offset_ptr::{TaggedOffsetPtr, TaggedPtrError};
subetha_cxc/lib.rs

subetha_cxc/
lib.rs
