Description
Defines the representation contract shared by Flyology's relocatable data structures. Stored layouts contain only fixed-width scalar values and payload bytes; a Region_View's native address is process-local state and is never copied into its backing bytes. Linking this hierarchy has no scheduler, poller, task, mapping, or allocation side effect. Every attached structure view caches a persisted initialization epoch. Reinitializing an extent advances that epoch, so an older local view fails closed instead of applying cached geometry to replacement bytes. If out-of-band corruption destroys the epoch itself, recovery Initialize treats the bytes as fresh; all earlier views must first be retired.
Busy_Error
Busy_Error : exception;
Raised when a nonblocking internally synchronized operation cannot acquire its stored guard immediately. Callers may retry only at an application-selected scheduling or fairness point; implementations do not spin, sleep, or block an event-loop pthread.
Byte_Count
type Byte_Count is new Interfaces.Unsigned_64;
Fixed-width byte count used by stored extents and region views.
Handle_Error
Handle_Error : exception;
Raised when a handle is null, malformed, out of range, stale, already reclaimed, or otherwise invalid for the receiving structure.
Immutable_Storage_View
type Immutable_Storage_View is private;
Opaque process-local binding used by immutable storage-type instances. Structure implementations construct bindings only after validating a complete element extent. Applications cannot inspect or construct the native address retained by this value. @exclude
Layout_Error
Layout_Error : exception;
Raised when stored magic, version, schema, extent, configuration, or mutable bookkeeping is incompatible or corrupt.
Layout_Identity
type Layout_Identity is record
Magic : Interfaces.Unsigned_64;
Version : Interfaces.Unsigned_32;
Schema : Interfaces.Unsigned_64;
end record;
Stable identity of one stored layout. Leaf packages expose one value so wrappers can consume the identity without repeating numeric literals. Bump Version or Schema when the leaf's stored contract changes; Magic identifies the structure family.
Record fields
- Magic
Nonzero 64-bit structure-family identifier
- Version
Leaf-specific stored-layout version
- Schema
Nonzero 64-bit layout and algorithm schema identifier
Null_Offset
Null_Offset : constant Region_Offset := 0;
Null persisted relationship.
Open_Result
type Open_Result is (Initialized_New, Attached_Existing, Initialization_In_Progress);
Outcome of one race-safe attempt to create a virgin stored object or attach to an existing compatible object.
Enumeration literals
- Initialized_New
The caller atomically claimed an exact zero lifecycle sentinel, initialized the object, and attached Item
- Attached_Existing
A ready compatible object already existed and Item attached to it without rewriting stored bytes
- Initialization_In_Progress
Another caller owns the virgin-state initialization claim; Item remains detached and no waiting occurs
Poison_Error
Poison_Error : exception;
Raised when an object or independently recoverable slot was explicitly poisoned after an interrupted or failed mutation. Poisoned bytes are never silently treated as ready; the leaf defines explicit recovery.
Region_Error
Region_Error : exception;
Raised when a local region view is detached or a requested slice is null, overflowing, misaligned, out of bounds, or not representable by the native address model.
Region_Offset
type Region_Offset is new Interfaces.Unsigned_64;
Fixed-width offset from the first byte of a backing region. Zero is the null sentinel for persisted relationships and is not a valid structure location.
Region_View
type Region_View is limited private;
Process-local view of mapped or arena-backed bytes. The type owns no mapping and performs no allocation. Flyology.Data_Structures.Regions attaches and detaches it; every structure view borrowing the same bytes must be detached before the application unmaps or releases the region.
Timeout_Error
Timeout_Error : exception;
Raised when an explicitly waiting data-structure operation cannot complete before its nonnegative monotonic timeout expires. Waiting operations yield the calling Ada task between attempts; their leaf contracts describe which resource conditions are retried.
Wait_Timeout
subtype Wait_Timeout is Duration range 0.0 .. 86_400.0;
Nonnegative relative timeout accepted by explicitly waiting operations, limited to 24 hours. Zero permits one immediate attempt and then times out. Time starts with the first unsuccessful claim.