Struct TIMERS

pub struct TIMERS;

App timers, deadlines and timeouts.

You can use this service to create UI bound timers, these timers run using only the app loop and awake the app to notify updates.

Timer updates can be observed using variables that update when the timer elapses, or you can register handlers to be called directly when the time elapses. Timers can be one-time, updating only once when a deadline is reached; or they can update every time on a set interval.

Note that you can also use the task::deadline function to .await deadlines, in app threads this function uses the TIMERS service too.

Precision

Timers elapse at the specified time or a little later, depending on how busy the app main loop is. High frequency timers can also have an effective lower frequency of updates because timers only elapse once per frame cycle.

Implementations

impl TIMERS

pub fn deadline( &self, deadline: impl Into<Deadline>, ) -> ReadOnlyVar<Deadline, ArcVar<Deadline>>

Returns a DeadlineVar that will update once when the deadline is reached.

If the deadline is in the past the variable will still update once in the next app update. Drop all clones of the variable to cancel the timer.

let deadline = TIMERS.deadline(20.secs());

text = deadline.map(|d| if d.has_elapsed() { "20 seconds have passed" } else { "..." });

In the example above the deadline variable will update 20 seconds later when the deadline has_elapsed. The variable is read-only and will only update once.

pub fn interval( &self, interval: Duration, paused: bool, ) -> ReadOnlyVar<Timer, ArcVar<Timer>>

Returns a TimerVar that will update every time the interval elapses.

The timer can be controlled using methods in the variable value. The timer starts running immediately if paused is false.

let timer = TIMERS.interval(1.secs(), false);

text = timer.map(|t| match t.count() {
    0 => formatx!(""),
    1 => formatx!("1 second elapsed"),
    c => formatx!("{c} seconds elapsed")
});

In the example above the timer variable will update every second, the variable keeps a count of times the time elapsed, that is incremented every update. The variable is read-only but the value can be used to control the timer to some extent, see TimerVar for details.

pub fn on_deadline<H>( &self, deadline: impl Into<Deadline>, handler: H, ) -> DeadlineHandle

where H: AppHandler<DeadlineArgs>,

Register a handler that will be called once when the deadline is reached.

If the deadline is in the past the handler will be called in the next app update.

let handle = TIMERS.on_deadline(20.secs(), app_hn_once!(|_| {
    println!("20 seconds have passed");
}));

Handler

The handler can be any of the once AppHandler implementers. You can use the macros app_hn_once! or async_hn_once! to declare a handler closure.

Async handlers execute up to the first .await immediately when the deadline is reached, subsequent awakes are scheduled like an async preview event handler.

Handle

Returns a DeadlineHandle that can be used to cancel the timer, either by dropping the handle or by calling cancel. You can also call perm to drop the handle without cancelling.

pub fn on_interval<H>( &self, interval: Duration, paused: bool, handler: H, ) -> TimerHandle

where H: AppHandler<TimerArgs>,

Register a handler that will be called every time the interval elapses.

The timer starts running immediately if paused is false.

impl TIMERS

pub fn wait_deadline( &self, deadline: impl Into<Deadline>, ) -> impl Future<Output = ()> + Send + Sync

Implementation of the task::deadline function when called from app threads.