time can be paused and resumed repeatedly

[tsidea]

The resume function was breaking the guarantee that Instants should
never be less than any previously measured Instants when created.

Altered the pause and resume function such that they will not break this
guarantee. After resume, the time should continue from where it left
off.

Created test to prove that the advanced function still works as
expected.

Added additional tests for the pause/advance/resume functions.

Updated documentation.

Motivation

The tokio::time::resume() function was breaking the following guarantee: "Instants are always guaranteed to be no less than any previously measured instant when created".
This happened because after pausing via tokio::time::pause() and then advancing via
tokio::time::advance() the time might have advanced by much more than what the real time was.
After calling tokio::time::resume() in this situation, a call to Instant::now() would yield an
Instant that would be less than the one created after advancing and before resuming. There are 2 tests added that can demonstrate this if ran on the old code.

Solution

The tokio::time::resume() function was changed to take into account the advanced time and will start counting from that point forward. That means that if while paused you advanced the time to T+10, resume will start at T+10 and move along with the system clock afterwards. You can also pause it again, advance by another duration and once you resume, it will again start where it left off after the advance.
For example:
pause at time T
advance by 10 => time is T+10
resume => time is T+10 + x ( x is elapsed since resumed)
pause at T+10+x => time is T+10+x
advance by 3 => time is T+10+x+3
resume => time is T+10+x+3+ elapsed since resumed

[LucioFranco]

This seems like something we should def fix though I'd like to defer this to @carllerche

[tsidea]

@carllerche, Sorry to bug you, but this might be quick. It's just a fix to a minor bug. Let me know if you have any questions.
Thanks!

[carllerche]

Thanks for getting this started. Instead of leaving review comments, I ended up pushing a commit to this PR that made fairly significant changes to the clock implementation. I left the new tests you had though as those are 👍

Let me know what you think.

[tsidea]

unfrozen is much better than since_started. Less code with the same functionality is always better.
Thanks! it's great!