Description
Bounded, set-independent access to one standalone TLS connection lease. Higher-level protocol operations store a Capability while owning the only completion-set slot themselves.
Acquisition_Result
type Acquisition_Result is (Acquired, Need_Acquire_Readiness);
Result of one nonblocking TLS connection-lease acquisition step.
Enumeration literals
- Acquired
The capability may perform provider 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 an outer operation for lease availability, close, and cancellation.
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)
Add the unused portion of Start's shared deadline to an outer operation. A higher-level provider must call this once after Start; provider steps themselves do not inspect time because the outer operation owns the Deadline_Reached transition.
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 an outer operation for the readiness direction returned by a step, plus close and cancellation.
Parameters
- IO
Acquired capability
- Operation
Outer user-visible provider operation
- Required
Need_Read or Need_Write returned by a provider step
Raised exceptions
- Program_Error
IO is not acquired or Required is not a wait
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 TLS connection borrow is discharged
Capability
type Capability is new Ada.Finalization.Limited_Controlled with private;
Set-independent standalone TLS driver state. A higher-level protocol may store one Capability while its outer operation owns the only completion-set slot. The capability is limited, reusable after Release, and allocation-free. It never exposes the descriptor or provider session.
Handshake
procedure Handshake (IO : in out Capability; Result : out Step_Result)
Perform one bounded provider handshake step.
Parameters
- IO
Acquired capability
- Result
Progress, required readiness, or peer closure
Raised exceptions
- Operation_Cancelled
Token or Close interrupts the driver
- TLS_Error
The provider fails or reports invalid progress
Is_Acquired
function Is_Acquired (IO : Capability) return Boolean
Report whether IO currently owns the TLS connection operation lease.
Parameters
- IO
Capability to inspect
Return value
True when provider 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
Poll_Acquisition
procedure Poll_Acquisition (IO : in out Capability; Result : out Acquisition_Result)
Retry one lease acquisition after Arm_Acquisition becomes ready.
Parameters
- IO
Started capability awaiting the TLS connection lease
- Result
Immediate lease result
Raised exceptions
- Operation_Cancelled
Token or Close is active
- Timeout_Error
The lease remains busy at the shared deadline
- Program_Error
IO is fresh, released, or already acquired
Receive
procedure Receive
(IO : in out Capability;
Data : out Ada.Streams.Stream_Element_Array;
Last : out Ada.Streams.Stream_Element_Offset;
Result : out Step_Result)
Perform one bounded decrypted receive step.
Parameters
- IO
Acquired 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
Token or Close interrupts the driver
- TLS_Error
The provider fails or reports invalid progress
Release
procedure Release (IO : in out Capability)
Discharge the lease or registration and every retained borrow.
Parameters
- IO
Capability whose TLS connection borrow is discharged
Send
procedure Send
(IO : in out Capability;
Data : Ada.Streams.Stream_Element_Array;
Last : out Ada.Streams.Stream_Element_Offset;
Result : out Step_Result)
Perform one bounded encrypted send step. Need_Read and Need_Write consume no bytes and set Last to one less than Data'First. Retry either result with the identical Data slice, including its bounds and contents; only its address may differ. Empty Data makes progress without sending bytes.
Parameters
- IO
Acquired 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
Token or Close interrupts the driver
- TLS_Error
The provider fails or reports invalid progress
Shutdown
procedure Shutdown (IO : in out Capability; Result : out Step_Result)
Perform one bounded close-notify step.
Parameters
- IO
Acquired capability
- Result
Progress, required readiness, or peer closure
Raised exceptions
- Operation_Cancelled
Token or Close interrupts the driver
- TLS_Error
The provider fails or reports invalid progress
Start
procedure Start
(IO : in out Capability;
Item : not null access Connection'Class;
Result : out Acquisition_Result;
Timeout : Duration := Infinite;
Token : access Flyology.Cancellation.Token := null)
Register Item and attempt its exclusive provider lease once. Item and Token remain borrowed until Release or finalization.
Parameters
- IO
Fresh or released set-independent capability
- Item
Open standalone TLS connection
- Result
Immediate lease result
- Timeout
Shared acquisition and provider deadline
- Token
Optional cancellation source that outlives the capability
Raised exceptions
- Operation_Cancelled
Token or Close is active
- Timeout_Error
The lease is busy at the shared deadline
- 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 TLS provider step.
Enumeration literals
- Made_Progress
The provider advanced or completed the operation
- Need_Read
The next provider step needs descriptor read readiness
- Need_Write
The next provider step needs descriptor write readiness
- Peer_Closed
The peer ended the applicable TLS direction