Description
Supplies bounded closeable channels that transfer unique buffer ownership without copying payload bytes. The protected queue carries fixed ownership records; payload storage remains in the associated pool.
Await_Drained
procedure Await_Drained (Item : in out Channel)
Wait until Close has occurred and every accepted buffer was received.
Parameters
- Item
Channel to observe
Channel
type Channel
(Owner : not null access Pool;
Capacity : Positive)
is limited new Ada.Finalization.Limited_Controlled with private;
Fixed-capacity MPMC FIFO tied to one buffer pool. Finalization closes the channel and returns any undelivered buffers to Owner. Every transfer commits its queue update and its ownership change in one protected action, so aborting a sender or a receiver leaves the message with exactly one owner: the sender, the channel, or the target.
Channel_Access
type Channel_Access is access all Channel;
Named access capability used by operation-producing overloads. The channel must outlive every operation started through this capability. A local aliased channel therefore supplies Queue'Unchecked_Access only within a scope that finishes or finalizes all such operations first.
Channel_Closed
Channel_Closed : exception;
Raised when a send observes a closed channel, or a receive observes a closed and drained channel.
Close
procedure Close (Item : in out Channel)
Idempotently reject new sends and allow queued buffers to drain.
Parameters
- Item
Channel to close
Current
function Current (Item : Channel) return Snapshot
Read channel state under its protected lock.
Parameters
- Item
Channel to inspect
Return value
Current close, queue, and waiter counts
Finish
procedure Finish (Operation : in out Receive_Operation; Target : in out Unique_Buffer)
Consume a successful receive and move its buffer into Target.
Parameters
- Operation
Terminal receive operation
- Target
Vacant same-pool destination
Finish
procedure Finish
(Operation : in out Receive_Operation; Target : in out Unique_Buffer; Metadata : out Transfer_Metadata)
Consume a successful receive and return its transfer metadata.
Parameters
- Operation
Terminal receive operation
- Target
Vacant same-pool destination
- Metadata
Metadata supplied by the sender
Finish
procedure Finish (Operation : in out Send_Operation; Value : in out Unique_Buffer)
Consume a send. Value must be vacant. A failed or cancelled send moves its original buffer into Value before raising; success leaves it vacant.
Parameters
- Operation
Terminal send operation
- Value
Vacant same-pool destination for untransferred ownership
No_Metadata
No_Metadata : constant Transfer_Metadata := 0;
Default metadata used by send overloads. Zero is an ordinary encoded value, not an indication that metadata is absent.
Operation_Cancelled
Operation_Cancelled : exception renames Flyology.Cancellation.Operation_Cancelled;
Raised when a cancellation-aware receive observes its one-shot token.
Receive_Move
function Receive_Move
(Set : not null access Flyology.Operations.Completion_Set'Class;
Item : not null Channel_Access;
Timeout : Duration := -1.0) return Receive_Operation
Start a receive whose operation will own the dequeued buffer. No vacant destination is borrowed during the wait; typed Finish supplies it.
Parameters
- Set
Completion set that owns the operation slot
- Item
Aliased channel that outlives the operation
- Timeout
Relative deadline; negative waits indefinitely
Return value
Started limited receive operation
Receive_Move
procedure Receive_Move (Item : in out Channel; Target : in out Unique_Buffer)
Receive the oldest buffer, waiting while the channel is open and empty. Target must be vacant and belong to Item's pool.
Parameters
- Item
Channel yielding ownership
- Target
Vacant buffer that receives the oldest payload
Raised exceptions
- Channel_Closed
Closed channel has fully drained
- Program_Error
Target is occupied or belongs to another pool
Receive_Move
procedure Receive_Move
(Item : in out Channel; Target : in out Unique_Buffer; Metadata : out Transfer_Metadata)
Receive the oldest buffer and its channel-local metadata.
Parameters
- Item
Channel yielding ownership
- Target
Vacant buffer that receives the oldest payload
- Metadata
Metadata supplied by the sender
Raised exceptions
- Channel_Closed
Closed channel has fully drained
- Program_Error
Target is occupied or belongs to another pool
Receive_Move
procedure Receive_Move
(Item : not null Channel_Access; Timeout : Duration := -1.0; Operation : in out Receive_Operation)
Start or restart an ownership-transferring receive.
Parameters
- Item
Aliased channel that outlives the operation
- Timeout
Relative deadline; negative waits indefinitely
- Operation
Fresh or consumed receive operation
Receive_Operation
type Receive_Operation is new Flyology.Operations.Operation with private;
First-class ownership-transferring receive operation.
Send_Move
function Send_Move
(Set : not null access Flyology.Operations.Completion_Set'Class;
Item : not null Channel_Access;
Value : in out Unique_Buffer;
Metadata : Transfer_Metadata := No_Metadata;
Timeout : Duration := -1.0) return Send_Operation
Start a send after moving Value into the operation. Value is vacant on return. Success transfers the token to the channel; typed Finish returns it only for timeout, close, cancellation, or driver failure.
Parameters
- Set
Completion set that owns the operation slot
- Item
Aliased channel that outlives the operation
- Value
Acquired buffer whose ownership transfers
- Metadata
Scalar metadata transferred on success
- Timeout
Relative deadline; negative waits indefinitely
Return value
Started limited send operation
Send_Move
procedure Send_Move
(Item : in out Channel; Value : in out Unique_Buffer; Metadata : Transfer_Metadata := No_Metadata)
Append Value, waiting while the open channel is full. Success leaves Value vacant. Close before acceptance raises and preserves Value.
Parameters
- Item
Channel receiving ownership
- Value
Acquired buffer from Item's pool
- Metadata
Scalar metadata transferred with Value
Raised exceptions
- Channel_Closed
Close occurs before acceptance
- Program_Error
Value is vacant or belongs to another pool
Send_Move
procedure Send_Move
(Item : not null Channel_Access;
Value : in out Unique_Buffer;
Metadata : Transfer_Metadata := No_Metadata;
Timeout : Duration := -1.0;
Operation : in out Send_Operation)
Start or restart an ownership-transferring send.
Parameters
- Item
Aliased channel that outlives the operation
- Value
Acquired buffer whose ownership transfers
- Metadata
Scalar metadata transferred on success
- Timeout
Relative deadline; negative waits indefinitely
- Operation
Fresh or consumed send operation
Send_Operation
type Send_Operation is new Flyology.Operations.Operation with private;
First-class ownership-transferring send operation.
Snapshot
type Snapshot is record
Closed : Boolean;
Pending : Natural;
Waiting_Senders : Natural;
Waiting_Receivers : Natural;
end record;
One coherent channel-state snapshot.
Record fields
- Closed
Whether Close has been called
- Pending
Number of buffer tokens currently queued
- Waiting_Senders
Number of callers queued for capacity
- Waiting_Receivers
Number of callers queued for a buffer
Timed_Receive_Move
procedure Timed_Receive_Move (Item : in out Channel; Target : in out Unique_Buffer; Timeout : Duration)
Receive within one relative deadline. Negative Timeout waits without a deadline; zero is an immediate attempt. Timeout leaves Target vacant.
Parameters
- Item
Channel yielding ownership
- Target
Vacant buffer that receives ownership on success
- Timeout
Maximum monotonic wait in seconds
Raised exceptions
- Channel_Closed
Closed channel has fully drained
- Timeout_Error
No buffer arrives before the deadline
- Program_Error
Target is occupied or belongs to another pool
Timed_Receive_Move
procedure Timed_Receive_Move
(Item : in out Channel;
Target : in out Unique_Buffer;
Timeout : Duration;
Token : access Flyology.Cancellation.Token)
Receive within one relative deadline or until Token is requested. Cancellation leaves Target vacant unless delivery completed first.
Parameters
- Item
Channel yielding ownership
- Target
Vacant buffer that receives the oldest payload
- Timeout
Maximum monotonic wait in seconds
- Token
Optional one-shot cancellation source
Raised exceptions
- Channel_Closed
Closed channel has fully drained
- Timeout_Error
No buffer arrives before the deadline
- Operation_Cancelled
Token is requested before delivery
- Program_Error
Target is occupied or belongs to another pool
Timed_Receive_Move
procedure Timed_Receive_Move
(Item : in out Channel;
Target : in out Unique_Buffer;
Timeout : Duration;
Metadata : out Transfer_Metadata)
Receive within one relative deadline and return channel-local metadata.
Parameters
- Item
Channel yielding ownership
- Target
Vacant buffer that receives ownership on success
- Timeout
Maximum monotonic wait in seconds
- Metadata
Metadata supplied by the sender
Raised exceptions
- Channel_Closed
Closed channel has fully drained
- Timeout_Error
No buffer arrives before the deadline
- Program_Error
Target is occupied or belongs to another pool
Timed_Receive_Move
procedure Timed_Receive_Move
(Item : in out Channel;
Target : in out Unique_Buffer;
Timeout : Duration;
Metadata : out Transfer_Metadata;
Token : access Flyology.Cancellation.Token)
Receive a buffer and metadata within a deadline or until cancellation. Ownership and exception semantics match the overload without metadata.
Parameters
- Item
Channel yielding ownership
- Target
Vacant buffer that receives the oldest payload
- Timeout
Maximum monotonic wait in seconds
- Metadata
Metadata supplied by the sender. A cancellation observed after delivery completed leaves it unassigned
- Token
Optional one-shot cancellation source
Raised exceptions
- Channel_Closed
Closed channel has fully drained
- Timeout_Error
No buffer arrives before the deadline
- Operation_Cancelled
Token is requested before delivery
- Program_Error
Target is occupied or belongs to another pool
Timed_Send_Move
procedure Timed_Send_Move
(Item : in out Channel;
Value : in out Unique_Buffer;
Timeout : Duration;
Metadata : Transfer_Metadata := No_Metadata)
Append Value within one relative deadline. Negative Timeout waits indefinitely; zero is an immediate attempt. Timeout and close preserve Value.
Parameters
- Item
Channel receiving ownership
- Value
Acquired buffer from Item's pool
- Timeout
Maximum monotonic wait in seconds
- Metadata
Scalar metadata transferred with Value
Raised exceptions
- Channel_Closed
Close occurs before acceptance
- Timeout_Error
Capacity remains unavailable until the deadline
- Program_Error
Value is vacant or belongs to another pool
Timeout_Error
Timeout_Error : exception;
Raised by a timed send or receive whose deadline expires first.
Transfer_Metadata
type Transfer_Metadata is mod 2**64;
Distinct 64-bit scalar metadata transferred atomically with a buffer token. This value is channel-local and does not alter the buffer's application Tag. Callers define and validate their own encoding.
Try_Receive_Move
procedure Try_Receive_Move
(Item : in out Channel; Target : in out Unique_Buffer; Result : out Try_Receive_Result)
Attempt to receive without waiting. Target becomes acquired only for Item_Received.
Parameters
- Item
Channel yielding ownership
- Target
Vacant buffer that receives ownership on success
- Result
Receive outcome
Raised exceptions
- Program_Error
Target is occupied or belongs to another pool
Try_Receive_Move
procedure Try_Receive_Move
(Item : in out Channel;
Target : in out Unique_Buffer;
Result : out Try_Receive_Result;
Metadata : out Transfer_Metadata)
Attempt to receive without waiting and return channel-local metadata only when a buffer is received.
Parameters
- Item
Channel yielding ownership
- Target
Vacant buffer that receives ownership on success
- Result
Receive outcome
- Metadata
Sender metadata, or No_Metadata when no buffer is received; No_Metadata is not a presence indicator
Raised exceptions
- Program_Error
Target is occupied or belongs to another pool
Try_Receive_Result
type Try_Receive_Result is (Item_Received, Channel_Empty, Receive_Closed);
Result of a nonblocking receive attempt.
Enumeration literals
- Item_Received
Target received sole ownership
- Channel_Empty
No value was available from an open channel
- Receive_Closed
Closed channel has fully drained
Try_Send_Move
procedure Try_Send_Move
(Item : in out Channel;
Value : in out Unique_Buffer;
Result : out Try_Send_Result;
Metadata : Transfer_Metadata := No_Metadata)
Attempt to append without waiting. Value becomes vacant only for Item_Sent.
Parameters
- Item
Channel receiving ownership
- Value
Acquired buffer from Item's pool
- Result
Send outcome
- Metadata
Scalar metadata transferred with Value
Raised exceptions
- Program_Error
Value is vacant or belongs to another pool
Try_Send_Result
type Try_Send_Result is (Item_Sent, Channel_Full, Send_Closed);
Result of a nonblocking send attempt.
Enumeration literals
- Item_Sent
Ownership transferred to the channel
- Channel_Full
No capacity was available; sender retains ownership
- Send_Closed
Channel is closed; sender retains ownership