time: A way to advance time manually

[amikhalev]

Is your feature request related to a problem? Please describe.
I am trying to write unit tests for code which involves running things throughout time in a task. I saw the tokio::time::{pause, advance} functions and thought those would work. I thought I could do something like this

tokio::time::pause();
do_thing_in_10s().await;
tokio::time::advance(Duration::from_secs(1)).await;
assert!(thing_did_not_happen_yet());

send_message_which_modifies_thing().await;
// need this so task will get the message 
tokio::task::yield_now().await;

tokio::time::advance(Duration::from_secs(1)).await;
assert!(thing_did_not_happen_yet()); // this assert fails

But since #2059, the yield_now will cause the executor to park the thread and the time driver advances time, so the thing happens early.

Describe the solution you'd like
A way to actually pause time and advance manually.

[carllerche]

Why is advancing time using sleep(Duration::from_secs(1)).await not sufficient here?

[amikhalev]

Since creating this issue I realized that sleeping while paused does exactly what I needed. This issue could either be closed or made into an issue for improving the docs. Ideally they would have an example of using sleep while paused to write tests.

[carllerche]

@amikhalev I am going ot close this, but I would love if you could follow up w/ a doc PR. The usage pattern can be described in the API docs for time::pause().