Timers & Intervals

Tokio's timer wheel drives sleep, interval, timeout, and Instant-based scheduling without blocking worker threads. Enable the time feature for production services.

Recipe

Quick-reference recipe card - copy-paste ready.

use tokio::time::{sleep, Duration, timeout};
 
async fn work() -> &'static str {
    sleep(Duration::from_millis(50)).await;
    "ok"
}
 
#[tokio::main]
async fn main() {
    let result = timeout(Duration::from_secs(1), work()).await;
    println!("{:?}", result);
}

When to reach for this: Debouncing, periodic polls, request deadlines, retry backoff, and heartbeat ticks.

Working Example

use tokio::time::{interval, sleep, Duration, MissedTickBehavior};
 
#[tokio::main]
async fn main() {
    let mut ticker = interval(Duration::from_millis(100));
    ticker.set_missed_tick_behavior(MissedTickBehavior::Skip);
 
    for _ in 0..3 {
        ticker.tick().await;
        println!("tick");
    }
 
    sleep(Duration::from_millis(250)).await;
    ticker.tick().await; // skips missed ticks with Skip behavior
    println!("resumed");
}

What this demonstrates:

• interval produces periodic wakes.
• MissedTickBehavior::Skip avoids catch-up storm after delay.
• sleep is one-shot delay.

Deep Dive

How It Works

• Timer wheel: Efficient scheduling of many deadlines.
• sleep: Relative delay from now.
• interval: Periodic; first tick completes immediately unless interval_at used.
• timeout: Wrapper cancelling inner future on expiry.

Missed Tick Behavior

Rust Notes

use tokio::time::{Instant, Duration};
 
let start = Instant::now() + Duration::from_secs(1);
let mut ticker = tokio::time::interval_at(start, Duration::from_secs(5));

• Use Instant from tokio::time, not std::time::Instant, in async tests with pause.
• Layer timeouts: connect, TTFB, total request.
• Exponential backoff: sleep(duration * 2u32.pow(attempt)) with cap.

Gotchas

• std::thread::sleep in async - Blocks worker. Fix: tokio::time::sleep.
• interval catch-up storm - Default burst fires many ticks after stall. Fix: MissedTickBehavior::Skip for heartbeats.
• timeout too tight on cold start - False failures on JIT/connection warmup. Fix: Separate warmup budget or retry.
• Timer without time feature - Compile/runtime failure. Fix: features = ["time"] on tokio.
• Assuming wall-clock precision - Timers are cooperative under load. Fix: Do not use for hard real-time guarantees.

Alternatives

FAQs

Related

• Cancellation & Timeouts - deadlines
• Combining Futures - timeout in select
• select! & Concurrency - timer branches
• Tokio Basics - sleep intro
• Graceful Shutdown - drain timeouts

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.