Module shm 

POSIX shared-memory helpers — V1 substrate for cross-process rings.

Wraps shm_open / ftruncate / mmap / munmap / shm_unlink into a small, RAII-friendly API. Unix-only; Windows support is a separate concern (Win32 named file mapping) that can land later.

Naming

Segments are named /orbit-{fleet}-{kind}-{uid} — fleet name from the embedder, KIND from OrbitTyped::KIND, UID from geteuid(). UID-scoping avoids the /dev/shm sticky-bit cross-user collision problem (a stale segment owned by one user blocks another from shm_unlink-ing it on next boot).

Rings that require a process-recoverable writer lock also open a companion orbit-{fleet}-{kind}-{uid}.lock file. It carries no ring data or state; it only supplies a regular-file inode for flock, because advisory locking on a POSIX SHM descriptor is not uniformly supported across the Unix targets Orbit serves. An unlocked stale companion file is safe to reuse.

Those files live in a per-uid directory — $XDG_RUNTIME_DIR/orbit-{uid} where the session provides one, /tmp/orbit-{uid} otherwise — created 0700 and checked on every lock. They were once in /tmp directly, which made them squattable: see [lock_dir].

Lifetime

ShmRegion owns the mapped pointer and unmaps on drop. It does NOT shm_unlink on drop — the segment lives until an explicit ShmRegion::unlink call. This matches POSIX convention: a segment with mapped users is not removed; shm_unlink only prevents new opens, the current mapping stays valid until the last process unmaps.

Structs

FleetMembership

A process’s membership in a fleet: a shared flock on the fleet’s lock file, held for as long as this lives and released by the kernel when the process dies, however it dies. It is what try_lock_fleet_exclusive contends with, so a tool that removes the fleet’s segments cannot do so while any member is alive.

ShmRegion

A mapped POSIX SHM region. Drop unmaps; unlink removes the underlying name and any companion lock file (only the creator should call it on shutdown).

ShmRegionLock

RAII guard for a ShmRegion’s process-recoverable exclusive lock.

Enums

ShmValidation

Result of physically validating an existing POSIX SHM object.

Constants

SHM_NAMESPACE

Namespace used by Orbit POSIX shared-memory objects.

Functions

fleet_lock_path

Where a fleet’s members hold their presence: <lock dir>/orbit-<fleet>.fleet.

fleet_lock_path_for_uid

The same for another user’s fleet, for lifecycle tools that address a uid other than their own.

join_fleet_membership

Join the fleet’s membership. Waits for a lifecycle tool that holds the exclusive lock at that moment; a clear in progress finishes first.

ring_segment_name

Build the conventional name for an Orbit ring segment.

ring_segment_name_for_uid

Build the conventional name for an Orbit ring segment owned by uid.

try_lock_fleet_exclusive

Exclusive hold on a fleet, for the tool that removes its segments.