Module shared_handle_table 

SharedHandleTable<T> - cross-process ECS-style slotmap.

Same architectural shape as the in-process AdaptiveHandle / Slotmap, but the slot table lives in a memory-mapped file so handles are valid across processes. Handle = (generation: u32, slot: u32) packed into a u64; generation bumps on every insert and every remove so stale handles fail visibility check across the process boundary.

Layout

+-----------------------------+
| HandleHeader (64B)          |
|   - magic                   |
|   - capacity                |
|   - slot_size               |
|   - free_list_head_packed   |  (counter:u32, slot:u32) packed u64
|   - live_count              |
+-----------------------------+
| Slot[0] (64B cache line)    |
|   - generation: AtomicU32   |
|   - occupied:   AtomicU32   |
|   - next_free:  AtomicU32   |
|   - _pad:       u32         |
|   - payload:    [u8; 48]    |
+-----------------------------+
| Slot[1] ...                 |
+-----------------------------+

Generation parity

Even generation = vacant, odd = occupied. Bumped on every insert (vacant -> occupied) and every remove (occupied -> vacant). A handle from generation N matches only when the slot is currently at generation N.

Free list

ABA-free Treiber stack. Head is packed (counter, slot_idx) so every CAS bumps the counter, making the (head, next) sequence distinguishable from the (head, _, next-after-reinsert) sequence that would otherwise alias. Each vacant slot’s next_free field is the linkage.

Structs

Handle

Opaque cross-process handle. Packed (generation: u32 high, slot: u32 low).

HandleHeader

SharedHandleTable

SharedSlot

Enums

HandleTableError

Constants

HANDLE_TABLE_MAGIC

NIL_SLOT

Sentinel for “no slot” in the free list.

SLOT_PAYLOAD_BYTES

Functions

handle_table_file_size

slot_offset