From 5ad3dd337899c791a6e35e83dbf0fa7ca0edf605 Mon Sep 17 00:00:00 2001
From: sb64 <53383020+sb64@users.noreply.github.com>
Date: Wed, 16 Jun 2021 05:51:12 -0600
Subject: [PATCH] time: document auto-advancing behavior of runtime (#3763)

---
 tokio/src/time/clock.rs | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/tokio/src/time/clock.rs b/tokio/src/time/clock.rs
index a0ff62139..b9ec5c5aa 100644
--- a/tokio/src/time/clock.rs
+++ b/tokio/src/time/clock.rs
@@ -77,6 +77,15 @@ cfg_test_util! {
     ///
     /// Panics if time is already frozen or if called from outside of a
     /// `current_thread` Tokio runtime.
+    ///
+    /// # Auto-advance
+    ///
+    /// If time is paused and the runtime has no work to do, the clock is
+    /// auto-advanced to the next pending timer. This means that [`Sleep`] or
+    /// other timer-backed primitives can cause the runtime to advance the
+    /// current time when awaited.
+    ///
+    /// [`Sleep`]: crate::time::Sleep
     pub fn pause() {
         let clock = clock().expect("time cannot be frozen from outside the Tokio runtime");
         clock.pause();
@@ -111,6 +120,12 @@ cfg_test_util! {
     ///
     /// Panics if time is not frozen or if called from outside of the Tokio
     /// runtime.
+    ///
+    /// # Auto-advance
+    ///
+    /// If the time is paused and there is no work to do, the runtime advances
+    /// time to the next timer. See [`pause`](pause#auto-advance) for more
+    /// details.
     pub async fn advance(duration: Duration) {
         let clock = clock().expect("time cannot be frozen from outside the Tokio runtime");
         clock.advance(duration);