Description
Raised by a timed pool acquisition whose deadline expires first.
Acquire
procedure Acquire (Item : in out Unique_Buffer)
Wait until a pool slot is available and attach it to vacant Item. The protected entry suspends a lightweight caller cooperatively and blocks only a native caller's tasking thread.
Parameters
- Item
Vacant buffer that receives sole ownership
Raised exceptions
- Program_Error
Item already owns a slot
Acquire_For
procedure Acquire_For (Item : in out Unique_Buffer; Timeout : Duration)
Acquire within one relative deadline. Negative Timeout waits without a deadline; zero is an immediate attempt.
Parameters
- Item
Vacant buffer that receives ownership on success
- Timeout
Maximum monotonic wait in seconds
Raised exceptions
- Timeout_Error
No slot becomes available before the deadline
- Program_Error
Item already owns a slot
Buffer_Capacity
function Buffer_Capacity (Item : Unique_Buffer) return Positive
Return the fixed payload capacity supplied by Item's pool.
Parameters
- Item
Buffer to inspect
Return value
Maximum writable payload bytes
Copy_From
procedure Copy_From (Item : in out Unique_Buffer; Data : Ada.Streams.Stream_Element_Array)
Copy Data into Item and set its readable length. This convenience operation is for boundaries that do not yet produce directly into a borrowed block.
Parameters
- Item
Acquired destination buffer
- Data
Source bytes
Raised exceptions
- Program_Error
Item is vacant
- Constraint_Error
Data is larger than Item's capacity
Current
function Current (Item : Pool) return Pool_Snapshot
Read the pool's coherent availability counters. This task-safe snapshot does not wait for all outstanding owners to drain.
Parameters
- Item
Pool to inspect
Return value
Current slot accounting
Has_Buffer
function Has_Buffer (Item : Unique_Buffer) return Boolean
Report whether Item currently owns a pool slot.
Parameters
- Item
Buffer to inspect
Return value
True only while Item owns storage
Length
function Length (Item : Unique_Buffer) return Natural
Return the initialized payload length. A vacant buffer has length zero.
Parameters
- Item
Buffer to inspect
Return value
Number of readable payload bytes
Move
procedure Move (Source : in out Unique_Buffer; Target : in out Unique_Buffer)
Transfer ownership without copying payload bytes. Source and Target must belong to the same pool.
Parameters
- Source
Acquired buffer whose ownership transfers
- Target
Vacant buffer that receives the slot
Raised exceptions
- Program_Error
The handles belong to different pools, Source is vacant, or Target already owns a slot
Pool
type Pool
(Block_Size : Positive;
Capacity : Positive)
is limited new Ada.Finalization.Limited_Controlled with private;
Fixed-block storage pool. Pool must outlive every buffer obtained from it; an access discriminant enforces that relationship for ordinary Ada objects. Storage is allocated once during initialization and never grows. Finalizing a Pool with an outstanding buffer or channel token raises Program_Error rather than invalidating live ownership.
Pool_Snapshot
type Pool_Snapshot is record
Available : Natural;
Outstanding : Natural;
end record;
Snapshot of one pool's ownership accounting.
Record fields
- Available
Slots available for acquisition
- Outstanding
Slots held by buffers or channels
Release
procedure Release (Item : in out Unique_Buffer)
Return Item's slot to its pool and leave Item vacant. A slot completing its final nonwrapping generation is permanently retired instead of becoming available again. Releasing a vacant buffer is harmless.
Parameters
- Item
Buffer whose ownership is relinquished
Set_Tag
procedure Set_Tag (Item : in out Unique_Buffer; Value : Interfaces.Unsigned_64)
Associate an application scalar with Item. The tag follows ownership transfer but is not part of the payload.
Parameters
- Item
Acquired buffer to update
- Value
Application-defined scalar
Raised exceptions
- Program_Error
Item is vacant
Tag
function Tag (Item : Unique_Buffer) return Interfaces.Unsigned_64
Return Item's application tag, or zero for a vacant buffer.
Parameters
- Item
Buffer to inspect
Return value
Application-defined scalar
Timeout_Error
Timeout_Error : exception;
Raised by a timed pool acquisition whose deadline expires first.
Try_Acquire
procedure Try_Acquire (Item : in out Unique_Buffer; Acquired : out Boolean)
Attempt to acquire without waiting.
Parameters
- Item
Vacant buffer that receives ownership on success
- Acquired
True only when a slot was attached
Raised exceptions
- Program_Error
Item already owns a slot
Unique_Buffer
type Unique_Buffer
(Owner : not null access Pool)
is limited new Ada.Finalization.Limited_Controlled with private;
Exclusive handle for one pool slot. The type is limited so assignment cannot duplicate ownership. Finalization returns an acquired slot.
With_Readable_Data
procedure With_Readable_Data
(Item : Unique_Buffer; Process : not null access procedure (Data : Ada.Streams.Stream_Element_Array))
Borrow Item's initialized payload for the duration of Process. Empty payloads are passed as a null array. Process executes synchronously and any exception it raises propagates. It must not retain an address into Data after it returns.
Parameters
- Item
Acquired buffer to inspect
- Process
Synchronous payload consumer
Raised exceptions
- Program_Error
Item is vacant
With_Writable_Data
procedure With_Writable_Data
(Item : in out Unique_Buffer;
Process :
not null access procedure (Data : in out Ada.Streams.Stream_Element_Array; Length : in out Natural))
Borrow Item's full writable block for the duration of Process. Length initially contains the current readable length and is committed only when Process returns normally with a value no greater than capacity. An exception leaves the prior readable length unchanged, although payload bytes already mutated by Process remain changed. Process must not retain an address into Data after it returns.
Parameters
- Item
Acquired buffer to modify
- Process
Synchronous payload producer
Raised exceptions
- Program_Error
Item is vacant
- Constraint_Error
Process returns Length greater than capacity