Engine: core/
Reference · the engine tier, crate by crate
Reference data structures and transports built directly on the pulse-canon atom: shared-memory IPC primitives, backoff strategies, the transport trait family, the reference UDP transport, and integrity checking. See also core/README.md.
| Crate | Purpose |
|---|---|
core-backoff | Backoff — a three-phase spin-wait state machine for OS-visible stalls (the UDP sender uses it while waiting for the receiver’s cursor): a bare-metal hot spin (steps 0–1000, ~ns latency), then an OS yield (1001–5000, ~µs latency, near-zero CPU), then a sleep (5001+, 1µs by default, ~0% CPU). reset() snaps back to phase 1 the instant progress is observed. Bounded SeqLock retries stay bare spins and hardware monitor waits use hft-functions’ WaitStrategy; the crate doc says which to pick. |
core-region | PulseRegion — a single-slot POSIX SHM mmap region holding one Pulse, protected by a SeqLock embedded in the pulse’s seq_lock field: writers increment to odd then even, readers retry on odd or on pre/post disagreement. create creates the region or attaches to the one under the name, as the ring’s does, never resizing or clearing it, and on Linux its page is reserved when the object is sized. The crate also holds shm, the one shared-memory mechanism: name validation, exclusive creation abandoned on a later failure, sizing with the Linux page reservation, the open-then-map step at which a header is read through the descriptor before any page is touched, the mapping that unmaps itself when dropped, and the unlink that removes a name only while it still names the caller’s object. The ring, the store and the NUMA backings map through it and keep their own headers, geometry and errors (ADR-0013). |
core-ring | PulseRing — the multi-slot SeqLock-protected SHM ring buffer, with a documented byte layout (write cursor, total writes, read cursor, then the ring’s own description: magic, header version, capacity and slot size, then N × 128-byte slots); open refuses a header that disagrees with the caller, and open_existing takes the geometry from the header. A publish takes the handle’s &mut, so a handle has one writer, and always succeeds, overwriting the oldest slot; a reader that lands on a slot mid-write retries within a bounded budget, and an odd counter left by a crashed writer is re-based by the next publish into that slot. read_position is the read for a poller that walks the write positions in order: each Pulse once, or the position counted lost with the next one to read, never a later lap under an earlier position. create creates a ring or attaches to the one under the name, never resizing or clearing a live ring, and is_creator says which happened, which the hub runtime uses to make the creating hub the ring’s one writer; on Linux a new object’s pages are reserved when it is sized, so a /dev/shm without room is NoSpace at creation rather than SIGBUS later. |
core-store | EnvelopeStore — a SHM circular buffer of serialized PulseEnvelopes, referenced from a Pulse via envelope_ref. Each slot is a SeqLock word, a 16-byte ID and a length prefix ahead of up to 64 KiB of the envelope’s canonical bytes (layout version 2, ADR-0011); a writer publishes a slot only after its body is written and routes around a held slot to a fresh cursor, the header carries a magic, a version and a busy-claim counter that open checks, and readers verify every body they return, fetch by ID, or stream new entries via read_since. |
core-transport | The public PulseTransport trait family (PulseSender/PulseReceiver) that concrete transport backends implement. Deliberately one-way (not bidirectional) to match per-thread halves, excludes measurement metadata from the hot path, avoids allocation in recv_into (writes into a caller-owned buffer), and returns concrete — not boxed — errors via TransportError. |
pms-crc32c | CRC32C integrity-trailer utilities (compute_pulse_crc/verify_pulse_crc) over the Pulse data area (bytes 8..124 of the 128-byte slot) — Module M10 of the Pulse Mesh Standard. |
pulse-wire-udp | The reference UDP transport: one datagram is one Pulse plus an envelope of at most 1,315 bytes, framed with magic, version, sequence, timestamp and a CRC32C trailer, never fragmented. Three mechanisms are off by default and switched on per side: backpressure (an acknowledged cursor and a bounded in-flight window), NACK retransmission from a send cache, and per-window parity. |
mesh-stage-registry | Tier 1 since the split (it depends on nothing and every ring hub uses it). #![no_std]. Provides the register_stages! macro that every ring’s *-hub crate calls once to enumerate its functions and stages. It emits RING_MANIFEST, a constant listing the hub’s declared function and stage modules, and imports every listed path, so a hub that names a module that does not exist does not compile; each hub’s tests assert that manifest against the layers the hub re-exports. |
Where to plug in
Downstream code should generally depend on core-transport (the trait) and a concrete backend — pulse-wire-udp today, with AF_XDP/DPDK/TLS-443 backends as separate crates elsewhere in the workspace (the profiles repository’s plugins/hft-xdp, enterprise_ring’s TLS stage). Reach into core-ring/core-store/core-region directly only if you’re implementing a new transport or ring primitive yourself, not as a general-purpose API.