Description
Gives one protocol pump bounded full-duplex access to an admitted connection without exposing its descriptor or transport ownership.
Acquisition_Result
type Acquisition_Result is (Acquired, Need_Acquire_Readiness);
Result of one nonblocking connection-lease acquisition step.
Enumeration literals
- Acquired
The capability may perform transport steps
- Need_Acquire_Readiness
Arm_Acquisition and retry after wakeup
Arm_Acquisition
procedure Arm_Acquisition (IO : in out Capability; Operation : in out Flyology.Operations.Operation'Class)
Arm the outer provider operation for connection lease availability and every applicable lifecycle source. The capability owns no set slot.
Parameters
- IO
Started capability awaiting its lease
- Operation
Outer user-visible provider operation
Raised exceptions
- Program_Error
IO is not awaiting acquisition
Arm_Deadline
procedure Arm_Deadline (IO : in out Capability; Operation : in out Flyology.Operations.Operation'Class)
Arm the outer provider operation with the unused portion of the shared Start deadline. An infinite deadline adds no timer source.
Parameters
- IO
Engaged capability
- Operation
Outer user-visible provider operation
Arm_Transport
procedure Arm_Transport
(IO : in out Capability; Operation : in out Flyology.Operations.Operation'Class; Required : Step_Result)
Arm the outer provider operation for the single readiness direction returned by Receive or Send, plus close, manager shutdown, and Token.
Parameters
- IO
Acquired capability
- Operation
Outer user-visible provider operation
- Required
Need_Read or Need_Write returned by a transport step
Raised exceptions
- Program_Error
IO is not acquired or Required is not a wait
Arm_Transport
procedure Arm_Transport
(IO : in out Capability;
Operation : in out Flyology.Operations.Operation'Class;
Required : Step_Result;
Outbound : in out Outbound_Wakeup)
Arm the outer provider operation for one transport direction, protocol output publication, close, manager shutdown, and Token in one bounded readiness set. Outbound remains opaque and consumes no completion-set slot. If a coalesced output notification is already pending, it is consumed and Operation is rescheduled instead of armed. Arm_Deadline may be used independently on the same Operation.
Parameters
- IO
Acquired capability
- Operation
Outer user-visible provider operation
- Required
Need_Read or Need_Write returned by a transport step
- Outbound
Reusable protocol-output notification
Raised exceptions
- Program_Error
IO is not acquired or Required is not a wait result, or wake descriptor creation or consumption fails
Arm_Transport
procedure Arm_Transport
(IO : in out Capability;
Operation : in out Flyology.Operations.Operation'Class;
Required : Step_Result;
Outbound : in out Outbound_Wakeup;
Additional : Flyology.IO.Descriptor;
Additional_For_Write : Boolean)
Arm the outer provider operation for one transport direction, protocol output publication, one caller-borrowed latched descriptor, close, manager shutdown, and Token in one bounded readiness set. Outbound retains its consume-before-reschedule rule; Additional is never consumed by this call. Arm_Deadline may be used independently on Operation. The caller owns Additional and disarms its borrow after wakeup before querying or releasing its source again.
Parameters
- IO
Acquired capability
- Operation
Outer user-visible provider operation
- Required
Need_Read or Need_Write returned by a transport step
- Outbound
Reusable protocol-output notification
- Additional
Valid caller-borrowed latched descriptor
- Additional_For_Write
True to observe Additional write readiness
Raised exceptions
- Program_Error
IO is not acquired, Required is not a wait result, Additional is invalid, or wake preparation fails
Arm_Transport
procedure Arm_Transport
(IO : in out Capability;
Operation : in out Flyology.Operations.Operation'Class;
Required : Step_Result;
Additional : Flyology.IO.Descriptor;
Additional_For_Write : Boolean)
Arm the outer provider operation for one transport direction, one caller-borrowed latched descriptor, close, manager shutdown, and Token in one bounded readiness set. Arm_Deadline may be used independently on the same Operation. The caller owns Additional and disarms its borrow after wakeup before querying or releasing its source again.
Parameters
- IO
Acquired capability
- Operation
Outer user-visible provider operation
- Required
Need_Read or Need_Write returned by a transport step
- Additional
Valid caller-borrowed latched descriptor
- Additional_For_Write
True to observe Additional write readiness
Raised exceptions
- Program_Error
IO is not acquired, Required is not a wait result, or Additional is invalid
Cancel
procedure Cancel (IO : in out Capability)
Cancellation has the same ownership transition as Release; the outer provider chooses and publishes its own terminal cancellation outcome.
Parameters
- IO
Capability whose connection borrow is discharged
Capability
type Capability is new Ada.Finalization.Limited_Controlled with private;
Set-independent connection driver state. A higher-level protocol may store one Capability in its concrete transport adapter while its outer operation owns the only completion-set slot. The capability is limited, reusable after Release, and allocation-free. It never exposes the connection descriptor or TLS provider session.
Duplex_Interest
Duplex_Interest : constant Readiness_Interest := (Readable => True, Writable => True);
Wait for both transport directions.
Is_Acquired
function Is_Acquired (IO : Capability) return Boolean
Report whether IO currently owns the connection operation lease.
Parameters
- IO
Capability to inspect
Return value
True when transport steps are permitted
Is_Engaged
function Is_Engaged (IO : Capability) return Boolean
Report whether IO retains a registered or acquired connection borrow.
Parameters
- IO
Capability to inspect
Return value
True until Release, Cancel, or finalization completes
Outbound_Wakeup
type Outbound_Wakeup is limited private;
Thread-safe, reusable protocol-output notification. It owns its wake descriptor and never exposes it. Signals coalesce until Wait or the composable Arm_Transport overload consumes them. The object must outlive every operation, Run call, and task that can use it.
Poll_Acquisition
procedure Poll_Acquisition (IO : in out Capability; Result : out Acquisition_Result)
Retry one lease acquisition after its armed source becomes ready.
Parameters
- IO
Started capability awaiting the connection lease
- Result
Immediate lease result
Raised exceptions
- Operation_Cancelled
Shutdown, Token, or Close is active
- Socket_Error
Socket preparation fails after acquisition
- Program_Error
IO is fresh, released, or already acquired
Protocol_Only
Protocol_Only : constant Readiness_Interest := (Readable => False, Writable => False);
Wait only for a protocol wakeup or lifecycle cancellation.
Read_Interest
Read_Interest : constant Readiness_Interest := (Readable => True, Writable => False);
Wait for inbound or TLS read progress.
Readiness_Interest
type Readiness_Interest is record
Readable : Boolean := True;
Writable : Boolean := False;
end record;
Transport conditions to include in one Wait call. The outbound protocol wakeup and lifecycle cancellation sources are always included.
Record fields
- Readable
Observe descriptor read readiness
- Writable
Observe descriptor write readiness
Receive
procedure Receive
(Item : in out Capability;
Data : out Ada.Streams.Stream_Element_Array;
Last : out Ada.Streams.Stream_Element_Offset;
Result : out Step_Result)
Attempt one immediate receive step. At most one plaintext socket call or TLS provider step is made. No readiness wait occurs. Unless Result is Made_Progress with nonempty Data, Last is one less than Data'First. TLS may report Need_Write; plaintext reports Need_Read when it would block.
Parameters
- Item
Active scoped capability
- Data
Destination buffer for one bounded step
- Last
Last element received, or Data'First - 1 without progress
- Result
Progress, required readiness, or orderly peer closure
Raised exceptions
- Operation_Cancelled
Shutdown, token cancellation, or Close interrupts the driver
- Timeout_Error
Flyology.IO.Timeout_Error is raised when the shared Start deadline expires
- TLS_Error
Flyology.IO.TLS.TLS_Error is raised when the TLS provider fails or reports invalid progress
- Socket_Error
Flyology.IO.Sockets.Socket_Error is raised when plaintext receive fails
Release
procedure Release (IO : in out Capability)
Release or abandon the connection lease and every retained borrow. Call this before publishing the outer operation's terminal outcome. Repeating Release on a released capability is harmless.
Parameters
- IO
Capability whose connection borrow is discharged
Run
procedure Run
(Item : in out Connection;
Process : not null access procedure (IO : in out Capability);
Timeout : Duration := Infinite;
Token : access Cancellation_Token := null)
Hold Item's exclusive operation lease while Process drives both transport directions through a scoped Capability. One deadline includes lease acquisition and every capability call. Provider calls and Process itself are synchronous and are not preempted; expiration is observed at the next capability boundary. If Process returns, raises, or is aborted, the socket and admission permit remain owned by Item. Concurrent Close waits for that restoration before closing the descriptor and releasing admission. Process is invoked only during Run and must not let an access to Capability escape.
Parameters
- Item
Open admitted plaintext or TLS connection
- Process
Protocol pump callback invoked once under the lease
- Timeout
Shared driver deadline in seconds
- Token
Optional one-shot token that must outlive Run
Raised exceptions
- Operation_Cancelled
Shutdown, token cancellation, or Close interrupts lease acquisition or the driver
- Timeout_Error
Flyology.IO.Timeout_Error is raised when the shared deadline expires
- Socket_Error
Flyology.IO.Sockets.Socket_Error is raised when socket preparation fails
- Program_Error
Item is closed or transport state is invalid
Send
procedure Send
(Item : in out Capability;
Data : Ada.Streams.Stream_Element_Array;
Last : out Ada.Streams.Stream_Element_Offset;
Result : out Step_Result)
Attempt one immediate send step. At most one plaintext socket call or TLS provider step is made. No readiness wait occurs. Unless Result is Made_Progress with nonempty Data, Last is one less than Data'First. TLS may report Need_Read; plaintext reports Need_Write when it would block. After TLS reports Need_Read or Need_Write, retry with the identical Data slice, including its bounds and contents; only its address may differ.
Parameters
- Item
Active scoped capability
- Data
Source buffer for one bounded step
- Last
Last element sent, or Data'First - 1 without progress
- Result
Progress, required readiness, or peer closure
Raised exceptions
- Operation_Cancelled
Shutdown, token cancellation, or Close interrupts the driver
- Timeout_Error
Flyology.IO.Timeout_Error is raised when the shared Start deadline expires
- TLS_Error
Flyology.IO.TLS.TLS_Error is raised when the TLS provider fails or reports invalid progress
- Socket_Error
Flyology.IO.Sockets.Socket_Error is raised when plaintext send fails
Signal
procedure Signal (Item : in out Outbound_Wakeup)
Publish protocol output availability. Publish the protected queue state before calling Signal. After Outbound_Ready, the driver must observe all currently published work before waiting again because signals coalesce.
Parameters
- Item
Wakeup owned by the protocol driver
Raised exceptions
- Program_Error
Wake descriptor creation or signaling fails; the notification remains pending and a later Wait still observes it
Start
procedure Start
(IO : in out Capability;
Item : not null access Connection'Class;
Result : out Acquisition_Result;
Timeout : Duration := Infinite;
Token : access Cancellation_Token := null)
Start borrowing Item for a higher-level operation and attempt its lease once. Capability must be fresh or released. No wait occurs. Item and Token remain borrowed until Release or finalization.
Parameters
- IO
Fresh or released set-independent capability
- Item
Open admitted plaintext or TLS connection
- Result
Immediate lease result
- Timeout
Shared acquisition and transport deadline
- Token
Optional cancellation source that outlives the capability
Raised exceptions
- Operation_Cancelled
Shutdown, Token, or Close is active
- Socket_Error
Socket preparation fails after acquisition
- Program_Error
IO is active or Item is closed
Step_Result
type Step_Result is (Made_Progress, Need_Read, Need_Write, Peer_Closed);
Result of one bounded transport step.
Enumeration literals
- Made_Progress
At least one byte was transferred, or the input was empty
- Need_Read
The next provider or socket step needs read readiness
- Need_Write
The next provider or socket step needs write readiness
- Peer_Closed
The peer ended the applicable transport direction
Wait
procedure Wait
(Item : in out Capability;
Outbound : in out Outbound_Wakeup;
Interest : Readiness_Interest := Read_Interest;
Timeout : Duration := Infinite;
Result : out Wait_Result)
Suspend until a requested transport condition or Outbound is ready. Close, Manager shutdown, and token cancellation wake the call and raise Operation_Cancelled. Timeout bounds this wait and is also capped by the shared Run deadline. A negative value waits until either limit; zero is an immediate poll. Lightweight tasks suspend on their event loop and native tasks block only their pthread.
Parameters
- Item
Active scoped capability
- Outbound
Reusable protocol-output notification
- Interest
Transport readiness conditions to observe
- Timeout
Maximum interval for this wait in seconds
- Result
Transport, protocol, or per-wait timeout result
Raised exceptions
- Operation_Cancelled
Shutdown, token cancellation, or Close interrupts the driver
- Timeout_Error
Flyology.IO.Timeout_Error is raised when Run's shared deadline expires
- Device_Error
Flyology.IO.Device_Error is raised when readiness polling fails
- Program_Error
Wake descriptor creation or consumption fails
Wait_Result
type Wait_Result is (Transport_Ready, Outbound_Ready, Wait_Timed_Out);
Reason one capability wait returned.
Enumeration literals
- Transport_Ready
One requested descriptor condition is ready
- Outbound_Ready
A coalesced protocol wakeup was consumed
- Wait_Timed_Out
The per-wait timeout expired before Run's deadline
Write_Interest
Write_Interest : constant Readiness_Interest := (Readable => False, Writable => True);
Wait for outbound or TLS write progress.