Module protocol_pubsub 

PubSubRing: one-producer many-subscriber broadcast primitive with per-subscriber positions.

Where a regular ring (SpscRingCore) has one consumer position (the tail), PubSubRing exposes the producer’s monotonic head as the absolute position and lets each subscriber walk positions independently. Subscriber positions are tracked externally via SubscriberPosition, so they can survive a subscriber restart.

Slot layout

Each slot carries a sequence: AtomicU64 + 56-byte payload. On a successful publish(payload), the producer:

1. Writes the payload into slot[head % capacity].
2. Releases the new sequence = head + 1.
3. Releases head + 1 into the header.

On read_at(position), a subscriber:

1. Reads the slot’s sequence with Acquire.
2. Validates sequence == position + 1 (matches expected slot). If sequence > position + 1, the slot has been overwritten (wraparound); subscriber returns PubSubReadError::Lost. If sequence < position + 1, the slot is not yet published; subscriber returns PubSubReadError::Pending.
3. On match: copies the payload to the out buffer.

KeepAll vs KeepLastN policy

The primitive itself is KeepLastN-shaped: producer never blocks on subscribers; wraparound happens at capacity. Callers that want KeepAll semantics check the minimum subscriber position before publishing and back off when the ring is about to wrap past it. Helpers for that pattern can layer on top.

Structs

PubSubRing

One-producer many-subscriber broadcast ring with per-subscriber positions.

PubSubSubscriber

Subscriber-side helper that holds a SubscriberPosition and pulls items from a PubSubRing in order.

Enums

PubSubReadError

Errors a subscriber read can return.

Constants

PUBSUB_PAYLOAD_BYTES

Payload bytes per slot. Matches the Vyukov-side payload size to keep the substrate’s per-slot byte layout consistent across primitives.

Functions

pubsub_ring_file_size