Description
Owns an immutable catalogue of heterogeneous fixed-block buffer pools. Domain-bound public owners and access-free internal capabilities can move one pool token without copying its payload.
Acquire
procedure Acquire (Item : in out Owned_Buffer; Source : Pool_Reference; Result : out Acquisition_Result)
Acquire from Source, waiting until a slot is available.
Parameters
- Item
Vacant domain-bound owner receiving a slot
- Source
Exact pool selected for acquisition
- Result
Buffer_Acquired, Pool_Reserved, Reservation_Releasing, Claim_Limit_Reached, or Pool_Permanently_Exhausted
Raised exceptions
- Program_Error
Source is foreign or Item is occupied Unwinding before the abort-deferred ownership commit leaves Item vacant and restores the acquired slot. After commit, Item is the sole owner.
Acquire
procedure Acquire
(Item : in out Owned_Buffer; Reservation : Pool_Reservation; Result : out Acquisition_Result)
Wait for a slot under one exact active reservation. An older reservation reports Reservation_Stale; an exact reservation reports Reservation_Not_Active, Reservation_Releasing, or Pool_Permanently_Exhausted according to the pool lifecycle. A future, invalid, or foreign reservation raises Program_Error. Claim exhaustion rejects immediately even though this is the blocking overload.
Parameters
- Item
Vacant domain-bound owner receiving a slot
- Reservation
Exact reservation authority
- Result
Total acquisition outcome
Acquire_For
procedure Acquire_For
(Item : in out Owned_Buffer;
Source : Pool_Reference;
Timeout : Duration;
Result : out Acquisition_Result)
Acquire within one relative deadline. Negative Timeout waits without a deadline; zero performs an immediate attempt.
Parameters
- Item
Vacant domain-bound owner receiving a slot
- Source
Exact pool selected for acquisition
- Timeout
Maximum monotonic wait in seconds
- Result
Buffer_Acquired, Acquisition_Timed_Out, Pool_Reserved, Reservation_Releasing, Claim_Limit_Reached, or Pool_Permanently_Exhausted
Raised exceptions
- Program_Error
Source is foreign or Item is occupied Unwinding before the abort-deferred ownership commit leaves Item vacant and restores the acquired slot. After commit, Item is the sole owner.
Acquire_For
procedure Acquire_For
(Item : in out Owned_Buffer;
Reservation : Pool_Reservation;
Timeout : Duration;
Result : out Acquisition_Result)
Timed acquisition under one exact active reservation. Claim exhaustion and reservation-state outcomes reject before waiting; only an admitted base-pool wait may report Acquisition_Timed_Out.
Parameters
- Item
Vacant domain-bound owner receiving a slot
- Reservation
Exact reservation authority
- Timeout
Maximum monotonic wait in seconds
- Result
Total acquisition outcome
Acquisition_Result
type Acquisition_Result is
(Buffer_Acquired,
Pool_Empty,
Acquisition_Timed_Out,
Pool_Reserved,
Reservation_Stale,
Reservation_Not_Active,
Reservation_Releasing,
Claim_Limit_Reached,
Pool_Permanently_Exhausted);
Total outcome of an ordinary or reservation-qualified acquisition. Buffer_Acquired is the only outcome that publishes ownership. Pool_Empty is reachable only from Try_Acquire, while Acquisition_Timed_Out is reachable only from Acquire_For.
Enumeration literals
- Buffer_Acquired
Ownership was published to the destination
- Pool_Empty
No unowned buffer was immediately available
- Acquisition_Timed_Out
The admitted timed wait reached its deadline
- Pool_Reserved
Ordinary acquisition was excluded by a reservation
- Reservation_Stale
The reservation names an older generation
- Reservation_Not_Active
The exact reservation generation is not active
- Reservation_Releasing
Release was prepared but not acknowledged
- Claim_Limit_Reached
The pool's bounded claim capacity is full
- Pool_Permanently_Exhausted
The reservation generation cannot advance
Belongs_To
function Belongs_To (Domain : Buffer_Domain; Reference : Pool_Reference) return Boolean
Report whether Reference names an exact pool in Domain.
Parameters
- Domain
Candidate owning domain
- Reference
Pool reference to validate
Return value
True only for an exact current catalogue member
Block_Size
function Block_Size (Domain : Buffer_Domain; Reference : Pool_Reference) return Positive
Return the configured block size of Reference.
Parameters
- Domain
Owning domain
- Reference
Exact pool reference
Return value
Payload bytes in each pool slot
Raised exceptions
- Program_Error
Reference does not belong to Domain
Buffer_Capacity
function Buffer_Capacity (Item : Owned_Buffer) return Positive
Return Item's selected pool block size.
Parameters
- Item
Acquired domain-bound owner
Return value
Writable payload capacity
Buffer_Domain
type Buffer_Domain (<>) is limited private;
Fixed heterogeneous pool catalogue. Create is the only constructor.
Buffer_Pool
function Buffer_Pool (Item : Owned_Buffer) return Pool_Reference
Return Item's exact pool, or Invalid_Pool when vacant.
Parameters
- Item
Domain-bound owner to inspect
Return value
Selected exact pool or Invalid_Pool
Buffer_Reservation
function Buffer_Reservation (Item : Owned_Buffer) return Pool_Reservation
Return Item's exact reservation provenance, or Invalid_Reservation for a vacant or ordinary buffer.
Parameters
- Item
Domain-bound owner to inspect
Return value
Exact reservation or Invalid_Reservation
Capacity
function Capacity (Domain : Buffer_Domain; Reference : Pool_Reference) return Positive
Return the configured slot capacity of Reference.
Parameters
- Domain
Owning domain
- Reference
Exact pool reference
Return value
Number of pool slots
Raised exceptions
- Program_Error
Reference does not belong to Domain
Copy_From
procedure Copy_From (Item : in out Owned_Buffer; Data : Ada.Streams.Stream_Element_Array)
Copy Data into Item and set its initialized length.
Parameters
- Item
Acquired destination owner
- Data
Source payload bytes
Raised exceptions
- Constraint_Error
Data exceeds Item's capacity
Create
function Create (Configuration : Pool_Configuration_Array) return Buffer_Domain
Construct a domain and all configured pool storage transactionally. Configuration must contain at least one pool. Any failed construction releases every pool that was already created.
Parameters
- Configuration
Complete pool catalogue in logical index order
Return value
Domain owning the configured pools and their storage
Raised exceptions
- Constraint_Error
A pool has Maximum_Claims below Capacity
Current
function Current (Domain : Buffer_Domain; Reference : Pool_Reference) return Pool_Snapshot
Return coherent ownership accounting for Reference.
Parameters
- Domain
Owning domain
- Reference
Exact pool reference
Return value
Current available and outstanding counts
Raised exceptions
- Program_Error
Reference does not belong to Domain
Has_Buffer
function Has_Buffer (Item : Owned_Buffer) return Boolean
Report whether Item owns a slot.
Parameters
- Item
Domain-bound owner to inspect
Return value
True only while Item owns a pool token
Invalid_Pool
Invalid_Pool : constant Pool_Reference;
Sentinel that names no pool.
Invalid_Reservation
Invalid_Reservation : constant Pool_Reservation;
Sentinel that carries no reservation authority.
Is_Valid
function Is_Valid (Reference : Pool_Reference) return Boolean
Report whether Reference contains a complete nonzero identity.
Parameters
- Reference
Opaque pool reference to inspect
Return value
True only for a structurally complete reference
Is_Valid
function Is_Valid (Reservation : Pool_Reservation) return Boolean
Report whether Reservation contains a complete pool reference and a nonzero reservation generation.
Parameters
- Reservation
Opaque reservation reference to inspect
Return value
True only for a structurally complete reservation
Length
function Length (Item : Owned_Buffer) return Natural
Return initialized payload length, or zero while vacant.
Parameters
- Item
Domain-bound owner to inspect
Return value
Initialized byte count
Move
procedure Move (Source : in out Owned_Buffer; Target : in out Owned_Buffer)
Move ownership between vacant/occupied handles of the same domain.
Parameters
- Source
Acquired owner, vacant after success
- Target
Vacant same-domain owner receiving the slot
Raised exceptions
- Program_Error
Owners have different domains or invalid states Validation precedes mutation. Unwinding before the abort-deferred commit restores Source; unwinding after it leaves Target as the sole owner.
Owned_Buffer
type Owned_Buffer (Domain : not null access Buffer_Domain) is limited
new Ada.Finalization.Limited_Controlled with private;
Public single-owner handle tied by accessibility to one domain. A vacant handle does not select a pool until acquisition or movement.
Pool_At
function Pool_At (Domain : Buffer_Domain; Index : Positive) return Pool_Reference
Return the reference at one-based logical Index.
Parameters
- Domain
Domain whose catalogue is selected
- Index
One-based logical catalogue index
Return value
Exact immutable pool reference
Raised exceptions
- Constraint_Error
Index is outside Domain
Pool_Configuration
type Pool_Configuration is record
Block_Size : Positive;
Capacity : Positive;
Maximum_Claims : Positive;
end record;
Complete construction parameters for one owned pool.
Record fields
- Block_Size
Payload capacity of each buffer
- Capacity
Number of independently ownable buffers
- Maximum_Claims
Bound on held and acquisition-in-progress claims; must be at least Capacity
Pool_Configuration_Array
type Pool_Configuration_Array is array (Positive range <>) of Pool_Configuration;
Ordered, nonempty catalogue used to construct a domain.
Pool_Count
function Pool_Count (Domain : Buffer_Domain) return Positive
Return the number of pools owned by Domain.
Parameters
- Domain
Domain to inspect
Return value
Fixed catalogue size
Pool_Reference
type Pool_Reference is private;
Opaque, process-local reference to one immutable domain catalogue slot.
Pool_Reservation
type Pool_Reservation is private;
Opaque authority for one exact reservation generation of one pool. The value is definite and contains no Ada access component.
Release
procedure Release (Item : in out Owned_Buffer)
Release Item to its selected pool and leave it vacant.
Parameters
- Item
Owner relinquishing its slot Validation precedes the abort-deferred ownership commit. After commit, Item remains vacant while normal or unwinding cleanup returns the exact slot to its pool.
Reserved_Pool
function Reserved_Pool (Reservation : Pool_Reservation) return Pool_Reference
Return the pool named by Reservation, or Invalid_Pool when invalid.
Parameters
- Reservation
Reservation to inspect
Return value
Embedded exact pool reference or Invalid_Pool
Set_Tag
procedure Set_Tag (Item : in out Owned_Buffer; Value : Interfaces.Unsigned_64)
Set Item's application-defined scalar tag.
Parameters
- Item
Acquired domain-bound owner
- Value
Application-defined scalar
Tag
function Tag (Item : Owned_Buffer) return Interfaces.Unsigned_64
Return Item's application tag, or zero while vacant.
Parameters
- Item
Domain-bound owner to inspect
Return value
Application-defined scalar
Try_Acquire
procedure Try_Acquire
(Item : in out Owned_Buffer; Source : Pool_Reference; Result : out Acquisition_Result)
Attempt acquisition without waiting.
Parameters
- Item
Vacant domain-bound owner receiving a slot
- Source
Exact pool selected for acquisition
- Result
Buffer_Acquired, Pool_Empty, Pool_Reserved, Reservation_Releasing, Claim_Limit_Reached, or Pool_Permanently_Exhausted
Raised exceptions
- Program_Error
Source is foreign or Item is occupied Unwinding before the abort-deferred ownership commit leaves Item vacant and restores the acquired slot. After commit, Item is the sole owner.
Try_Acquire
procedure Try_Acquire
(Item : in out Owned_Buffer; Reservation : Pool_Reservation; Result : out Acquisition_Result)
Attempt acquisition under one exact active reservation without waiting. State classification precedes Pool_Empty; claim exhaustion precedes the base-pool attempt. Invalid, foreign, or future authority raises Program_Error before the gate is mutated.
Parameters
- Item
Vacant domain-bound owner receiving a slot
- Reservation
Exact reservation authority
- Result
Total acquisition outcome
With_Readable_Data
procedure With_Readable_Data
(Item : Owned_Buffer; Process : not null access procedure (Data : Ada.Streams.Stream_Element_Array))
Borrow initialized payload bytes only for Process's dynamic extent.
Parameters
- Item
Acquired owner to observe
- Process
Synchronous payload observer
With_Writable_Data
procedure With_Writable_Data
(Item : in out Owned_Buffer;
Process :
not null access procedure (Data : in out Ada.Streams.Stream_Element_Array; Length : in out Natural))
Borrow the full writable block. Length commits only after Process returns normally with a value no greater than the pool block size.
Parameters
- Item
Acquired owner to modify
- Process
Synchronous payload producer
Raised exceptions
- Constraint_Error
Process returns an excessive length