Description
Provides a bounded adaptive fixed-size pool backed by a relocatable arena. The pool adds fixed-size slab chunks only after existing chunks are exhausted. Chunk allocation is serialized by one persisted nonblocking guard; live chunks use Slab_Pools per-slot synchronization, so operations on different slots may proceed concurrently through distinct local views. One local View must not be used concurrently because it owns process-local chunk attachment caches. A dead chunk-creation owner leaves the pool guard locked; an external authority may poison the whole pool after establishing owner death and quiescence. Recovery requires exclusive reinitialization of the backing arena followed by the pool; reinitializing only the outer pool would orphan its old chunk allocations. The pool and every local view must be detached before the arena mapping disappears. Every operation taking an arena rejects an arena whose instance identity or incarnation differs from the one the view attached to. Arena_Provider must be configured with a Minimum_Block_Size of at least Minimum_Arena_Alignment so every nested slab has its required alignment.
Allocation_Result
type Allocation_Result is (Allocated, Exhausted, Allocation_Contended, Arena_Exhausted);
Allocation attempt outcome.
Enumeration literals
- Allocated
A slot was initialized and Value names it
- Exhausted
Every permitted chunk is full
- Allocation_Contended
Pool or slot metadata is currently owned
- Arena_Exhausted
The backing arena cannot allocate another chunk
Arena_Provider
with package Arena_Provider is new Flyology.Data_Structures.Arenas (<>);
Attach
procedure Attach
(Item : out View; Region : Region_View; Location : Region_Offset; Arena : Arena_Provider.View)
Attach to a quiescent compatible pool and validate every live chunk.
Parameters
- Item
View attached on success
- Region
Independently attached outer region
- Location
Stored pool location
- Arena
Independently attached matching arena
Raised exceptions
- Layout_Error
Identity, geometry, arena alignment, table, or chunk is incompatible or corrupt
- Busy_Error
A chunk creation was active or abandoned
Create_Or_Attach
procedure Create_Or_Attach
(Item : out View;
Region : Region_View;
Location : Region_Offset;
Arena : Arena_Provider.View;
Result : out Open_Result)
Create in allocation-certified virgin bytes or attach to an exact ready pool. Arena algorithm, instance, incarnation, element, and chunk geometry must match.
Parameters
- Item
Attached view or detached during another initialization
- Region
Caller-owned outer backing region
- Location
Stored pool location
- Arena
Attached backing arena
- Result
Creation, attachment, or in-progress outcome
Raised exceptions
- Constraint_Error
Arena allocation alignment is insufficient
Destroy
procedure Destroy (Item : in out View; Arena : in out Arena_Provider.View)
Destroy every empty chunk, return its allocation to Arena, invalidate the outer pool, and detach Item. All views and handles must be quiescent. If a later chunk is live, earlier empty chunks may already have been reclaimed when Program_Error is raised; the remaining pool stays ready.
Parameters
- Item
Exclusively synchronized pool view
- Arena
Matching exclusively synchronized backing arena view
Raised exceptions
- Program_Error
A chunk still contains a live slot
Detach
procedure Detach (Item : in out View)
Detach local chunk caches and the outer view without releasing storage.
Parameters
- Item
View to detach
Element
with package Element is new Flyology.Data_Structures.Storage_Types.Elements (<>);
Handle
type Handle is record
Chunk : Interfaces.Unsigned_32 := 0;
Slot : Handles.Slot_Index := 0;
Stamp : Handles.Generation := 0;
Epoch : Interfaces.Unsigned_32 := 0;
end record;
Generation-stamped address-independent slot identity.
Record fields
- Chunk
One-based chunk table index
- Slot
One-based slot within the chunk slab
- Stamp
Nonzero slab-slot generation
- Epoch
Adaptive-pool initialization incarnation
Identity
Identity : constant Layout_Identity := (Magic => Magic, Version => Layout_Version, Schema => Schema);
Complete persisted pool identity.
Initialize
procedure Initialize
(Item : out View; Region : Region_View; Location : Region_Offset; Arena : Arena_Provider.View)
Destructively create an empty pool. The arena must be attached and the caller must exclusively own the outer extent. If the outer extent held an earlier pool incarnation, the caller must first reinitialize or otherwise reclaim its arena allocations; this operation cannot discover allocations after overwriting the old chunk table.
Parameters
- Item
View attached on success
- Region
Caller-owned outer backing region
- Location
Nonzero 64-byte-aligned outer location
- Arena
Attached backing arena
Raised exceptions
- Constraint_Error
Arena allocation alignment is insufficient
Is_Attached
function Is_Attached (Item : View) return Boolean
Test process-local attachment.
Parameters
- Item
View to inspect
Return value
True while Item retains outer mapping information
Layout_Version
Layout_Version : constant Interfaces.Unsigned_32 := 1;
Leaf-specific stored-layout version.
Magic
Magic : constant Interfaces.Unsigned_64 := 16#4644_5341_504F_4F31#;
Eight-byte magic stored in every adaptive-pool header.
Maximum_Chunks
Maximum_Chunks : Positive;
Minimum_Arena_Alignment
Minimum_Arena_Alignment : constant Byte_Count := 64;
Smallest backing-arena allocation alignment accepted by this pool.
Null_Handle
Null_Handle : constant Handle := (others => <>);
Null adaptive-pool relationship.
Poison
procedure Poison (Region : Region_View; Location : Region_Offset)
Poison the whole pool after external owner-death and quiescence checks.
Parameters
- Region
Attached outer backing region
- Location
Stored pool location
Read
procedure Read
(Item : in out View; Arena : Arena_Provider.View; Value : Handle; Data : out Element.Observed)
Observe one live immutable element.
Parameters
- Item
Non-shared process-local pool view
- Arena
Matching backing arena view
- Value
Live adaptive-pool handle
- Data
Observation assigned on success
Release
procedure Release (Item : in out View; Arena : Arena_Provider.View; Value : Handle)
Release one live slot. Every copy of Value becomes stale.
Parameters
- Item
Non-shared process-local pool view
- Arena
Matching backing arena view
- Value
Live adaptive-pool handle
Replace
procedure Replace (Item : in out View; Arena : Arena_Provider.View; Value : Handle; Data : Element.Source)
Replace one live immutable element.
Parameters
- Item
Non-shared process-local pool view
- Arena
Matching backing arena view
- Value
Live adaptive-pool handle
- Data
Application value accepted by Element
Required_Storage
function Required_Storage return Byte_Count
Compute the fixed outer pool header and chunk-table extent.
Return value
Complete stored outer extent; chunk slabs remain arena-backed
Schema
Schema : constant Interfaces.Unsigned_64 :=
16#0001_4150_4F4F_0001#
xor Arena_Provider.Identity.Magic
xor Arena_Provider.Identity.Schema
xor Element.Signature
xor Interfaces.Shift_Left (Interfaces.Unsigned_64 (Element.Version), 32)
xor Interfaces.Unsigned_64 (Slots_Per_Chunk)
xor Interfaces.Shift_Left (Interfaces.Unsigned_64 (Maximum_Chunks), 32);
Schema binds arena, element, and fixed chunk geometry.
Slots_Per_Chunk
Slots_Per_Chunk : Positive;
Try_Allocate
procedure Try_Allocate
(Item : in out View;
Arena : in out Arena_Provider.View;
Data : Element.Source;
Value : out Handle;
Result : out Allocation_Result)
Allocate from an existing slab or add one arena-backed chunk. The call never waits; arena exhaustion is distinct from the configured chunk limit and transient metadata contention.
Parameters
- Item
Non-shared process-local pool view
- Arena
Matching backing arena view
- Data
Application value accepted by Element
- Value
New handle or Null_Handle
- Result
Allocation outcome
View
type View is limited private;
Process-local attached view with bounded chunk attachment caches.