Description
Adds ownership, admission control, and cancellation to socket connections.
Example:
Flyology.IO.Connections.Take (Manager, Socket, Client);
Accept_Connection
procedure Accept_Connection
(Manager : aliased in out Server;
Listener : Flyology.IO.Sockets.Socket_Type;
Item : in out Connection;
Address : out Flyology.IO.Sockets.Endpoint;
Timeout : Duration := Infinite;
Cancellation_Quantum : Duration := 0.050;
Token : access Cancellation_Token := null)
Acquire capacity before accepting, so a full Manager backpressures the listening socket. Transient aborted admissions are retried; descriptor exhaustion uses interruptible bounded backoff. One Timeout deadline spans readiness, retries, and backoff. Negative is unlimited and zero is immediate. Cancellation_Quantum must be positive for compatibility but is ignored; wake-source readiness notices cancellation without periodic polling. Lightweight tasks suspend; native tasks block their threads.
Parameters
- Manager
Admission controller that must outlive Item
- Listener
Open listening socket; ownership is retained
- Item
Closed Connection that receives the accepted socket
- Address
Accepted peer address
- Timeout
Deadline interval in seconds
- Cancellation_Quantum
Compatibility parameter; value is ignored
- Token
Optional one-shot cancellation source that must outlive the call
Raised exceptions
- Admission_Closed
Manager has closed admission before reserve
- Operation_Cancelled
Shutdown or Token interrupts the accept
- Timeout_Error
The accept deadline expires
- Device_Error
Readiness polling fails
- Flyology
.IO.Sockets.Socket_Error Accept or setup fails
- Program_Error
Item is open or a wake source cannot be created
Admission_Closed
Admission_Closed : exception;
Raised when a Server no longer admits connections.
Cancellation_Token
subtype Cancellation_Token is Flyology.Cancellation.Token;
Canonical thread-safe one-shot cancellation source. Request is idempotent. The token must outlive every operation using it.
Close
procedure Close (Item : in out Connection)
Cancel and drain the active operation and every registered or queued caller, close Item's socket, and release its Server permit. Concurrent Close callers wait for the same close. Closing a closed Item is harmless.
Parameters
- Item
Connection whose ownership is released
Raised exceptions
- Flyology
.IO.Sockets.Socket_Error The underlying close reports failure
Connection
type Connection is new Ada.Finalization.Limited_Controlled with private;
Sole closing owner of one socket and one Server admission permit. Finalize calls Close. At most one I/O operation holds the active lease, while multiple callers may be registered or queued for it. Close is idempotent and may run concurrently with all of them: it cancels and drains the active operation and every registered or queued operation before closing the socket. Server must outlive the Connection.
Is_Open
function Is_Open (Item : Connection) return Boolean
Query the protected ownership state.
Parameters
- Item
Connection to inspect
Return value
True while Item owns a socket and is not closing
Operation_Cancelled
Operation_Cancelled : exception renames
Flyology.Cancellation.Operation_Cancelled;
Raised when server shutdown, an explicit token, or concurrent Close interrupts an operation. This is the canonical cross-I/O exception.
Receive
procedure Receive
(Item : in out Connection;
Data : out Ada.Streams.Stream_Element_Array;
Last : out Ada.Streams.Stream_Element_Offset;
Timeout : Duration := Infinite;
Cancellation_Quantum : Duration := 0.050;
Token : access Cancellation_Token := null)
Receive one chunk under Item's exclusive operation lease. Timeout and lane behavior match Accept_Connection. Cancellation_Quantum is ignored; Manager shutdown, Token, or concurrent Close wakes the operation.
Parameters
- Item
Open connection
- Data
Destination buffer
- Last
Last element received, or Data'First - 1 on orderly closure
- Timeout
Deadline interval in seconds
- Cancellation_Quantum
Compatibility parameter; value is ignored
- Token
Optional token that must outlive this call
Raised exceptions
- Operation_Cancelled
Shutdown, Token, or Close interrupts a call that started while Item was open
- Timeout_Error
The deadline expires
- Device_Error
Readiness polling fails
- Flyology
.IO.Sockets.Socket_Error Receive or setup fails
- Program_Error
Item is already closed when the call starts, or a wake source cannot be used
Receive_Exactly
procedure Receive_Exactly
(Item : in out Connection;
Data : out Ada.Streams.Stream_Element_Array;
Timeout : Duration := Infinite;
Cancellation_Quantum : Duration := 0.050;
Token : access Cancellation_Token := null)
Fill Data under one exclusive operation lease and one sequence-wide deadline. Cancellation and lane behavior match Receive.
Parameters
- Item
Open connection
- Data
Destination buffer to fill
- Timeout
Deadline interval in seconds
- Cancellation_Quantum
Compatibility parameter; value is ignored
- Token
Optional token that must outlive this call
Raised exceptions
- Operation_Cancelled
Shutdown, Token, or Close interrupts a call that started while Item was open
- Timeout_Error
The shared deadline expires
- Device_Error
Polling fails or the peer closes early
- Flyology
.IO.Sockets.Socket_Error Receive or setup fails
- Program_Error
Item is already closed when the call starts, or a wake source cannot be used
Send_All
procedure Send_All
(Item : in out Connection;
Data : Ada.Streams.Stream_Element_Array;
Timeout : Duration := Infinite;
Cancellation_Quantum : Duration := 0.050;
Token : access Cancellation_Token := null)
Send all Data under one exclusive operation lease and one deadline. Cancellation_Quantum is ignored; cancellation sources wake readiness.
Parameters
- Item
Open connection
- Data
Source buffer to send completely
- Timeout
Deadline interval in seconds
- Cancellation_Quantum
Compatibility parameter; value is ignored
- Token
Optional token that must outlive this call
Raised exceptions
- Operation_Cancelled
Shutdown, Token, or Close interrupts a call that started while Item was open
- Timeout_Error
The shared deadline expires
- Device_Error
Polling fails or no forward progress is made
- Flyology
.IO.Sockets.Socket_Error Socket send or setup fails
- Program_Error
Item is already closed when the call starts, or a wake source cannot be used
Server
subtype Server is Flyology.Capacity.Gate;
General bounded admission gate used for connection ownership. Existing Server declarations remain source-compatible; the implementation is shared with non-I/O capacity control through Flyology.Capacity.
Take
procedure Take
(Manager : aliased in out Server;
Socket : in out Flyology.IO.Sockets.Socket_Type;
Item : in out Connection)
Transfer Socket and one Manager permit to Item. On success Socket is closed and Item is the sole closing owner.
Parameters
- Manager
Admission controller that must outlive Item
- Socket
Open socket whose ownership transfers on success
- Item
Closed Connection that receives ownership
Raised exceptions
- Admission_Closed
Manager has started shutdown
- Program_Error
Socket or Item is invalid, or wake setup fails