time: add example using `interval` to the time module (#2623)

3 files changed, 82 insertions, 1 deletions

diff --git a/tokio/src/time/delay.rs b/tokio/src/time/delay.rs
index 2e0c9124..744c7e16 100644
--- a/tokio/src/time/delay.rs
+++ b/tokio/src/time/delay.rs
@@ -29,10 +29,28 @@ pub fn delay_until(deadline: Instant) -> Delay {
 /// operates at millisecond granularity and should not be used for tasks that
 /// require high-resolution timers.
 ///
+/// To run something regularly on a schedule, see [`interval`].
+///
 /// # Cancellation
 ///
 /// Canceling a delay is done by dropping the returned future. No additional
 /// cleanup work is required.
+///
+/// # Examples
+///
+/// Wait 100ms and print "100 ms have elapsed".
+///
+/// ```
+/// use tokio::time::{delay_for, Duration};
+///
+/// #[tokio::main]
+/// async fn main() {
+///     delay_for(Duration::from_millis(100)).await;
+///     println!("100 ms have elapsed");
+/// }
+/// ```
+///
+/// [`interval`]: crate::time::interval()
 #[cfg_attr(docsrs, doc(alias = "sleep"))]
 pub fn delay_for(duration: Duration) -> Delay {
     delay_until(Instant::now() + duration)
diff --git a/tokio/src/time/interval.rs b/tokio/src/time/interval.rs
index 090e2d1f..1fa21e66 100644
--- a/tokio/src/time/interval.rs
+++ b/tokio/src/time/interval.rs
@@ -33,6 +33,37 @@ use std::task::{Context, Poll};
 ///     // approximately 20ms have elapsed.
 /// }
 /// ```
+///
+/// A simple example using `interval` to execute a task every two seconds.
+///
+/// The difference between `interval` and [`delay_for`] is that an `interval`
+/// measures the time since the last tick, which means that `.tick().await`
+/// may wait for a shorter time than the duration specified for the interval
+/// if some time has passed between calls to `.tick().await`.
+///
+/// If the tick in the example below was replaced with [`delay_for`], the task
+/// would only be executed once every three seconds, and not every two
+/// seconds.
+///
+/// ```
+/// use tokio::time;
+///
+/// async fn task_that_takes_a_second() {
+///     println!("hello");
+///     time::delay_for(time::Duration::from_secs(1)).await
+/// }
+///
+/// #[tokio::main]
+/// async fn main() {
+///     let mut interval = time::interval(time::Duration::from_secs(2));
+///     for _i in 0..5 {
+///         interval.tick().await;
+///         task_that_takes_a_second().await;
+///     }
+/// }
+/// ```
+///
+/// [`delay_for`]: crate::time::delay_for()
 pub fn interval(period: Duration) -> Interval {
     assert!(period > Duration::new(0, 0), "`period` must be non-zero.");
 
diff --git a/tokio/src/time/mod.rs b/tokio/src/time/mod.rs
index 7070d6b2..c532b2c1 100644
--- a/tokio/src/time/mod.rs
+++ b/tokio/src/time/mod.rs
@@ -24,7 +24,7 @@
 //!
 //! # Examples
 //!
-//! Wait 100ms and print "Hello World!"
+//! Wait 100ms and print "100 ms have elapsed"
 //!
 //! ```
 //! use tokio::time::delay_for;
@@ -58,6 +58,38 @@
 //! }
 //! # }
 //! ```
+//!
+//! A simple example using [`interval`] to execute a task every two seconds.
+//!
+//! The difference between [`interval`] and [`delay_for`] is that an
+//! [`interval`] measures the time since the last tick, which means that
+//! `.tick().await` may wait for a shorter time than the duration specified
+//! for the interval if some time has passed between calls to `.tick().await`.
+//!
+//! If the tick in the example below was replaced with [`delay_for`], the task
+//! would only be executed once every three seconds, and not every two
+//! seconds.
+//!
+//! ```
+//! use tokio::time;
+//!
+//! async fn task_that_takes_a_second() {
+//!     println!("hello");
+//!     time::delay_for(time::Duration::from_secs(1)).await
+//! }
+//!
+//! #[tokio::main]
+//! async fn main() {
+//!     let mut interval = time::interval(time::Duration::from_secs(2));
+//!     for _i in 0..5 {
+//!         interval.tick().await;
+//!         task_that_takes_a_second().await;
+//!     }
+//! }
+//! ```
+//!
+//! [`delay_for`]: crate::time::delay_for()
+//! [`interval`]: crate::time::interval()
 
 mod clock;
 pub(crate) use self::clock::Clock;