Description
Supplies readiness primitives shared by lightweight and native tasks.
Example:
if Flyology.IO.Wait (FD, Flyology.IO.For_Read, 0.0) then
null;
end if;
Descriptor
subtype Descriptor is Interfaces.C.int;
Native operating-system descriptor number.
Device_Error
Device_Error : exception;
Raised when descriptor validation, polling, or a device operation fails.
Finish
procedure Finish (Operation : in out Readiness_Operation)
Consume a terminal readiness operation. Cancellation raises the common scoped-operation cancellation exception.
Parameters
- Operation
Terminal readiness operation to consume
Raised exceptions
- Device_Error
The readiness provider failed
Infinite
Infinite : constant Duration := -1.0;
Conventional negative timeout denoting no time limit. All negative Duration values have the same meaning in this API.
Interrupt_Set
type Interrupt_Set is array (Positive range <>) of Descriptor;
Readable wake descriptors composed into an interruptible wait. The wait observes but never reads or closes them; their owners must outlive the call.
Invalid_Descriptor
Invalid_Descriptor : constant Descriptor := Interfaces.C.int (-1);
Sentinel denoting no descriptor.
Is_Lightweight_Task
function Is_Lightweight_Task return Boolean
Report whether the calling Ada task uses a Flyology event loop.
Return value
True for a lightweight task; False for a native task
Max_Wait_Requests
Max_Wait_Requests : constant := 192;
Maximum number of descriptors in one allocation-free Wait_Any call. Bound shared with completion sets: 32 operations may each retain six transport, protocol, source, and lifecycle descriptor interests without helper tasks.
No_Interrupts
No_Interrupts : constant Interrupt_Set (1 .. 0) := (others => Invalid_Descriptor);
Empty interrupt set used when no wake source is present.
Readiness_Operation
type Readiness_Operation is new Flyology.Operations.Operation with private;
Scoped readiness operation associated with one completion set. Calling the operation-producing Wait overload below records the request without waiting. The completion set must outlive the operation.
Rearm
procedure Rearm (FD : Descriptor; Condition : Wait_Kind; Operation : in out Readiness_Operation)
Restart a previously consumed readiness operation.
Parameters
- FD
Valid descriptor to observe
- Condition
Requested readiness condition
- Operation
Previously consumed operation state
Timeout_Error
Timeout_Error : exception;
Raised by higher-level I/O operations when one deadline expires.
Wait
function Wait (FD : Descriptor; Condition : Wait_Kind; Timeout : Duration := Infinite) return Boolean
Wait until FD is ready or Timeout seconds expire. Negative means no limit; zero performs an immediate poll. A lightweight task suspends on its event loop; a native task blocks its thread in poll(2). Retries after EINTR share the original deadline. This is a potentially blocking operation and must not be called inside a protected action: a lightweight task that would suspend there raises Program_Error before suspending, while the zero-Timeout immediate poll does not suspend and is not refused. Native tasks keep stock behavior.
Parameters
- FD
Valid descriptor to observe
- Condition
Requested readiness condition
- Timeout
Deadline interval in seconds
Return value
True when ready; False on timeout
Raised exceptions
- Device_Error
FD is invalid or the poller fails
- Program_Error
A lightweight task would suspend inside a protected action
Wait
function Wait
(Set : not null access Flyology.Operations.Completion_Set'Class; FD : Descriptor; Condition : Wait_Kind)
return Readiness_Operation
Construct and start one readiness operation in place.
Parameters
- Set
Completion set that owns the operation slot
- FD
Valid descriptor to observe
- Condition
Requested readiness condition
Return value
Started limited readiness operation
Wait
procedure Wait (FD : Descriptor; Condition : Wait_Kind; Operation : in out Readiness_Operation)
Start or restart readiness in an established operation object. This is the composition form of the familiar Wait name.
Parameters
- FD
Valid descriptor to observe
- Condition
Requested readiness condition
- Operation
Fresh, released, or consumed readiness operation
Wait_Any
function Wait_Any (Requests : Wait_Request_Array; Timeout : Duration := Infinite) return Natural
Wait until one request is ready. Negative Timeout means no limit and zero is an immediate poll. One deadline spans EINTR retries. Duplicate descriptors and read/write pairs are supported; the lowest caller index wins simultaneous readiness. No descriptor is consumed. Lightweight tasks suspend; native tasks block their thread. A lightweight task that would suspend inside a protected action raises Program_Error, as for Wait.
Parameters
- Requests
At most Max_Wait_Requests readiness requests
- Timeout
Deadline interval in seconds
Return value
Exact Requests index ready, or 0 on timeout or empty input
Raised exceptions
- Device_Error
A descriptor is invalid or polling fails
- Program_Error
A lightweight task would suspend inside a protected action
Wait_Batch
type Wait_Batch (Capacity : Natural) is record
Count : Natural := 0;
Indexes : Wait_Index_Array (1 .. Capacity) := (others => Positive'First);
end record;
Batch of caller indexes observed ready by one Wait_Some call.
Record fields
- Capacity
Maximum number of indexes in the batch
- Count
Number of defined entries in Indexes
- Indexes
Ready indexes from the caller's request array
Wait_Index_Array
type Wait_Index_Array is array (Positive range <>) of Positive;
Bounded list of caller indexes that became ready in one wait. Only Indexes (1 .. Count) are defined. Indexes are reported in ascending caller-index order.
Wait_Interruptibly
function Wait_Interruptibly
(FD : Descriptor;
Condition : Wait_Kind;
Timeout : Duration := Infinite;
Interrupts : Interrupt_Set := No_Interrupts) return Wait_Outcome
Wait for FD or any readable interrupt source. Interrupt descriptors are neither read nor closed. Timeout and lane behavior match Wait; one deadline spans native EINTR retries.
Parameters
- FD
Primary valid descriptor
- Condition
Primary readiness condition
- Timeout
Deadline interval in seconds
- Interrupts
At most Max_Wait_Requests - 1 readable wake descriptors
Return value
Ready, Timed_Out, or Interrupted
Raised exceptions
- Device_Error
FD is invalid or the poller fails
- Program_Error
A lightweight task would suspend inside a protected action
Wait_Kind
type Wait_Kind is (For_Read, For_Write);
Readiness condition requested from the poller.
Enumeration literals
- For_Read
The descriptor can be read without blocking
- For_Write
The descriptor can be written without blocking
Wait_Outcome
type Wait_Outcome is (Ready, Timed_Out, Interrupted);
Result from an interruptible wait.
Enumeration literals
- Ready
The primary descriptor became ready
- Timed_Out
The deadline expired
- Interrupted
A member of the interrupt set became readable
Wait_Request
type Wait_Request is record
FD : Descriptor;
Condition : Wait_Kind;
end record;
One descriptor readiness request.
Record fields
- FD
Descriptor to observe
- Condition
Read or write readiness to observe
Wait_Request_Array
type Wait_Request_Array is array (Positive range <>) of Wait_Request;
Caller-indexed set passed to Wait_Any.
Wait_Some
procedure Wait_Some
(Requests : Wait_Request_Array; Completed : out Wait_Batch; Timeout : Duration := Infinite)
Wait until at least one request is ready, then report the requests observed ready by the terminal zero-time probe. A readiness event that disappears before that probe is still reported. Empty input and timeout return an empty batch. Completed.Capacity must equal Requests'Length. Duplicate requests remain distinct caller indexes. A lightweight task that would suspend inside a protected action raises Program_Error, as for Wait.
Parameters
- Requests
At most Max_Wait_Requests readiness requests
- Completed
Ready caller indexes
- Timeout
Deadline interval in seconds
Raised exceptions
- Device_Error
A descriptor is invalid or polling fails
- Program_Error
A lightweight task would suspend inside a protected action