Description
Lockstep framed control transport for one exact upgrade authority. One send or receive may be active at a time. This deliberate serialization keeps partial-frame failure, close, and poisoning ownership unambiguous.
Adopt
procedure Adopt
(Item : in out Control_Channel; Socket : in out Sockets.Socket_Type; Authority : Upgrade_Handle)
Transfer a connected AF_UNIX stream socket into a closed control channel and bind every future frame to Authority.
Parameters
- Item
Closed destination channel
- Socket
Connected stream socket whose ownership is transferred
- Authority
Exact transaction required on every frame
Channel_Busy
Channel_Busy : exception;
A second operation attempted to use the serialized channel.
Close
procedure Close (Item : in out Control_Channel)
Close the stream and consume its channel ownership.
Parameters
- Item
Channel to close
Control_Channel
type Control_Channel is limited private;
Sole owner of an authority-bound framed control stream.
Is_Open
function Is_Open (Item : Control_Channel) return Boolean
Report whether the channel currently owns an open stream.
Parameters
- Item
Channel to inspect
Return value
True when the stream is open
Is_Poisoned
function Is_Poisoned (Item : Control_Channel) return Boolean
Report whether an earlier failed operation poisoned the channel.
Parameters
- Item
Channel to inspect
Return value
True when failure made the stream unusable
Message_Available
function Message_Available
(Item : Control_Channel;
Timeout : Duration := Flyology.IO.Infinite;
Token : access Flyology.Cancellation.Token := null) return Boolean
Wait for the start of the next frame without consuming stream bytes. Cancellation is therefore safe: a caller may send a compensating command on the same channel after Operation_Cancelled is raised.
Parameters
- Item
Open authority-bound channel
- Timeout
Maximum readiness wait
- Token
Optional one-shot cancellation source
Return value
True when a frame or peer closure is readable; False on timeout
Raised exceptions
- Operation_Cancelled
Token is requested
Protocol_Error
Protocol_Error : exception;
Frame structure or message ordering is invalid.
Receive
procedure Receive
(Item : in out Control_Channel; Frame : out Protocol.Frame; Timeout : Duration := Flyology.IO.Infinite)
Receive exactly one frame. Invalid framing, stale authority, unexpected sequence, partial I/O failure, and timeout poison and close the channel.
Parameters
- Item
Authority-bound source channel
- Frame
Received frame
- Timeout
Total operation timeout
Send
procedure Send
(Item : in out Control_Channel;
Kind : Protocol.Message_Kind;
Payload : Protocol.Payload_Buffer;
Length : Protocol.Payload_Length;
Timeout : Duration := Flyology.IO.Infinite)
Send one frame with a bounded payload.
Parameters
- Item
Authority-bound destination channel
- Kind
Control message kind
- Payload
Payload storage
- Length
Significant payload bytes
- Timeout
Total operation timeout
Send
procedure Send
(Item : in out Control_Channel;
Kind : Protocol.Message_Kind;
Timeout : Duration := Flyology.IO.Infinite)
Send one frame with an empty payload.
Parameters
- Item
Authority-bound destination channel
- Kind
Control message kind
- Timeout
Total operation timeout
Sequence_Error
Sequence_Error : exception;
A peer sequence is stale, skipped, or exhausted.
Transport_Error
Transport_Error : exception;
Socket I/O or timeout prevented a complete operation.
Validation_Error
Validation_Error : exception;
The frame authority does not match the adopted transaction.