Skip to main content

Module handlers

atomic_matrix

Module handlers 

Source
Expand description

§Matrix High-Level API Handles

This module encapsulates the matrix raw primitives into a more ergonomic API that abstracts a lot of manual and repetitive work that has to be executed in order to correctly interact with the matrix, as well as some safe pre-baked functions that add more extensibility over what can be done generally.

§Abstraction Layers

[ internals -> Matrix Internal Frameworks ]   + iter, workers, tables, ...
    * builds on
[ MatrixHandler ]                             + typed blocks, lifecycle, sharing
    * escape hatch
[ AtomicMatrix ]                              + raw offsets, sizes, bytes
    *
[ /dev/shm ]                                  * physical shared memory

§Handler Scope

The handler owns the SHM mapping and provides:

  • Typed block allocation (allocate<T>) and deallocation (free<T>)
  • Raw byte allocation for unknown types (allocate_raw)
  • Zero-copy typed read and write on allocated blocks
  • User-defined lifecycle state management (states 49+)
  • Atomic state transitions with user-defined ordering
  • Thread sharing via SharedHandler
  • Escape hatches to the raw matrix and base pointer

Any high-level datasets and operators will be implemented in the internals folder.

§Lifecycle States

States 0–48 are reserved for internal matrix operations:

  • 0 — STATE_FREE
  • 1 — STATE_ALLOCATED
  • 2 — STATE_ACKED
  • 3 — STATE_COALESCING

States 49 and above are available for user-defined lifecycles. The matrix coalescing engine ignores any state beyond the ones described above — a block in state 112 is never reclaimed automatically. Call free() explicitly when done.

Note: States 4–48 are reserved for future internal state management implementations that have not been planned yet. Better safe than sorry.

§Thread Sharing

MatrixHandler owns the mmap and is not Clone. Use share() to produce a SharedHandler that can be sent to other threads. The original handler must outlive all shared handles derived from it.

Structs§

Block
A typed handle to an allocated block in the matrix.
MatrixHandler
The primary interface for interacting with an AtomicMatrix.
SharedHandler
A lightweight reflection of the original handler that can be safely sent across threads.

Enums§

HandlerError
Errors produced by MatrixHandler and SharedHandler operations.

Constants§

USER_STATE_MIN
Minimum state value available for user-defined lifecycles. States 0–48 are reserved for internal matrix and future framework use. Currently only 0–3 are assigned — the remaining range (4–48) is reserved for future internal lifecycle states without breaking user code.

Traits§

HandlerFunctions
Defines the core interaction surface for any matrix handle.