Description
Provides explicitly task-owned allocation regions with bulk release.
Create_Region
function Create_Region
(Pool : in out Task_Pool; Chunk_Storage : System.Storage_Elements.Storage_Count := 65_536)
return not null Region_Handle
Create a region owned by Pool and the calling task. Chunk_Storage is the preferred backing-chunk capacity; a larger allocation receives a dedicated sufficiently large chunk. Region-backed references must not escape the region's lifetime.
Parameters
- Pool
Task-owned storage pool
- Chunk_Storage
Preferred backing-chunk capacity
Return value
Handle for use in a named allocator, new (Handle) T
Raised exceptions
- Ownership_Error
The calling task does not own Pool
- Constraint_Error
Chunk_Storage is zero
Ownership_Error
Ownership_Error : exception;
Raised when a pool or region is used by a task other than its owner, or when Release is given a handle not created by this package.
Pool_Statistics
type Pool_Statistics is record
Live_Regions : Natural;
Consumed_Storage : System.Storage_Elements.Storage_Count;
Reserved_Storage : System.Storage_Elements.Storage_Count;
end record;
Accounting for storage retained by live regions. Consumed_Storage includes alignment and compiler finalization overhead. Reserved_Storage is the total capacity of backing chunks.
Record fields
- Live_Regions
Number of regions not yet released
- Consumed_Storage
Storage consumed within live regions
- Reserved_Storage
Backing storage retained by live regions
Region_Handle
subtype Region_Handle is System.Storage_Pools.Subpools.Subpool_Handle;
Standard Ada subpool handle accepted by a named allocator.
Release
procedure Release (Region : in out Region_Handle)
Finalize every controlled object in Region and release all of its backing chunks. References into the region become invalid. Null is an idempotent no-op; a successful call sets the handle to null. If controlled finalization raises, storage is still reclaimed before the exception propagates. Ada does not copy an in out scalar back after an exceptional return, so the caller must treat every handle copy as invalid and set the passed variable to null in its handler.
Parameters
- Region
Region to finalize and release
Raised exceptions
- Ownership_Error
Region belongs to another pool type or task
Statistics
function Statistics (Pool : Task_Pool) return Pool_Statistics
Return accounting for Pool. Only the owner task may query it.
Parameters
- Pool
Task-owned storage pool
Return value
Current live-region storage accounting
Raised exceptions
- Ownership_Error
The calling task does not own Pool
Task_Pool
type Task_Pool is limited new System.Storage_Pools.Subpools.Root_Storage_Pool_With_Subpools with private;
Pool owned by the task that declares it. Each access type associated with the pool must use a named Region_Handle in every allocator. An allocator without a region raises Program_Error. The pool is not synchronized and must not outlive its owning task.