Description
Exposes lane-neutral timer waits through standard Ada delay semantics.
Example:
Flyology.IO.Timers.Sleep_For (0.010);
Activation_Batch
type Activation_Batch (Capacity : Positive) is record
Count : Natural := 0;
Ids : Timer_Id_Array (1 .. Capacity) := (others => Timer_Id'First);
end record;
Every timer activated by one monotonic-clock sample. Only Ids (1 .. Count) are defined; callers must not depend on their order.
Record fields
- Capacity
Maximum number of ids in this batch
- Count
Number of defined entries in Ids
- Ids
Activated timer identities
Arm
procedure Arm (Timers : in out Timer_Set; Id : Timer_Id; Deadline : Ada.Real_Time.Time)
Arm or reschedule one slot. A deadline at or before the next clock sample is returned by the next Wait_Next without an additional sleep. Re-arming an already armed id replaces its pending deadline.
Parameters
- Timers
Timer collection to update
- Id
Caller-selected slot in 1 .. Timers.Capacity
- Deadline
Absolute monotonic deadline
Armed_Count
function Armed_Count (Timers : Timer_Set) return Natural
Return the number of currently armed timers.
Parameters
- Timers
Timer collection to inspect
Return value
Armed slot count
Cancel
procedure Cancel (Timers : in out Timer_Set; Id : Timer_Id)
Idempotently disarm one slot.
Parameters
- Timers
Timer collection to update
- Id
Caller-selected slot in 1 .. Timers.Capacity
Deadline_Array
type Deadline_Array is array (Timer_Id range <>) of Ada.Real_Time.Time;
Caller-indexed monotonic deadlines used to replace a complete timer set. Array indexes become the timer ids reported after activation.
Default_Backstep_Tolerance
Default_Backstep_Tolerance : constant Duration := 0.001;
Default amount by which wall-clock progress may lag monotonic progress without being reported as a backward adjustment.
Finish
procedure Finish (Operation : in out Timer_Operation)
Consume a terminal timer operation.
Parameters
- Operation
Terminal timer operation to consume
Raised exceptions
- Device_Error
The timer provider failed
Is_Armed
function Is_Armed (Timers : Timer_Set; Id : Timer_Id) return Boolean
Report whether one slot is currently armed.
Parameters
- Timers
Timer collection to inspect
- Id
Caller-selected slot in 1 .. Timers.Capacity
Return value
True until cancellation, replacement, or activation delivery
Rearm
procedure Rearm (Interval : Duration; Operation : in out Timer_Operation)
Restart a previously consumed timer operation.
Parameters
- Interval
Relative delay in seconds
- Operation
Previously consumed timer operation
Replace
procedure Replace (Timers : in out Timer_Set; Deadlines : Deadline_Array)
Replace the complete collection with the supplied deadline array. Existing arms are cancelled first. Deadlines must use a one-based range no longer than Timers.Capacity; each array index becomes its timer id. An empty array leaves the collection empty.
Parameters
- Timers
Timer collection to replace
- Deadlines
New one-shot monotonic deadlines
Sleep_For
function Sleep_For
(Set : not null access Flyology.Operations.Completion_Set'Class; Interval : Duration)
return Timer_Operation
Construct and start one relative timer operation in place.
Parameters
- Set
Completion set that owns the operation slot
- Interval
Relative delay in seconds
Return value
Started limited timer operation
Sleep_For
procedure Sleep_For (Interval : Duration)
Wait for Interval seconds. A nonpositive interval is one delay 0.0 yield. A lightweight task suspends on its event loop; a native task uses the runtime's native delay wait and blocks that task's thread. The monotonic clock and both wait paths pause during system sleep.
Parameters
- Interval
Relative delay in seconds
Sleep_For
procedure Sleep_For (Interval : Duration; Operation : in out Timer_Operation)
Start or restart a relative timer in an established operation object.
Parameters
- Interval
Relative delay in seconds
- Operation
Fresh, released, or consumed timer operation
Sleep_Until
function Sleep_Until
(Set : not null access Flyology.Operations.Completion_Set'Class; Deadline : Ada.Real_Time.Time)
return Timer_Operation
Construct and start one absolute timer operation in place.
Parameters
- Set
Completion set that owns the operation slot
- Deadline
Absolute Ada.Real_Time deadline
Return value
Started limited timer operation
Sleep_Until
procedure Sleep_Until (Deadline : Ada.Real_Time.Time)
Wait until the monotonic real-time Deadline. A past deadline returns at the next scheduling point. Lane blocking and system-sleep behavior match Sleep_For.
Parameters
- Deadline
Absolute Ada.Real_Time deadline
Sleep_Until
procedure Sleep_Until (Deadline : Ada.Real_Time.Time; Operation : in out Timer_Operation)
Start or restart an absolute timer in an established operation object.
Parameters
- Deadline
Absolute Ada.Real_Time deadline
- Operation
Fresh, released, or consumed timer operation
Timer_Id
subtype Timer_Id is Positive;
Stable caller-selected identity for one slot in a Timer_Set.
Timer_Id_Array
type Timer_Id_Array is array (Positive range <>) of Timer_Id;
Bounded list of timer ids activated by one Wait_Next call.
Timer_Operation
type Timer_Operation is new Flyology.Operations.Operation with private;
Scoped timer operation associated with one heterogeneous completion set. The set must outlive the operation.
Timer_Set
type Timer_Set (Capacity : Positive) is limited private;
Bounded, caller-owned collection of monotonic timers. The object is not task safe: one task must serialize Arm, Replace, Cancel, and Wait_Next. Each arm is one-shot and Wait_Next disarms it when reported. The object allocates no storage after declaration and registers only its earliest pending deadline with the calling task's normal timer path.
Record fields
- Capacity
Maximum number of caller-selected timer ids
Timer_Wait_Outcome
type Timer_Wait_Outcome is (Timers_Activated, Wait_Timed_Out);
Terminal reason for a bounded Timer_Set wait.
Enumeration literals
- Timers_Activated
Activated contains every timer due at the operation's terminal monotonic-clock sample
- Wait_Timed_Out
No timer was due by the timeout deadline
Wait_Next
procedure Wait_Next (Timers : in out Timer_Set; Activated : out Activation_Batch)
Wait for and consume the next nonempty activation batch. All timers due at one monotonic-clock sample are returned and disarmed together. A timer that passes after that sample remains armed, so the next call returns it before sleeping; processing one batch therefore cannot lose later expirations. Activated.Capacity must equal Timers.Capacity. A lightweight caller suspends only its fiber; a native caller blocks only its pthread. The wait and clock pause during system sleep.
Parameters
- Timers
Nonempty timer collection to wait on and update
- Activated
Complete set of ids due at the operation's clock sample
Wait_Next
procedure Wait_Next
(Timers : in out Timer_Set;
Activated : out Activation_Batch;
Timeout : Duration;
Outcome : out Timer_Wait_Outcome)
Wait for the next activation batch for at most Timeout active monotonic seconds. A zero timeout performs one clock sample without sleeping. Timers due at the terminal sample take precedence over timeout and are returned normally. On Wait_Timed_Out, Activated.Count is zero and every timer remains armed for a later call. The timeout pauses during system sleep, matching the timer deadlines and both task lanes.
Parameters
- Timers
Nonempty timer collection to wait on and update
- Activated
Complete due set, or an empty batch on timeout
- Timeout
Maximum active monotonic wait in seconds
- Outcome
Whether timers activated or the bounded wait expired
Wait_Until
function Wait_Until
(Target : Ada.Calendar.Time; Backstep_Tolerance : Duration := Default_Backstep_Tolerance)
return Wall_Clock_Wait_Result
Wait until the adjustable wall clock reaches Target. A forward clock change may complete the wait early. A backward change larger than Backstep_Tolerance returns Clock_Moved_Backward so that the caller can revalidate its schedule; smaller changes are treated as jitter and the wait is rearmed. The comparison uses monotonic elapsed time and therefore detects a backstep even when successive wall-clock samples still increase. Steady reads bracket each wall read; broad brackets are retried, brackets wider than one second are rejected, and classification uses the least elapsed time allowed by the accepted brackets. Linux uses cancel-on-clock-set readiness. Darwin pairs clock-set notification with a relative monotonic timer and samples the wall clock in at-most-one- second active-time slices that continue after resume, bounding a missed notification's active-time detection latency apart from normal task- scheduling delay. A lightweight task suspends on its event loop; a native task blocks only its pthread. The steady clock and waits pause during system sleep, and the operation does not wake a suspended computer.
Parameters
- Target
Absolute Ada.Calendar wall-clock target
- Backstep_Tolerance
Permitted lost wall-clock progress in seconds
Return value
Terminal outcome, observation, and estimated backward adjustment
Raised exceptions
- Device_Error
Flyology.IO.Device_Error is raised when clock sampling, timer setup, or waiting fails
Wall_Clock_Wait_Outcome
type Wall_Clock_Wait_Outcome is (Target_Reached, Clock_Moved_Backward);
Terminal reason for a wall-clock wait.
Enumeration literals
- Target_Reached
The wall clock was observed at or beyond the target
- Clock_Moved_Backward
The wall clock lost more time than tolerated
Wall_Clock_Wait_Result
type Wall_Clock_Wait_Result is record
Outcome : Wall_Clock_Wait_Outcome;
Observed_Time : Ada.Calendar.Time;
Backward_Adjustment : Duration;
end record;
Result of a wall-clock wait.
Record fields
- Outcome
Why the wait returned
- Observed_Time
Wall-clock sample used for the terminal decision
- Backward_Adjustment
Estimated lost wall-clock progress in seconds; zero when Outcome is Target_Reached