Функция advance

Перемещает время вперёд.

Увеличивает сохранённое значение Instant::now() на duration. Последующие вызовы Instant::now() будут возвращать результат увеличения.

Эта функция одним скачком перемещает текущее время вперёд на заданную длительность. Это означает, что все вызовы sleep со сроком до нового времени немедленно завершатся «одновременно», а среда выполнения может опрашивать их в любом порядке. Кроме того, этот метод не будет ждать завершения вызовов sleep, которые он обогнал. Если вам нужно дождаться их завершения, вместо этого вызовите sleep и воспользуйтесь функцией автоматического продвижения времени в среде выполнения.

Обратите внимание, что вызовы sleep не гарантированно завершатся при первом опросе после вызова advance. Например, это может произойти, если после вызова advance среда выполнения ещё не обращалась к драйверу таймеров. Однако, если они не завершатся, среда выполнения вскоре опросит задачу повторно.

Когда вместо этого использовать sleep

Важно: advance предназначена для тестирования, когда нужно мгновенно переместить время вперёд. Однако у неё есть ограничения, из-за которых она не подходит для некоторых сценариев использования:

• Принудительное срабатывание тайм-аутов: Если нужно надёжно вызвать тайм-аут, предпочтительнее использовать sleep с автоматическим продвижением времени, а не advance. Функция advance перемещает время вперёд, но не гарантирует, что все таймеры будут обработаны до продолжения выполнения вашего кода.

• Имитация зависания: Если вы пытаетесь смоделировать ситуацию, в которой программа зависает, а затем возобновляет работу, пакетное поведение advance может привести к неожиданным результатам. Все таймеры, время которых истекает во время продвижения времени, завершаются одновременно.

В большинстве тестовых сценариев, когда нужно дождаться истечения заданного времени и срабатывания всех таймеров по порядку, вместо этого используйте sleep:

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

#[tokio::test(start_paused = true)]
async fn test_timeout_reliable() {
    // Use sleep with auto-advance for reliable timeout testing
    time::sleep(Duration::from_secs(5)).await;
    // All timers that were scheduled to fire within 5 seconds
    // have now been processed in order
}

Паники

Вызывает панику при выполнении любого из следующих условий:

• Часы не приостановлены, поэтому перед вызовом этого метода необходимо вызвать pause.
• Вызов выполнен вне среды выполнения Tokio.
• Входное значение duration слишком велико (например, Duration::MAX), чтобы его можно было безопасно прибавить к текущему времени без переполнения.

Предостережения

Не рекомендуется использовать очень большое значение duration, поскольку это может привести к панике из-за переполнения.

Автоматическое продвижение времени

Если время приостановлено и нет работы, среда выполнения перемещает время к следующему таймеру. Подробнее см. в разделе pause.