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

craigpastro · 2020-06-16T03:33:20Z

Motivation

To add an interval example to the time module, add also add examples to the interval and delay_for functions. (#2494).

Solution

Add an example using interval to the time module
Add the same example to the interval function
Copy the delay_for example in the module to the delay_for function
Fix the comment for the delay_for example in the module

Refs: #2494

Add an example using `interval` to the time module. Add the same example to the `interval` function. Copy the `delay_for` example in the module to the `delay_for` function. Finally, fix the comment for the `delay_for` example in the time module Refs: #2494

Darksonn

The text here explains it as interval allowing you to do other things while awaiting the tick, but that's not really accurate. The amount of time a .tick().await call spends sleeping depends on the time since the last tick, but the tick still causes the task to sleep, and doesn't cause several things to happen at the same time.

We should also not use the word "blocks" for waiting, as it is easily confused with blocking the thread. I have added a suggestion below for how one might rephrase the text.

Darksonn · 2020-06-16T06:55:53Z

tokio/src/time/interval.rs

+/// `tokio::time::interval` yields so every iteration of the loop takes
+/// two seconds (except the first as the first `tick` completes immediately).
+/// The difference with `tokio::time::delay_for` is that `delay_for` blocks.
+/// Replacing `interval` with `delay_for` would result in a loop that takes
+/// three seconds per iteration.


It is dangerous to use the phrase "blocks" because it is very easily confused with blocking the thread, which is a very bad thing to do in async/await.

Suggested change

/// `tokio::time::interval` yields so every iteration of the loop takes

/// two seconds (except the first as the first `tick` completes immediately).

/// The difference with `tokio::time::delay_for` is that `delay_for` blocks.

/// Replacing `interval` with `delay_for` would result in a loop that takes

/// three seconds per iteration.

/// 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.

///

/// [`delay_for`]: crate::time::delay_for()

Indeed, that is much better. Thank you. I'll update the comment in the module as well and add links.

I also added links to interval in the docs for interval. Is that too much?

It is unnecessary to make it a link on interval's documentation.

Darksonn · 2020-06-16T08:06:45Z

tokio/src/time/delay.rs

+/// Wait 100ms and print "100 ms have elapsed". Note that no work is
+/// performed while awaiting on the delay to complete. If you wish to do
+/// other work while awaiting please see [`interval`].


Can you change it so it says that interval is used for regularly running something according to a schedule or something like that? And move the part about interval up before the # Cancellation header?

How is the following?

If you wish to run something regularly on a schedule see [interval].

I prefer to avoid "If you wish" in documentation, but other than that it is fine

To run something regularly on a schedule, see interval.

Okay! Thanks.

Remove links to `interval` in the `interval` documentation and reword the comment for `delay_for`.

Darksonn

Thank you for the PR!

- docs: misc improvements (#2572, #2658, #2663, #2656, #2647, #2630, #2487, #2621, #2624, #2600, #2623, #2622, #2577, #2569, #2589, #2575, #2540, #2564, #2567, #2520, #2521, #2572, #2493) - rt: allow calls to `block_on` inside calls to `block_in_place` that are themselves inside `block_on` (#2645) - net: fix non-portable behavior when dropping `TcpStream` `OwnedWriteHalf` (#2597) - io: improve stack usage by allocating large buffers on directly on the heap (#2634) - io: fix unsound pin projection in `AsyncReadExt::read_buf` and `AsyncWriteExt::write_buf` (#2612) - io: fix unnecessary zeroing for `AsyncRead` implementors (#2525) - io: Fix `BufReader` not correctly forwarding `poll_write_buf` (#2654) - coop: returning `Poll::Pending` no longer decrements the task budget (#2549) - io: little-endian variants of `AsyncReadExt` and `AsyncWriteExt` methods (#1915) - io: fix panic in `AsyncReadExt::read_line` (#2541) - task: add [`tracing`] instrumentation to spawned tasks (#2655) - sync: allow unsized types in `Mutex` and `RwLock` (via `default` constructors) (#2615) - net: add `ToSocketAddrs` implementation for `&[SocketAddr]` (#2604) - fs: add `OpenOptionsExt` for `OpenOptions` (#2515) - fs: add `DirBuilder` (#2524) [`tracing`]: https://crates.io/crates/tracing Signed-off-by: Eliza Weisman <eliza@buoyant.io>

# 0.2.22 (July 2!, 2020) ### Fixes - docs: misc improvements (#2572, #2658, #2663, #2656, #2647, #2630, #2487, #2621, #2624, #2600, #2623, #2622, #2577, #2569, #2589, #2575, #2540, #2564, #2567, #2520, #2521, #2493) - rt: allow calls to `block_on` inside calls to `block_in_place` that are themselves inside `block_on` (#2645) - net: fix non-portable behavior when dropping `TcpStream` `OwnedWriteHalf` (#2597) - io: improve stack usage by allocating large buffers on directly on the heap (#2634) - io: fix unsound pin projection in `AsyncReadExt::read_buf` and `AsyncWriteExt::write_buf` (#2612) - io: fix unnecessary zeroing for `AsyncRead` implementors (#2525) - io: Fix `BufReader` not correctly forwarding `poll_write_buf` (#2654) - io: fix panic in `AsyncReadExt::read_line` (#2541) ### Changes - coop: returning `Poll::Pending` no longer decrements the task budget (#2549) ### Added - io: little-endian variants of `AsyncReadExt` and `AsyncWriteExt` methods (#1915) - task: add [`tracing`] instrumentation to spawned tasks (#2655) - sync: allow unsized types in `Mutex` and `RwLock` (via `default` constructors) (#2615) - net: add `ToSocketAddrs` implementation for `&[SocketAddr]` (#2604) - fs: add `OpenOptionsExt` for `OpenOptions` (#2515) - fs: add `DirBuilder` (#2524) [`tracing`]: https://crates.io/crates/tracing Signed-off-by: Eliza Weisman <eliza@buoyant.io>

Darksonn requested changes Jun 16, 2020

View reviewed changes

Darksonn added A-tokio Area: The main tokio crate C-maintenance Category: PRs that clean code up or issues documenting cleanup. M-time Module: tokio/time T-docs Topic: documentation labels Jun 16, 2020

Apply @Darksonn's suggestion to update comments

95e0a15

Darksonn reviewed Jun 16, 2020

View reviewed changes

time: updates based on feedback

2b9b907

Remove links to `interval` in the `interval` documentation and reword the comment for `delay_for`.

Darksonn approved these changes Jun 16, 2020

View reviewed changes

Darksonn merged commit e2adf26 into tokio-rs:master Jun 16, 2020

craigpastro deleted the interval-example branch June 16, 2020 09:59

hawkw mentioned this pull request Jul 20, 2020

chore: prepare to release 0.2.22 #2672

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

craigpastro commented Jun 16, 2020

Darksonn left a comment

Darksonn Jun 16, 2020

craigpastro Jun 16, 2020

craigpastro Jun 16, 2020

Darksonn Jun 16, 2020

Darksonn Jun 16, 2020

craigpastro Jun 16, 2020

Darksonn Jun 16, 2020

craigpastro Jun 16, 2020

Darksonn left a comment

-/// `tokio::time::interval` yields so every iteration of the loop takes
-/// two seconds (except the first as the first `tick` completes immediately).
-/// The difference with `tokio::time::delay_for` is that `delay_for` blocks.
-/// Replacing `interval` with `delay_for` would result in a loop that takes
-/// three seconds per iteration.
+/// 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.
+///
+/// [`delay_for`]: crate::time::delay_for()

time: add an example using interval to the time module #2623

time: add an example using interval to the time module #2623

Conversation

craigpastro commented Jun 16, 2020

Motivation

Solution

Darksonn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Darksonn left a comment

Choose a reason for hiding this comment

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

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