Skip to main content

Module shared_universal

subetha_cxc

Module shared_universal 

Source
Expand description

SharedUniversal<T> - Layer-2 cross-process container that migrates between Shared* backings as the workload shape changes.

§The architectural claim

A single cross-process container that auto-swaps its backing storage when the observed operation mix favors a different shape. At creation time the container starts in Vec mode (cheap pushes, O(N) contains). When contains calls dominate (the common case for membership / dedup workloads), the container migrates to HashMap mode (O(1) contains, slightly more expensive insert). Subsequent peer reads observe the migration via a version bump in the shared state header and transparently re-open the new backing.

§The MVP scope

  • 2 backings only: SharedVec<T> and SharedHashMap<T, ()>. The extension to 5 backings (SharedRing, SharedHandleTable, SharedBTreeMap, SharedTreiberStack) is its own bead.
  • Single-writer model: ONE process holds the writer role and triggers migrations. Other processes are read-only observers that follow the strategy tag. Multi-writer voting protocol is ap-uvj.
  • Local policy: the writer’s local op histogram drives migration decisions. Quorum / cross-process voting is ap-uvj.

§File layout

Three coordinated files per logical container:

<base>.state.bin           always; small header MMF
<base>-v{N}-vec.bin        current backing if strategy == Vec
<base>-v{N}-map.bin        current backing if strategy == Map

On migration: writer creates the new -v{N+1}-{strategy}.bin, copies the snapshot, then bumps state.bin’s version+strategy with a single CAS. Readers see the bump on their next op and re-open transparently.

§Concurrency model

  • Reader / writer ops take an INTERNAL RwLock<Backing<T>> on the handle (process-local; protects against the re-open race between two ops in the same process).
  • Re-open is double-checked: re-read state.version under the write lock; if some other thread already re-opened, drop the write lock and use the current backing.
  • Migration is ONLY safe from a single writer process. If two processes both try to migrate, both will succeed locally but race on the state CAS; the loser’s new backing file is orphaned (cleanable). The voting protocol (ap-uvj) prevents this; the MVP documents the single-writer constraint.

Structs§

SharedUniversal
UniversalHeader

Enums§

Strategy
Strategy tag: which backing is currently live.
UniversalError

Constants§

UNIVERSAL_MAGIC