Description
Adds ownership, admission control, and cancellation to socket connections.
Example:
Flyology.IO.Connections.Connect (Manager, Server, 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 capacity admission, readiness, retries, and backoff. Negative is unlimited and zero is immediate. Token cancellation and Manager shutdown interrupt a full-capacity admission wait without polling. 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. On failure after admission, cleanup independently releases the permit and attempts to close any accepted socket. If admission readiness signalling fails, the permit remains released. Ada finalization rules determine the observable exception occurrence when that cleanup failure accompanies a timeout, cancellation, socket failure, or another exception.
Parameters
- Manager
Admission controller that must outlive Item, and that must be Item's Manager discriminant when Item has one
- 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 closes a pending admission
- Operation_Cancelled
Token interrupts admission; Manager shutdown or Token interrupts the admitted accept
- Timeout_Error
The accept deadline expires
- Device_Error
Readiness polling fails
- Socket_Error
Flyology.IO.Sockets.Socket_Error is raised when accept or setup fails
- Program_Error
Item is open, Item is bound to a different Manager, a wake source cannot be created, or cleanup releases its permit but cannot signal admission readiness
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
- Socket_Error
Flyology.IO.Sockets.Socket_Error is raised when the underlying close reports failure
- TLS_Error
Flyology.IO.TLS.TLS_Error is raised when an upgraded provider session violates its non-raising finalization contract; cleanup still completes
- Program_Error
The Server permit is released but admission readiness cannot be signalled
Connect
function Connect
(Set : not null access Flyology.Operations.Completion_Set'Class;
Manager : not null access Server;
Server : Flyology.IO.Sockets.Endpoint;
Timeout : Duration := Infinite;
Token : access Cancellation_Token := null) return Connect_Operation
Start one managed connection without suspending the owner task.
Parameters
- Set
Completion set with room for the parent and hidden child
- Manager
Admission controller that outlives the operation
- Server
Destination endpoint copied into the operation
- Timeout
Shared admission-and-connect deadline in seconds
- Token
Optional cancellation source that outlives the operation
Return value
Started limited managed connect operation
Connect
procedure Connect
(Manager : aliased in out Server;
Server : Flyology.IO.Sockets.Endpoint;
Item : in out Connection;
Timeout : Duration := Infinite;
Token : access Cancellation_Token := null)
Reserve one Manager permit, create an Internet stream socket for Server's address family, connect it, and transfer sole closing ownership to Item. One monotonic Timeout spans admission, socket creation, and the task-aware connection attempt. Negative is unlimited and zero is immediate. Manager shutdown closes a pending admission with Admission_Closed; after admission, shutdown and Token cancellation interrupt the connection attempt with Operation_Cancelled. Lightweight tasks suspend; native tasks block only their pthreads.
On every failure before adoption, cleanup releases the permit and closes any created socket. If admission readiness signalling fails, the permit remains released. Ada finalization rules determine the observable exception occurrence when that cleanup failure accompanies a timeout, cancellation, socket failure, or another exception.
Parameters
- Manager
Admission controller that must outlive Item, and that must be Item's Manager discriminant when Item has one
- Server
Destination endpoint
- Item
Closed Connection that receives the connected socket
- Timeout
Shared admission-and-connect deadline in seconds
- Token
Optional one-shot cancellation source that must outlive the call
Raised exceptions
- Admission_Closed
Manager closes a pending admission
- Operation_Cancelled
Manager shutdown or Token interrupts an admitted connection attempt
- Timeout_Error
The shared deadline expires
- Device_Error
Readiness polling fails
- Socket_Error
Flyology.IO.Sockets.Socket_Error is raised when socket creation, connection, or setup fails
- Program_Error
Item is open, Item is bound to a different Manager, a wake source cannot be created, or cleanup releases its permit but cannot signal admission readiness
Connect
procedure Connect
(Manager : not null access Server;
Server : Flyology.IO.Sockets.Endpoint;
Timeout : Duration := Infinite;
Token : access Cancellation_Token := null;
Operation : in out Connect_Operation)
Start or restart managed connection construction in an established operation object.
Parameters
- Manager
Admission controller that outlives the operation
- Server
Destination endpoint copied into the operation
- Timeout
Shared admission-and-connect deadline in seconds
- Token
Optional cancellation source that outlives the operation
- Operation
Fresh, released, or consumed managed connect operation
Connect_Operation
type Connect_Operation (Owner : not null access Flyology.Operations.Completion_Set'Class) is
new Flyology.Operations.Operation (Owner)
with record
State : Connect_Operation_State (Owner);
end record;
Scoped managed connection construction. The operation reserves one Manager permit, owns its temporary socket, and composes the raw socket connection attempt as a hidden child. It does not borrow a Connection; typed Finish transfers both resources into a caller-selected closed target. Manager and Token must outlive the operation.
The parent and its hidden child temporarily consume two completion-set slots while the socket is connecting. Admission waiting and a retained successful result consume only the parent's slot.
Record fields
- Owner
Completion set that owns the parent and hidden child slots
- State
Opaque build-in-place child and ownership storage
Connect_Operation_State
type Connect_Operation_State (Owner : not null access Flyology.Operations.Completion_Set'Class) is
limited private;
Opaque build-in-place storage for a managed connect's child operation. @exclude
Record fields
- Owner
Completion set shared with the child operation
Connection
type Connection
(Manager : access Server := null)
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. The TLS child may replace the plaintext transport in place without changing this ownership.
An admitted Connection borrows its Server for as long as it owns a socket: every operation, Close, and Finalize call into that Server, so the Server must outlive the Connection. Supply the borrowed Server as the Manager discriminant to have the compiler enforce that rule
Gate : aliased Flyology.IO.Connections.Server (Capacity => 64);
Item : Flyology.IO.Connections.Connection (Gate'Access);
because an access discriminant may not designate an object of a shorter-lived scope than the object it discriminates. Take and Accept_Connection then reject any other Manager. The default null discriminant keeps older declarations compiling, but leaves the lifetime rule unchecked: a Connection that outlives the Server it was admitted through has no defined behavior.
Connection_Operation
type Connection_Operation is abstract new Flyology.Operations.Operation with private;
Common limited base for scoped high-level connection I/O. Each operation retains one generation-checked exclusive connection lease, transparently driving either the plaintext socket or upgraded TLS provider. Item, Token, and the borrowed buffer must outlive it. The owning task must finish or cancel and drain its pending scoped operations before it calls synchronous Close; Close may wait for those operations, while only their owner can drive them to completion.
Finish
procedure Finish (Operation : in out Connect_Operation; Item : in out Connection'Class)
Consume a terminal managed connect. On success, transfer the operation's socket and permit to Item. A mismatched or open Item raises Program_Error without consuming the result, so Finish can be retried with a valid target. Failed and cancelled outcomes leave Item unchanged.
Parameters
- Operation
Terminal managed connection attempt
- Item
Closed Connection that is unbound or bound to Manager
Raised exceptions
- Admission_Closed
Manager closed before admission
- Operation_Cancelled
Explicit cancellation, Token, or Manager shutdown interrupted an admitted attempt
- Timeout_Error
The shared deadline expired
- Socket_Error
Socket creation or connection failed
- Capacity_Error
Completion-set child capacity was unavailable
- Program_Error
Item is open or bound to another Manager, or cleanup failed
Finish
procedure Finish (Operation : in out Receive_Exactly_Operation)
Consume a terminal exact receive.
Parameters
- Operation
Terminal exact-receive operation
Finish
procedure Finish (Operation : in out Receive_Operation; Last : out Ada.Streams.Stream_Element_Offset)
Consume a terminal receive and publish the familiar Last result.
Parameters
- Operation
Terminal receive operation
- Last
Last element received, or Data'First - 1 on peer closure
Finish
procedure Finish (Operation : in out Send_All_Operation)
Consume a terminal complete send.
Parameters
- Operation
Terminal send operation
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
function Receive
(Set : not null access Flyology.Operations.Completion_Set'Class;
Item : not null access Connection'Class;
Data : not null access Ada.Streams.Stream_Element_Array;
Timeout : Duration := Infinite;
Token : access Cancellation_Token := null) return Receive_Operation
Start one high-level receive without suspending the owner. The operation acquires Item's lease asynchronously and borrows Data until typed Finish or finalization.
Parameters
- Set
Completion set that owns the operation slot
- Item
Open admitted plaintext or TLS connection
- Data
Aliased destination buffer
- Timeout
Shared lease-and-I/O deadline
- Token
Optional cancellation source that outlives the operation
Return value
Started limited receive operation
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
- TLS_Error
Flyology.IO.TLS.TLS_Error is raised when an upgraded provider fails or returns invalid progress
- Socket_Error
Flyology.IO.Sockets.Socket_Error is raised when receive or setup fails
- Program_Error
Item is already closed when the call starts, or a wake source cannot be used
Receive
procedure Receive
(Item : not null access Connection'Class;
Data : not null access Ada.Streams.Stream_Element_Array;
Timeout : Duration := Infinite;
Token : access Cancellation_Token := null;
Operation : in out Receive_Operation)
Start or restart a receive in an established operation object.
Parameters
- Item
Open admitted plaintext or TLS connection
- Data
Aliased destination buffer
- Timeout
Shared lease-and-I/O deadline
- Token
Optional cancellation source that outlives the operation
- Operation
Fresh, released, or consumed receive operation
Receive_Exactly
function Receive_Exactly
(Set : not null access Flyology.Operations.Completion_Set'Class;
Item : not null access Connection'Class;
Data : not null access Ada.Streams.Stream_Element_Array;
Timeout : Duration := Infinite;
Token : access Cancellation_Token := null) return Receive_Exactly_Operation
Start a high-level receive that fills Data.
Parameters
- Set
Completion set that owns the operation slot
- Item
Open admitted plaintext or TLS connection
- Data
Aliased destination buffer to fill
- Timeout
Shared lease-and-I/O deadline
- Token
Optional cancellation source that outlives the operation
Return value
Started limited exact-receive operation
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
- TLS_Error
Flyology.IO.TLS.TLS_Error is raised when an upgraded provider fails, closes early, or returns invalid progress
- Socket_Error
Flyology.IO.Sockets.Socket_Error is raised when 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 : not null access Connection'Class;
Data : not null access Ada.Streams.Stream_Element_Array;
Timeout : Duration := Infinite;
Token : access Cancellation_Token := null;
Operation : in out Receive_Exactly_Operation)
Start or restart an exact receive.
Parameters
- Item
Open admitted plaintext or TLS connection
- Data
Aliased destination buffer to fill
- Timeout
Shared lease-and-I/O deadline
- Token
Optional cancellation source that outlives the operation
- Operation
Fresh, released, or consumed exact-receive operation
Receive_Exactly_Operation
type Receive_Exactly_Operation is new Connection_Operation with private;
Scoped plaintext-or-TLS receive that fills its array.
Receive_Operation
type Receive_Operation is new Connection_Operation with private;
Scoped one-chunk plaintext-or-TLS receive.
Send_All
function Send_All
(Set : not null access Flyology.Operations.Completion_Set'Class;
Item : not null access Connection'Class;
Data : not null access constant Ada.Streams.Stream_Element_Array;
Timeout : Duration := Infinite;
Token : access Cancellation_Token := null) return Send_All_Operation
Start a high-level complete send.
Parameters
- Set
Completion set that owns the operation slot
- Item
Open admitted plaintext or TLS connection
- Data
Aliased source buffer borrowed read-only
- Timeout
Shared lease-and-I/O deadline
- Token
Optional cancellation source that outlives the operation
Return value
Started limited complete-send operation
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
- TLS_Error
Flyology.IO.TLS.TLS_Error is raised when an upgraded provider or peer fails, or the provider returns invalid progress
- Socket_Error
Flyology.IO.Sockets.Socket_Error is raised when socket send 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 : not null access Connection'Class;
Data : not null access constant Ada.Streams.Stream_Element_Array;
Timeout : Duration := Infinite;
Token : access Cancellation_Token := null;
Operation : in out Send_All_Operation)
Start or restart a complete send.
Parameters
- Item
Open admitted plaintext or TLS connection
- Data
Aliased source buffer borrowed read-only
- Timeout
Shared lease-and-I/O deadline
- Token
Optional cancellation source that outlives the operation
- Operation
Fresh, released, or consumed complete-send operation
Send_All_Operation
type Send_All_Operation is new Connection_Operation with private;
Scoped plaintext-or-TLS complete send.
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)
Wait indefinitely for one Manager permit, then transfer Socket to Item. This compatibility operation has no timeout or cancellation token; Manager shutdown releases its admission wait with Admission_Closed. On success Socket is closed and Item is the sole closing owner. If an unsuccessful transfer releases its permit but admission readiness signalling fails, the permit remains released and Socket remains owned by the caller. Ada finalization rules determine the observable exception occurrence when that cleanup failure accompanies another exception.
Parameters
- Manager
Admission controller that must outlive Item, and that must be Item's Manager discriminant when Item has one
- 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, Item is bound to a different Manager, wake setup fails, or failed-transfer cleanup releases its permit but cannot signal admission readiness