Struct Timer

pub struct Timer { /* private fields */ }

A future or stream that emits timed events.

Timers are futures that output a single Instant when they fire.

Timers are also streams that can output Instants periodically.

Precision

There is a limit on the maximum precision that a Timer can provide. This limit is dependent on the current platform; for instance, on Windows, the maximum precision is about 16 milliseconds. Because of this limit, the timer may sleep for longer than the requested duration. It will never sleep for less.

Examples

Sleep for 1 second:

use async_io::Timer;
use std::time::Duration;

Timer::after(Duration::from_secs(1)).await;

Timeout after 1 second:

use async_io::Timer;
use futures_lite::FutureExt;
use std::time::Duration;

let addrs = async_net::resolve("google.com:80")
    .or(async {
        Timer::after(Duration::from_secs(1)).await;
        Err(std::io::ErrorKind::TimedOut.into())
    })
    .await?;

Implementations

impl Timer

pub fn never() -> Timer

Creates a timer that will never fire.

Examples

This function may also be useful for creating a function with an optional timeout.

use async_io::Timer;
use futures_lite::prelude::*;
use std::time::Duration;

async fn run_with_timeout(timeout: Option<Duration>) {
    let timer = timeout
        .map(|timeout| Timer::after(timeout))
        .unwrap_or_else(Timer::never);

    run_lengthy_operation().or(timer).await;
}

// Times out after 5 seconds.
run_with_timeout(Some(Duration::from_secs(5))).await;
// Does not time out.
run_with_timeout(None).await;

pub fn after(duration: Duration) -> Timer

Creates a timer that emits an event once after the given duration of time.

Examples

use async_io::Timer;
use std::time::Duration;

Timer::after(Duration::from_secs(1)).await;

pub fn at(instant: Instant) -> Timer

Creates a timer that emits an event once at the given time instant.

Examples

use async_io::Timer;
use std::time::{Duration, Instant};

let now = Instant::now();
let when = now + Duration::from_secs(1);
Timer::at(when).await;

pub fn interval(period: Duration) -> Timer

Creates a timer that emits events periodically.

Examples

use async_io::Timer;
use futures_lite::StreamExt;
use std::time::{Duration, Instant};

let period = Duration::from_secs(1);
Timer::interval(period).next().await;

pub fn interval_at(start: Instant, period: Duration) -> Timer

Creates a timer that emits events periodically, starting at start.

Examples

use async_io::Timer;
use futures_lite::StreamExt;
use std::time::{Duration, Instant};

let start = Instant::now();
let period = Duration::from_secs(1);
Timer::interval_at(start, period).next().await;

pub fn will_fire(&self) -> bool

Indicates whether or not this timer will ever fire.

never() will never fire, and timers created with after() or at() will fire if the duration is not too large.

Examples

use async_io::Timer;
use futures_lite::prelude::*;
use std::time::Duration;

// `never` will never fire.
assert!(!Timer::never().will_fire());

// `after` will fire if the duration is not too large.
assert!(Timer::after(Duration::from_secs(1)).will_fire());
assert!(!Timer::after(Duration::MAX).will_fire());

// However, once an `after` timer has fired, it will never fire again.
let mut t = Timer::after(Duration::from_secs(1));
assert!(t.will_fire());
(&mut t).await;
assert!(!t.will_fire());

// Interval timers will fire periodically.
let mut t = Timer::interval(Duration::from_secs(1));
assert!(t.will_fire());
t.next().await;
assert!(t.will_fire());

pub fn set_after(&mut self, duration: Duration)

Sets the timer to emit an event once after the given duration of time.

Note that resetting a timer is different from creating a new timer because set_after() does not remove the waker associated with the task that is polling the timer.

Examples

use async_io::Timer;
use std::time::Duration;

let mut t = Timer::after(Duration::from_secs(1));
t.set_after(Duration::from_millis(100));

pub fn set_at(&mut self, instant: Instant)

Sets the timer to emit an event once at the given time instant.

Note that resetting a timer is different from creating a new timer because set_at() does not remove the waker associated with the task that is polling the timer.

Examples

use async_io::Timer;
use std::time::{Duration, Instant};

let mut t = Timer::after(Duration::from_secs(1));

let now = Instant::now();
let when = now + Duration::from_secs(1);
t.set_at(when);

pub fn set_interval(&mut self, period: Duration)

Sets the timer to emit events periodically.

Note that resetting a timer is different from creating a new timer because set_interval() does not remove the waker associated with the task that is polling the timer.

Examples

use async_io::Timer;
use futures_lite::StreamExt;
use std::time::{Duration, Instant};

let mut t = Timer::after(Duration::from_secs(1));

let period = Duration::from_secs(2);
t.set_interval(period);

pub fn set_interval_at(&mut self, start: Instant, period: Duration)

Sets the timer to emit events periodically, starting at start.

Note that resetting a timer is different from creating a new timer because set_interval_at() does not remove the waker associated with the task that is polling the timer.

Examples

use async_io::Timer;
use futures_lite::StreamExt;
use std::time::{Duration, Instant};

let mut t = Timer::after(Duration::from_secs(1));

let start = Instant::now();
let period = Duration::from_secs(2);
t.set_interval_at(start, period);

Trait Implementations

impl Debug for Timer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Timer

fn drop(&mut self)

Executes the destructor for this type.

impl Future for Timer

type Output = Instant

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempts to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.

impl Stream for Timer

type Item = Instant

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.