Что такое tokio::time::sleep, timeout и interval? Как их использовать?

tokio::time: sleep, timeout, interval

Модуль tokio::time предоставляет три основных инструмента для работы со временем в асинхронном коде. Все они работают без блокировки потока — вместо std::thread::sleep runtime просто «засыпает» текущую задачу и выполняет другие.

tokio::time::sleep — одноразовая задержка

use tokio::time::{sleep, Duration};

#[tokio::main]
async fn main() {
    println!("start");
    sleep(Duration::from_millis(500)).await;
    println!("after 500ms");

    // sleep_until принимает Instant
    use tokio::time::{sleep_until, Instant};
    let deadline = Instant::now() + Duration::from_secs(1);
    sleep_until(deadline).await;
    println!("after absolute deadline");
}

tokio::time::Instant — монотонные часы, изолированные от системных (можно паузировать в тестах). Не путайте с std::time::Instant.

tokio::time::timeout — ограничение времени выполнения

use tokio::time::{timeout, Duration};
use tokio::net::TcpStream;

async fn connect_with_timeout(addr: &str) -> anyhow::Result<TcpStream> {
    match timeout(Duration::from_secs(5), TcpStream::connect(addr)).await {
        Ok(Ok(stream)) => Ok(stream),
        Ok(Err(e))     => Err(e.into()),      // соединение ошибка
        Err(_elapsed)  => Err(anyhow::anyhow!("connection timed out")),
    }
}

timeout оборачивает любую future. Если она не завершилась за отведённое время, возвращается Err(Elapsed). Внутренняя future отменяется (дропается) при истечении таймаута — убедитесь в её cancellation safety.

timeout_at — с абсолютным дедлайном

use tokio::time::{timeout_at, Instant, Duration};

async fn handle_request_with_budget(deadline: Instant) {
    // несколько операций делят общий бюджет времени
    let _ = timeout_at(deadline, step_one()).await;
    let _ = timeout_at(deadline, step_two()).await;
}

tokio::time::interval — периодические задачи

use tokio::time::{interval, Duration};

#[tokio::main]
async fn main() {
    let mut ticker = interval(Duration::from_secs(1));

    for i in 0..5 {
        ticker.tick().await;   // первый tick срабатывает немедленно!
        println!("tick {i}");
    }
}

Важно: первый tick() срабатывает сразу же при создании интервала. Если нужно начать с задержки, создайте интервал через interval_at:

use tokio::time::{interval_at, Instant, Duration};

let start = Instant::now() + Duration::from_secs(5);
let mut ticker = interval_at(start, Duration::from_secs(1));
ticker.tick().await; // первый tick через 5 секунд

MissedTickBehavior — что делать с пропущенными тиками

use tokio::time::{interval, Duration, MissedTickBehavior};

let mut ticker = interval(Duration::from_secs(1));
ticker.set_missed_tick_behavior(MissedTickBehavior::Skip);
// Burst  — немедленно возвращает все пропущенные тики (по умолчанию)
// Skip   — пропускает пропущенные, следующий тик через period от текущего момента
// Delay  — откладывает следующий тик на period от текущего момента

Практический пример: healthcheck loop

use tokio::time::{interval, timeout, Duration};
use tokio::sync::broadcast;

async fn healthcheck_loop(
    url: String,
    mut shutdown_rx: broadcast::Receiver<()>,
) {
    let mut ticker = interval(Duration::from_secs(30));
    ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);

    loop {
        tokio::select! {
            _ = ticker.tick() => {
                match timeout(Duration::from_secs(5), ping(&url)).await {
                    Ok(Ok(())) => println!("healthy"),
                    Ok(Err(e)) => eprintln!("unhealthy: {e}"),
                    Err(_)     => eprintln!("probe timed out"),
                }
            }
            _ = shutdown_rx.recv() => break,
        }
    }
}

async fn ping(_url: &str) -> anyhow::Result<()> { Ok(()) }

Подводные камни

• Первый interval.tick() срабатывает немедленно — это удивляет большинство разработчиков. Используйте interval_at(Instant::now() + period, period) для отложенного старта.
• Поведение по умолчанию MissedTickBehavior::Burst может вызвать всплеск задач после паузы (например, после GC или нагрузки). Для большинства production-задач лучше подходит Skip.
• timeout отменяет внутреннюю future при истечении времени — если future не cancellation-safe, данные могут быть потеряны.
• tokio::time::Instant и std::time::Instant несовместимы — нельзя передавать одно вместо другого.
• В тестах время Tokio можно паузировать с помощью tokio::time::pause() и перематывать через tokio::time::advance() — не используйте std::thread::sleep в async тестах, это блокирует поток.
• Если runtime «занят» (CPU-bound задачи без yield), таймеры не срабатывают вовремя — time-based гарантии в Tokio мягкие (best-effort).
• Забытый mut у переменной interval (let ticker вместо let mut ticker) — компилятор поймает, но это частая опечатка при быстром написании.

• Отвечать определением без production-сценария.
• Не называть runtime boundary, security boundary или failure mode.
• Игнорировать версию API, observability и тестовую проверку.

• Объясняет механизм своими словами и без выдуманных API.
• Называет реальные риски, диагностику и критерий корректности.
• Связывает ответ с текущей документацией и миграционными ограничениями.