Description
Provides bounded fixed-size immutable-element allocation in relocatable storage. Stored slots contain generation, state, reserved metadata, and payload bytes, but no address or access value. Allocation, reclamation, and payload access are internally synchronized across native tasks, processes, and distinct mappings. Initialization, attachment, destruction, and backing-region lifetime changes require quiescence across every view. Concurrent Create_Or_Attach calls are allowed only on allocation-certified virgin bytes; if Ready may exist, attachment quiescence applies. Lifecycle operations must also be excluded from ordinary use of the same local View. Immediate operations retain bounded contention outcomes or Busy_Error; timed overloads yield through one explicit timeout. Termination during an operation leaves its slot abandoned rather than silently reusable; an external recovery authority may poison and reclaim that slot only after establishing owner death and target-slot quiescence.
Allocation_Result
type Allocation_Result is (Allocated, Exhausted, Allocation_Contended);
Allocation outcome.
Enumeration literals
- Allocated
A slot was claimed and Value contains its handle
- Exhausted
No free slot was observed during the capacity scan
- Allocation_Contended
A concurrently claimed free slot was observed
Attach
procedure Attach (Item : out View; Region : Region_View; Location : Region_Offset; Capacity : Positive)
Attach to a quiescent existing slab and validate its complete layout, slot states, generations, and expected configuration. Valid transitional and poisoned slots remain attachable so a recovery authority need not retain a pre-failure View.
Parameters
- Item
View attached on success
- Region
Independently attached backing region
- Location
Stored slab offset
- Capacity
Expected slot count
Raised exceptions
- Layout_Error
Stored data is incompatible or corrupt
- Region_Error
Region or extent is invalid
Contention_Limit
Contention_Limit : constant Positive := 64;
Maximum compare/exchange attempts made by one immediate claim campaign. Timed overloads may use shorter campaigns between yields.
Create_Or_Attach
procedure Create_Or_Attach
(Item : out View;
Region : Region_View;
Location : Region_Offset;
Capacity : Positive;
Result : out Open_Result)
Atomically initialize a known-virgin zeroed extent or attach to a ready compatible slab. Only the exact zero lifecycle sentinel is eligible for creation; no existing lifecycle is reinitialized. The operation does not wait for another initializer. Concurrent calls are permitted only while the allocation protocol guarantees virgin bytes; if Ready may exist, Attach quiescence applies.
Parameters
- Item
Attached view, or detached when initialization is in progress
- Region
Independently attached backing region
- Location
Stored slab offset
- Capacity
Expected slot count
- Result
Whether this caller initialized, attached, or observed an initialization in progress
Current_Metadata
function Current_Metadata (Item : View) return Metadata
Return the immutable stored configuration.
Parameters
- Item
Attached view
Return value
Validated slab metadata
Raised exceptions
- Region_Error
Item is detached
Destroy
procedure Destroy (Item : in out View)
Invalidate an empty slab and detach Item. Every view and handle must be quiescent; live slots make destruction fail rather than leak ownership.
Parameters
- Item
Exclusively synchronized slab view
Raised exceptions
- Program_Error
One or more slots remain live
Detach
procedure Detach (Item : in out View)
Detach Item without changing backing bytes or reclaiming live slots.
Parameters
- Item
Local view to detach
Element
with package Element is new Flyology.Data_Structures.Storage_Types.Elements (<>);
Identity
Identity : constant Layout_Identity := (Magic => Magic, Version => Layout_Version, Schema => Schema);
Complete stable layout identity for envelope instances and tooling.
Initialize
procedure Initialize
(Item : out View; Region : Region_View; Location : Region_Offset; Capacity : Positive)
Create a new slab at Location and attach Item. The caller must exclusively own the complete target extent. Initialization publishes a ready state with a release store only after all metadata is complete. Every preexisting view becomes stale and must attach again.
Parameters
- Item
View attached on success
- Region
Attached backing region
- Location
Nonzero aligned stored offset
- Capacity
Number of slots
Raised exceptions
- Region_Error
Region or extent is invalid
- Constraint_Error
Configuration cannot be represented
Is_Attached
function Is_Attached (Item : View) return Boolean
Report whether Item is locally attached.
Parameters
- Item
View to inspect
Return value
True while Item retains local mapping information; this does not guarantee the cached initialization epoch is still current
Layout_Version
Layout_Version : constant Interfaces.Unsigned_32 := 4;
Leaf-specific stored-layout version.
Magic
Magic : constant Interfaces.Unsigned_64 := 16#4644_534C_4142_3031#;
Eight-byte magic stored in every slab header.
Metadata
type Metadata is record
Capacity : Interfaces.Unsigned_32;
Element_Size : Interfaces.Unsigned_32;
Element_Alignment : Interfaces.Unsigned_32;
Extent : Byte_Count;
end record;
Immutable stored configuration reported by an attached view.
Record fields
- Capacity
Number of independently allocatable slots
- Element_Size
Payload bytes in each slot
- Element_Alignment
Required payload alignment
- Extent
Complete stored layout size in bytes
Poison_Abandoned
procedure Poison_Abandoned (Item : in out View; Slot : Handles.Slot_Index)
Mark a transitional slot abandoned. The caller is the recovery authority and must first establish that its owner has terminated and that no operation can still access the target slot. Live and free slots are rejected; an already poisoned slot is accepted idempotently.
Parameters
- Item
Any attached slab view
- Slot
One-based slot selected by the recovery authority
Raised exceptions
- Handle_Error
Slot is null or out of range
- Program_Error
Slot is live or free rather than abandoned
- Busy_Error
The bounded poison claim budget expires
Poison_Abandoned_At
procedure Poison_Abandoned_At
(Region : Region_View; Location : Region_Offset; Capacity : Positive; Slot : Handles.Slot_Index)
Validate immutable slab identity and geometry, then poison a transitional slot without requiring a retained pre-failure View or traversing unrelated mutable slots. The caller must establish owner death and target-slot quiescence before calling it.
Parameters
- Region
Attached backing region
- Location
Stored slab offset
- Capacity
Expected slot count
- Slot
One-based slot selected by the recovery authority
Raised exceptions
- Layout_Error
Immutable identity or geometry is incompatible
- Handle_Error
Slot is null or out of range
- Program_Error
Slot is live or free rather than abandoned
- Busy_Error
The bounded poison claim budget expires
Read
procedure Read (Item : View; Value : Handles.Handle; Data : out Element.Observed)
Observe exactly one immutable slot without copying its representation.
Parameters
- Item
Any concurrently attached slab view
- Value
Live handle returned by this slab
- Data
Observation assigned only on success
Raised exceptions
- Handle_Error
Value is invalid or stale
- Busy_Error
The bounded claim budget is exhausted
- Poison_Error
Value addresses a poisoned slot
Read
procedure Read (Item : View; Value : Handles.Handle; Data : out Element.Observed; Timeout : Wait_Timeout)
Read one slot after waiting through transient same-slot contention.
Parameters
- Item
Any concurrently attached slab view
- Value
Live handle returned by this slab
- Data
Observation assigned only on success
- Timeout
Maximum wait; zero permits one bounded claim campaign
Raised exceptions
- Timeout_Error
Slot contention persists through the deadline
Recover_Poisoned
procedure Recover_Poisoned (Item : in out View; Slot : Handles.Slot_Index)
Explicitly recycle a poisoned slot after external recovery authority has established target-slot quiescence. The generation advances before the slot is published, so every earlier handle remains stale. A maximum generation cannot advance and remains poisoned until whole-object exclusive Initialize. Other failures also leave the slot poisoned.
Parameters
- Item
Any attached slab view
- Slot
One-based poisoned slot to reclaim
Raised exceptions
- Handle_Error
Slot is null or out of range
- Program_Error
Slot is not poisoned
- Poison_Error
The slot generation is exhausted
Release
procedure Release (Item : in out View; Value : Handles.Handle)
Reclaim Value and advance its generation so every copy becomes stale. Releasing the maximum generation permanently poisons that slot until exclusive whole-pool initialization instead of wrapping to an old stamp.
Parameters
- Item
Any concurrently attached slab view
- Value
Live handle returned by this slab
Raised exceptions
- Handle_Error
Value is null, malformed, stale, or reclaimed
- Busy_Error
The bounded claim budget is exhausted
- Poison_Error
Value addresses a poisoned slot or its generation is exhausted and the slot was retired
- Layout_Error
Slot bookkeeping is corrupt
Release
procedure Release (Item : in out View; Value : Handles.Handle; Timeout : Wait_Timeout)
Reclaim Value after waiting through transient same-slot contention.
Parameters
- Item
Any concurrently attached slab view
- Value
Live handle returned by this slab
- Timeout
Maximum wait; zero permits one bounded claim campaign
Raised exceptions
- Timeout_Error
Slot contention persists through the deadline
Replace
procedure Replace (Item : in out View; Value : Handles.Handle; Data : Element.Source)
Replace exactly one immutable slot from Data. Independent creation completes before the slot claim, so a raising creator cannot mutate it.
Parameters
- Item
Any concurrently attached slab view
- Value
Live handle returned by this slab
- Data
Application value accepted by the bound creator
Raised exceptions
- Handle_Error
Value is invalid or stale
- Busy_Error
The bounded claim budget is exhausted
- Poison_Error
Value addresses a poisoned slot
Replace
procedure Replace
(Item : in out View; Value : Handles.Handle; Data : Element.Source; Timeout : Wait_Timeout)
Replace one slot after waiting through transient same-slot contention.
Parameters
- Item
Any concurrently attached slab view
- Value
Live handle returned by this slab
- Data
Application value accepted by the bound creator
- Timeout
Maximum wait; zero permits one bounded claim campaign
Raised exceptions
- Timeout_Error
Slot contention persists through the deadline
Required_Storage
function Required_Storage (Capacity : Positive) return Byte_Count
Compute the complete layout extent without touching a region.
Parameters
- Capacity
Number of slots
Return value
Required header, metadata, padding, and payload bytes
Raised exceptions
- Constraint_Error
Alignment or arithmetic is invalid
Schema
Schema : constant Interfaces.Unsigned_64 :=
16#0002_534C_4142_0003#
xor Element.Signature
xor Interfaces.Shift_Left (Interfaces.Unsigned_64 (Element.Version), 32);
Schema identifier for the current fixed-width slab layout.
Try_Allocate
procedure Try_Allocate
(Item : in out View; Data : Element.Source; Value : out Handles.Handle; Result : out Allocation_Result)
Attempt to create and allocate one free slot without waiting. The handle is published only after the bound creator returns. Every outcome is bounded by one scan of the validated capacity. A process that terminates after the slot becomes live but before it records the returned handle leaves a committed allocation that cannot be identified from the slab alone; applications needing recovery must journal that ownership or exclusively reinitialize the whole pool.
Parameters
- Item
Any concurrently attached slab view
- Data
Application value accepted by the bound creator
- Value
New generation-stamped handle or Null_Handle
- Result
Allocated, exhausted, or bounded-contention outcome
Try_Allocate
procedure Try_Allocate
(Item : in out View;
Data : Element.Source;
Timeout : Wait_Timeout;
Value : out Handles.Handle;
Result : out Allocation_Result)
Retry bounded allocation contention through one timeout. A genuinely exhausted slab still returns Exhausted immediately after a full scan.
Parameters
- Item
Any concurrently attached slab view
- Data
Application value accepted by the bound creator
- Timeout
Maximum wait; zero permits one bounded scan
- Value
New generation-stamped handle or Null_Handle
- Result
Allocated or exhausted outcome
Raised exceptions
- Timeout_Error
Free-slot claims contend through the deadline
View
type View is limited private;
Process-local attached view. It owns neither the backing region nor any allocated slot and must be detached before the backing bytes disappear.