Flyology API reference

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.

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 := 32;

Maximum number of descriptors in one allocation-free Wait_Any call.

No_Interrupts

No_Interrupts : constant Interrupt_Set (1 .. 0) :=
  (others => Invalid_Descriptor);

Empty interrupt set used when no wake source is present.

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.

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

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.

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

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

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.