Tracking issue for 'checked_duration_since' feature

[vi]

There going to be checked analogues of offseting Instants by Durations, but I see no analogue of non-panicking calculation of Duration from a pair of Instants.

Note: this issue is referred by #[unstable] in the pull request.

[dtolnay]

Some use cases from @vi:

Most recent example from my code:

let rtt4 = if now >= send_time { now - send_time } else { Duration::from_secs(999)};

now.saturating_duration_since(send_time) would probably be OK for this, or a checked_duration_since with more explicit fallback.

The comparison was added when I suddenly encountered a panic.

A close call nearby:

if now < deadline {
    sleeper.sleep(deadline - now);
}

Although readable as is, using saturating_duration_since would be almost equally good.

That comparison is easy to miss, leading to panic when under load. Seeing checked/saturating analogues nearby in documentation puts one in "here be dragonsoverflows" mode and suggests care.

[faern]

I just had good use for Instant::checked_duration_since. It's a good method to have when working with deadlines, as compared to timeouts. I get a deadline: Instant handed to me, and I need to figure out how far into the future it is without risking a panic:

deadline.checked_duration_since(Instant::now())

[faern]

I do like checked_duration_since, and I would like that function stabilized. It both lowers the amount of code needed and lowers the risk of screwing up some check and ending up with a panic. It's already used by parking_lot here and here. And it can use it in even more places when it's stable.

However, I personally don't see the benefit of saturating_duration_since. It's a small convenience, but it does not help the user avoid panics like checked_duration_since does.

In the example posted above, regarding saturating_duration_since:

if now < deadline {
    sleeper.sleep(deadline - now);
}

The author hint that they would like to shorten it to:

sleeper.sleep(deadline.saturating_duration_since(now));

But it feels wasteful* to call sleep when we don't want to sleep, and I would personally have used:

if let Some(time_left) = deadline.checked_duration_since(now) {
    sleeper.sleep(time_left);
}

If someone really want a saturating computation it's not that many extra characters to type deadline.checked_duration_since(now).unwrap_or(Duration::new(0, 0)).

*: Assuming sleeper. means std::thread::, some platforms (Windows and CloudABI from what I can see) don't have any check if the duration is non-zero, and will actually perform the syscall even if the duration is zero.

[alexcrichton]

Removing nomination since this is covered by #62860