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;
173pub mod mmf_warm;
174pub mod monitor_wait;
175pub mod net_tune;
176pub mod ordering;
177pub mod peer_directory;
178pub mod protocol_pubsub;
179pub mod qos_policy;
180pub mod replay_positions;
181pub mod shm_file;
182pub mod virtual_endpoint;
183#[cfg(target_os = "linux")]
184pub mod hugepages;
185#[cfg(windows)]
186pub mod large_pages;
187#[cfg(any(target_os = "freebsd", target_os = "macos"))]
188pub mod super_pages;
189#[cfg(any(target_os = "linux", windows))]
190pub mod locale_vsock;
191#[cfg(any(unix, windows))]
192pub mod protocol_direct_file;
193#[cfg(any(unix, windows))]
194pub mod fd_handoff;
195#[cfg(any(target_os = "linux", windows, target_os = "freebsd", target_os = "macos"))]
196pub mod kernel_async_ring;
197#[cfg(all(
198    any(target_os = "linux", windows, target_os = "freebsd", target_os = "macos"),
199    feature = "wire-locale"
200))]
201pub mod locale_wire;
202#[cfg(feature = "quic-bridge")]
203pub mod quic_bridge;
204#[cfg(feature = "quic-bridge")]
205pub mod sens_quic;
206#[cfg(feature = "tcp-bridge")]
207pub mod tcp_bridge;
208#[cfg(feature = "tcp-tls-bridge")]
209pub mod tcp_tls_bridge;
210pub mod shared_rw_lock;
211pub mod shared_semaphore;
212pub mod shared_string_arena;
213pub mod shared_time_point;
214pub mod shared_topology_map;
215pub mod shared_treiber_stack;
216pub mod shared_umbra_pointer;
217pub mod shared_universal;
218pub mod shared_vec;
219pub mod shared_versioned_chain;
220pub mod tagged_offset_ptr;
221
222pub use epoch_barrier::{BarrierError, EpochBarrier, DEFAULT_BARRIER_GRACE_EPOCHS};
223pub use event_state_log::{EventLogError, EventStateLog};
224pub use failover::{FailoverWatchdog, ReclaimReport, DEFAULT_GRACE_EPOCHS};
225pub use k_tower_cascade::{
226    CascadeError, CascadeResolver2, CascadeResolverN, KTowerCascade,
227    NIL_INDEX as CASCADE_NIL_INDEX,
228};
229pub use lazy_config::{LazyConfig, LazyConfigError};
230pub use owner_lease::{
231    LeaseError, LeaseHeader, LeasePayload, OwnerLease,
232    LEASE_FILE_SIZE, LEASE_MAGIC, NO_OWNER,
233    PAYLOAD_BYTES as LEASE_PAYLOAD_BYTES,
234};
235pub use heartbeat::{
236    HeartbeatError, HeartbeatHeader, HeartbeatSlot, HeartbeatSnapshot,
237    HeartbeatTable, EMPTY_PID, HEARTBEAT_MAGIC, IN_FLIGHT_SLOTS,
238};
239pub use pass_registry::{
240    execute as execute_pass, is_registered, register as register_handler,
241    registered_count, unregister as unregister_handler,
242    Pass, PassError, PassHandler, PassResult,
243};
244pub use priority_fanout::{FanoutError, PriorityFanout, MAX_PRIORITIES};
245pub use progress_task::{ProgressReporter, ProgressTask, ProgressTaskError};
246pub use scheduler::{
247    BackgroundScheduler, ResultCollector, SchedError, SubmittedResult,
248    Submitter,
249};
250pub use shared_async_pointer::{SharedAsyncError, SharedAsyncPointer};
251pub use shared_atomic::{
252    SharedAtomicBool, SharedAtomicError, SharedAtomicU32, SharedAtomicU64,
253};
254pub use shared_bit_vec::{
255    bit_vec_file_size, BitVecError, BitVecHeader, SharedBitVec,
256    BITS_PER_WORD, BITVEC_MAGIC,
257};
258pub use shared_blocked_bloom_filter::{
259    BlockedBloomError, SharedBlockedBloomFilter,
260};
261pub use shared_bloom_filter::{
262    BloomError, BloomHeader, SharedBloomFilter, BLOOM_MAGIC,
263};
264pub use shared_broadcast_ring::{
265    broadcast_file_size, BroadcastError, BroadcastHeader, BroadcastSlot,
266    SharedBroadcastRing, BROADCAST_MAGIC, BROADCAST_PAYLOAD_BYTES,
267    MAX_CONSUMERS,
268};
269pub use shared_cell::{
270    CellHeader, SharedCell, SharedCellError, CELL_FILE_SIZE, CELL_MAGIC,
271    PAYLOAD_BYTES as CELL_PAYLOAD_BYTES,
272};
273pub use shared_count_min_sketch::{
274    cms_file_size, CMSError, CMSHeader, SharedCountMinSketch, CMS_MAGIC,
275};
276pub use dispatch_deque::{
277    DequeDispatcher, DequeVariant, DispatchError, DispatcherBuilder, WorkloadShape,
278};
279pub use message_transport::{MessageTransport, PassSlot, TransportError};
280pub use mmf_dispatcher::{MmfDispatcher, MmfFamily, MmfWorkloadShape};
281pub use api::{ApiError, AutoIpc, Channel, KvMap, WorkStealQueue};
282pub use adaptive_ipc::{
283    AdaptiveIpc, AdaptiveIpcSidecar, PinnedIpc, ProfileSnapshot,
284};
285pub use shared_deque::{
286    deque_file_size, slot_bytes_for, DequeError, DequeHeader, SharedDeque, DEQUE_MAGIC,
287};
288pub use shared_deque_fcl::SharedDequeFcl;
289pub use shared_deque_khl::{
290    khl_file_size, KhlHeader, KhlSlot, PublishRadius as KhlPublishRadius,
291    PushError as KhlPushError, SharedDequeKhl, Steal as KhlSteal,
292    StealResult as KhlStealResult, KHL_ITEMS_PER_SLOT, KHL_MAGIC, KHL_SLOT_SIZE,
293};
294pub use shared_deque_khpd::{
295    khpd_file_size, FatLineItem, KhpdHeader, LineItem, PublicationLine,
296    PushError as KhpdPushError, SharedDequeKhpd, Steal as KhpdSteal,
297    StealResult as KhpdStealResult, KHPD_ITEM_BYTES, KHPD_LINE_SIZE, KHPD_MAGIC,
298    LINE_ITEMS,
299};
300pub use shared_deque_loh::{
301    loh_file_size, LcrqJobSlot, LohHeader, PushError as LohPushError,
302    SharedDequeLoh, Steal as LohSteal, StealResult as LohStealResult,
303    DEFAULT_LIFO_CAP as LOH_DEFAULT_LIFO_CAP, LOH_MAGIC, LOH_SLOT_SIZE,
304};
305pub use shared_deque_urd::{
306    urd_file_size, Drain as UrdDrain, DrainResult as UrdDrainResult, Mailbox,
307    PublishError as UrdPublishError, PublishStrategy as UrdPublishStrategy,
308    SharedDequeUrd, UrdHeader, WaitStrategy, MAILBOX_ITEMS, URD_MAGIC, URD_MAILBOX_SIZE,
309};
310pub use shared_fence_clock::{
311    fence_clock_file_size, FenceClockError, Hlc, HlcHeader, HlcSlot,
312    HlcSlotSnapshot, SharedFenceClock, FENCE_CLOCK_MAGIC,
313};
314pub use shared_graph::{
315    EdgeIndex, GraphEdge, GraphError, GraphNode, NodeIndex, SharedGraph,
316    NIL_INDEX as GRAPH_NIL_INDEX,
317};
318pub use shared_handle_table::{
319    handle_table_file_size, slot_offset, Handle, HandleHeader, HandleTableError,
320    SharedHandleTable, SharedSlot, HANDLE_TABLE_MAGIC, NIL_SLOT, SLOT_PAYLOAD_BYTES,
321};
322pub use shared_hash_map::{
323    fnv1a_64, map_file_size, InsertOutcome, MapError, MapHeader, MapSlot,
324    SharedHashMap, MAP_MAGIC, MAP_PAYLOAD_BYTES,
325    SLOT_EMPTY, SLOT_OCCUPIED, SLOT_TOMBSTONE,
326};
327pub use shared_histogram::{
328    histogram_file_size, HistogramError, HistogramHeader, SharedHistogram,
329    HISTOGRAM_MAGIC,
330};
331pub use shared_hyper_log_log::{
332    hll_file_size, HLLError, HLLHeader, SharedHyperLogLog,
333    HLL_MAGIC, MAX_PRECISION as HLL_MAX_PRECISION,
334    MIN_PRECISION as HLL_MIN_PRECISION,
335};
336pub use shared_leader_election::{
337    LeaderError, LeaderHeader, SharedLeaderElection,
338    DEFAULT_GRACE_EPOCHS as LEADER_DEFAULT_GRACE_EPOCHS,
339    LEADER_FILE_SIZE, LEADER_MAGIC, NO_LEADER,
340};
341pub use shared_linked_list::{
342    LinkedListError, Node as LinkedListNode, NodeHandle, SharedLinkedList,
343    HEAD_INDEX as LINKED_LIST_HEAD_INDEX, NIL_INDEX as LINKED_LIST_NIL_INDEX,
344};
345pub use shared_lru_cache::{LRUError, SharedLRUCache};
346pub use shared_nan_tagged_value::{NaNTaggedType, SharedNaNTaggedValue};
347pub use shared_nan_value::{
348    NaNValueType, SharedNaNValue,
349    BOXED_MASK, BOXED_PREFIX, CANONICAL_QNAN, PAYLOAD_MASK,
350    TAG_BOOL, TAG_I32, TAG_MASK, TAG_NIL, TAG_OFFSET_PTR, TAG_SHIFT,
351    TAG_TAGGED_OFFSET_PTR, TAG_U32,
352};
353pub use shared_once_cell::{
354    OnceHeader, SharedOnceCell, SharedOnceError, ONCE_FILE_SIZE, ONCE_MAGIC,
355    ONCE_PAYLOAD_BYTES, STATE_EMPTY, STATE_INITIALIZED, STATE_INITIALIZING,
356};
357pub use shared_rate_limiter::{
358    RateLimiterError, RateLimiterHeader, SharedRateLimiter, RATE_LIMITER_MAGIC,
359};
360pub use shared_region::{
361    region_file_size, OffsetPtr, RegionError, RegionHeader, SharedRegion,
362    NIL_INDEX, REGION_MAGIC,
363};
364pub use shared_reservoir_sampler::{
365    reservoir_file_size, ReservoirError, ReservoirHeader, ReservoirSlot,
366    SharedReservoirSampler, RESERVOIR_MAGIC, RESERVOIR_SLOT_PAYLOAD,
367};
368pub use shared_ring::{
369    ring_file_size, Consumer as SpscConsumer, LazySharedRing, Producer as SpscProducer,
370    RingError, RingHeader, SharedRing, SharedRingSpsc, Slot, PAYLOAD_BYTES,
371    RING_MAGIC, SLOT_SIZE,
372};
373pub use frame_ring::{
374    frame_ring_file_size, FrameClass, FrameRing, LayoutHint,
375    DESC_HEADER_BYTES, FRAME_MAGIC, MIN_SLOT_SIZE,
376};
377pub use frame_region::{
378    frame_region_file_size, FrameRegion, FRAME_REGION_MAGIC, MIN_BLOCK_SIZE,
379};
380pub use mpsc_ring::{
381    MpscConsumer, MpscFifoConsumer, MpscFifoProducer, MpscProducer,
382    SharedRingMpsc, SharedRingMpscFifo,
383};
384pub use mpmc_ring::{MpmcConsumer, MpmcProducer, SharedRingMpmc};
385pub use adaptive_ring::{
386    AdaptiveError, AdaptiveRing, AdaptiveRingSidecar, DefaultOrderingPolicy,
387    DefaultRingShapePolicy, OrderingPolicy, OrderingPolicyObservation,
388    PinnedRing, PolicyObservation, QosRingShapePolicy, RingShape,
389    RingShapePolicy, ADAPTIVE_SPSC_PAYLOAD_BYTES,
390    ADAPTIVE_VYUKOV_PAYLOAD_BYTES, DRAINER_GRACE_EPOCHS,
391};
392pub use cache_ops::{cldemote, has_cldemote, prefetchw, sfence};
393pub use mmf_warm::{warm_mmap, warm_region};
394pub use monitor_wait::{
395    monitor_wait_budget_cycles, monitor_wait_kind, monitor_wait_u32,
396    monitor_wait_u32_with, monitor_wait_u64, monitor_wait_u64_with,
397    MonitorWaitKind, DEFAULT_MONITOR_BUDGET_CYCLES,
398};
399pub use ordering::{
400    default_stamp_kind, has_invariant_tsc, ordering_region_size,
401    OrderingHeader, OrderingMode, OrderingRegion, StampKind,
402    MONOTONIC_FRESHNESS_GUARD_NANOS, ORDERING_MAGIC, STAMPED_PAYLOAD_BYTES,
403    STAMP_BYTES, TSC_FRESHNESS_GUARD_CYCLES,
404};
405pub use qos_policy::{
406    Durability, History, Ordering as QosOrdering, QosPolicy, QosSnapshot,
407    Reliability,
408};
409pub use capacity_adaptive_ring::{
410    BackingTarget, CapacityAdaptiveRing, CapacityAdaptiveRingSidecar,
411    CapacityMorphError, CapacityPolicy, CapacityPolicyObservation,
412    DefaultCapacityPolicy, PinnedCapacity, RingConfig,
413};
414pub use policy_gate::{min_samples_for_arity, ConfidenceGate, GateConfig};
415pub use unified_policy::{
416    UnifiedObservation, UnifiedPolicy, UnifiedSidecar, UnifiedWeights,
417};
418pub use phase_estimator::{PhaseConfig, PhaseEstimator};
419pub use capacity_broadcast_ring::{
420    BroadcastCapacityMorphError, CapacityBroadcastRing, PinnedBroadcastCapacity,
421};
422pub use capacity_pubsub_ring::{
423    CapacityPubSubRing, CapacityPubSubSubscriber, PubSubCapacityMorphError,
424};
425pub use blocking_spsc_ring::{BlockingError, BlockingSpscRing, PhaseRecvStats};
426pub use blocking_mpsc_ring::{
427    BlockingMpscConsumer, BlockingMpscProducer, BlockingMpscRing,
428};
429pub use blocking_mpmc_ring::{
430    BlockingMpmcConsumer, BlockingMpmcProducer, BlockingMpmcRing,
431};
432pub use cross_process_waker::{
433    CrossProcessWaker, WakerError, WakerToken, MAX_WAITERS_DEFAULT, WAKER_MAGIC,
434    waker_region_size,
435};
436pub use shared_condvar::{CondvarError, SharedCondvar};
437pub use async_ring::{AsyncRecv, AsyncSend, AsyncSpscRing};
438pub use blocking_semaphore::{
439    BlockingPermit, BlockingSemaphore, BlockingSemaphoreError,
440};
441pub use blocking_rw_lock::{
442    BlockingReadGuard, BlockingRWLock, BlockingRWLockError, BlockingWriteGuard,
443};
444pub use locale_adaptive_ring::{
445    DefaultLocalePolicy, Locale, LocaleAdaptiveRing, LocaleAdaptiveRingSidecar,
446    LocalePolicy, LocalePolicyObservation, PinnedLocale,
447};
448pub use shared_rw_lock::{
449    ReadGuard, RWLockError, RWLockHeader, SharedRWLock, WriteGuard, RWLOCK_MAGIC,
450};
451pub use shared_semaphore::{Permit, SemaphoreError, SharedSemaphore};
452pub use shared_btree_map::{BTreeError, SharedBTreeMap};
453pub use shared_string_arena::{
454    arena_file_size, ArenaError, ArenaHeader, SharedStringArena, StringRef,
455    ARENA_MAGIC,
456};
457pub use shared_time_point::{
458    tile_file_size, SharedTimePointTile, TileError, TileHeader, VersionedSlot,
459    SLOT_PAYLOAD, TILE_CAP, TIME_POINT_MAGIC,
460};
461pub use shared_topology_map::{
462    topology_file_size, SharedTopologyMap, TopologyError, TopologyHeader,
463    TopologyKind, TopologyStats, DEFAULT_FAN_IN_THRESHOLD,
464    DEFAULT_FAN_OUT_THRESHOLD, TOPOLOGY_MAGIC,
465};
466pub use shared_treiber_stack::{
467    stack_file_size, SharedTreiberStack, StackError, StackHeader,
468    STACK_MAGIC, STACK_NIL,
469};
470pub use shared_umbra_pointer::SharedUmbraPointer;
471pub use shared_universal::{
472    SharedUniversal, Strategy as UniversalStrategy, UniversalError,
473    UniversalHeader, UNIVERSAL_MAGIC,
474};
475pub use shared_vec::{
476    vec_file_size, SharedVec, VecError, VecHeader, VecSlot,
477    VEC_MAGIC, VEC_PAYLOAD_BYTES,
478};
479pub use shared_versioned_chain::{
480    versioned_chain_file_size, ChainError, ChainHeader, SharedVersionedChain,
481    VersionNode, NIL_NODE, NODE_PAYLOAD_BYTES, VERSIONED_CHAIN_MAGIC,
482};
483pub use tagged_offset_ptr::{TaggedOffsetPtr, TaggedPtrError};
subetha_cxc/lib.rs

subetha_cxc/
lib.rs
