Module shared_vec

Expand description

SharedVec<T> - cross-process bounded indexable sequence.

Distinct from SharedRing (FIFO; drain semantics): SharedVec is RANDOM-ACCESS, accumulates monotonically up to capacity, and supports get(i) for any prior index.

§Layout

Single MMF file:

+---------------------------+
| VecHeader  (64B aligned)  |  magic, capacity, len, slot_size
+---------------------------+
| Slot[0]    (64B = cache)  |  version + payload[VEC_PAYLOAD_BYTES]
| Slot[1]                   |
| ...                       |
| Slot[capacity - 1]        |
+---------------------------+

Each slot is its own SeqLock cell (same shape as SharedCell); per-slot writes never false-share because each is its own cache line.

§Concurrency

push_back: atomic len.fetch_add(1) claims a slot index; if it exceeds capacity, rollback with fetch_sub(1) and return Full. On success, write the payload under the slot’s SeqLock (version bump odd → write → bump even).
get(i): load len (Acquire). If i >= len, return None. Otherwise SeqLock-read slot[i]: spin if version is odd (writer in progress), reread on version change.
pop_back: compare_exchange on len to decrement; if successful, read the now-popped slot’s payload at the old index. The slot bytes remain in place but are no longer addressable via len-bounded access.
set(i, v): bounds-check against len, then SeqLock-write.
clear: store len = 0 (Release). Previously-pushed slot payloads remain on disk but become unreachable through the bounded indexing.

§Capacity

Fixed at create time. The MMF is pre-allocated to the full size; no resize-on-grow protocol. The unbounded variant (with coordinator-mediated MMF resize) is a separate primitive.