Instant::until, calculating the time until another Instant

[dvdsk]

This proposes a minor API addition improving readability a tiny bit. I follow the wording in the template therefore I speak about a problem. Not having this API is not a problem in my opinion however I think this change would (slightly) improve the standard library. For me such a small change seems like a good way to start contributing to Rust.

Proposal

Problem statement

There is no (very) easy/readable way to calculate the time until an Instant. Instead, we use: deadline.saturating_duration_since(Instant::now()) where deadline is a Instant possibly in the future. Using deadline.duration_since(Instant::now()) by mistake will lead to a panic when the deadline lies in the past, this is an easy mistake to make.

The readability problem can be mitigated by assigning the result to a variable named until. This however comes at the cost of making code longer.

Motivation, use-cases

The time until some Instant is often used to pause the current thread until that Instant has elapsed:

let until = hb_deadline
	.saturating_duration_since(Instant::now())
	.as_millis();
thread::sleep(until);

I use calculating the time till an Instant to track performance:

match timeout_at(hb_deadline, heartbeat.notified()).await {
	Err(_) => {
		warn!("heartbeat for term {} timed out", data.term());
		return;
	}
	Ok(_) => {
		let until = hb_deadline
			.saturating_duration_since(Instant::now())
			.as_millis();
		if until < Duration::from_millis(50) {
			warn!("overloaded");
			// ensure we no longer accept new requests
		}
	)
}

Most other use-cases will take the shape of a planning problem, checking if there is enough time left to perform an action before a deadline.

Solution sketches

A solution would be to add an until method to Instant. This would complement the existing elapsed method. Its API would be:

Instant::until(&self) -> Duration

Similarly to elapsed the until method would be a wrapper around one line containing only existing Instant methods. Specifically it will call argument.saturating_duration_since(Instant::now()).

There are widely used libraries that mirror the Instant type of the std (time and tokio). They currently implement all std Instant methods. To keep their Instants similar they will need to adopt Instant::until.

An alternative could be modifying and adding to the documentation of saturating_duration_since to highlight how to solve the use cases above.

The second solution has as advantage that there is no API change. I however prefer adding a function as that also solves the readability 'problem' and is more discoverable.

Links and related work

• The go-lang time package has an Until function that mirrors the proposed API change.
• Java's time package has an until member for its Instant class.
• Python and C++ do not have a function for this

The languages in this list with an Instant type to offer an until method.

The tokio framework has a sleep_until function that solves the sleep use case.

What happens now?

This issue is part of the libs-api team API change proposal process. Once this issue is filed the libs-api team will review open proposals in its weekly meeting. You should receive feedback within a week or two.

if the libs-api team decides to adopt this proposal I would like to do the implementation to learn a bit more about contributing to rust

[cuviper]

Using deadline.duration_since(Instant::now()) by mistake will lead to a panic when the deadline lies in the past, this is an easy mistake to make.

Note that this was changed to saturating as well, as of Rust 1.60, but this is subject to change.

A solution would be to add an until method to Instant. This would complement the existing elapsed method. Its API would be:

Instant::until(&self, deadline: Instant) -> Duration

Similarly to elapsed the until method would be a wrapper around one line containing only existing Instant methods. Specifically it will call argument.saturating_duration_since(Instant::now()).

If it's always using now(), then what is &self here?

I think it probably is the right idea to implicitly use now(), just as elapsed() does, but you didn't give an example how this will be called. Callers with two arbitrary times are probably fine with the current duration methods.

start_time.elapsed();

// vs which?

Instant::now().until(&deadline);
Instant::until(&deadline);
deadline.until();

---

deadline.are_we_there_yet()?
// "Soon," said the exhausted parent...

[dvdsk]

If it's always using now(), then what is &self here?

Thats a silly mistake of me (I have edited the proposal to fix it). The API that I meant is:

Instant::until(&self) -> Duration

Which you would call like:

let deadline = Instant:now() + Duration::from_millis(42);
println!("seconds left: {}", deadline.until().as_secs());

[m-ou-se]

Unlike elapsed, the name until doesn't suggest that it's relative to the current time. If I see a.until(), that reads to me like the time from a until.. something.

[dvdsk]

If I see a.until(), that reads to me like the time from a until.. something.

Good point I didn't think about it that way.

What do you think of one of these alternative names?

• time_left
• now_until

To me a.time_left() looks best (it reads more like natural language for me) however
a.now_until() makes clear that the duration is relative to the current time.

edit: another possibility is to put the API under duration: Duration::now_until(a)

[shepmaster]

thread::sleep_until(Instant) reads better to me. I don't know that the other cases presented have wide applicability, but if it were in my own code I'd probably just add an extension trait.

[dvdsk]

thread::sleep_until(Instant) reads better to me. I don't know that the other cases presented have wide applicability, but if it were in my own code I'd probably just add an extension trait.

I agree sleep_until(a) reads better then sleep(a.time_left) I would be more then happy to put forward a proposal for adding sleep until. That would have the advantage of bringing the synchronous code using the std more in line with tokio.

I did ran into another (probably quite specific) use-case, logging time left till an item has to be processed:

pub struct PerishableOrder<O> {
    pub order: O,
    pub process_by: Instant,
}

impl<O: std::fmt::Debug> PerishableOrder<O> {
    pub fn perished(&self) -> bool {
        let time_left = self.process_by.saturating_duration_since(Instant::now())
        if time_left.is_zero() {
             false
        } else {
             trace!("time left: {:?}", time_left());
             true
        }
    }
}

It might be a good idea to grep some projects for .saturating_duration_since(Instant::now()) to see if there are use cases outside my thesis :)

Is there a list of diverse projects that indicate wide applicability? Simply taking the top n most popular crates will bias towards framework/infrastructure libraries.

[m-ou-se]

It might be a good idea to grep some projects for .saturating_duration_since(Instant::now()) to see if there are use cases outside my thesis :)

There are 22 occurrences of that exact string on all of crates.io, spread over 18 crates: act-zero, alacritty_terminal, asciiarena, cameleon, chronobreak, cynthia, girt-view, ham, nativeshell, parking, perfrecord, polling, retainer, snare, solana-core, songbird, subprocess, and tonari-actor.

[dvdsk]

There are 22 occurrences of that exact string on all of crates.io

That is a lot less then I expected. Then this proposal is trying to solve a problem that does not exist. I might still makes sens to modify the existing example for saturating_duration_since to illustrate how to get until/time_left.

Does it make sense to implement sleep_until? I would suspect anyone needing it is currently using .saturating_duration_since(Instant::now()) in their code. The string sleep_until is used at least 3,018 in Rust code on github (a ton of that might be forks though). A similar search for deadline.saturating_duration_since( gave only 375 hits most being forks.

@m-ou-se Can you describe how you were able to search all of crates.io? Then I can try that myself to check sleep_until. It would also be useful in the future to get a quick estimate how useful an API might be (I have some other API proposals I want to put out).

[m-ou-se]

Does it make sense to implement sleep_until?

I think so, yes. And also std::thread::park_until.

Then this proposal is trying to solve a problem that does not exist.

Note that I only grepped for that exact string. Maybe someone wrote it with different whitespace, or used - or .sub or some other variant of the code.

Can you describe how you were able to search all of crates.io?

Here's how I downloaded all the crates: https://twitter.com/m_ou_se/status/1433085053056262144 (Careful when copy-pasting: there's a zero width space in that tweet to prevent Twitter turning it into a shortlink. ^^') All those .crate files are compressed tar files. Extracting them all can take a while, though. Uncompressed, all the *.rs files add up to about 60-70 GB. (Leaving out the non-*.rs files saves a lot of space.)

Feel free to send me some regexes for ripgrep if you want me to run a few more queries, as I already have it all on my computer here.

An alternative would be to use https://cs.github.com/, although that one still seems to be in (not fully public?) beta.

[joshtriplett]

I like the idea of a name like now_until; now makes it clear that this looks at the current time.

I think sleep_until is not a bad idea either, but I do think the general Instant API seems useful.

[dvdsk]

I did another search to get a better estimate how much the API could be used if implemented. This time I used saturating_duration_since as a sort of control to account for missing hits.

On sourcegraph.com I get:

• 758 hits for saturating_duration_since( results,
• 88 hits for saturating_duration_since(now results
• 92 hits for saturating_duration_since(Instant::now) results

From these numbers I would think its reasonable to assume an API similar to now_until would be used about 30% as much as saturating_duration_since.

Things get interesting once we start comparing to duration_since. Remember using a.duration_since(Instant::now()) will panic if a is in the past.

Still using sourcegraph.com:

• 250 hits for duration_since(Instant::now results
• 500 hits for duration_since(now results
• 15_000 hits for duration_since( results

A few observations:

1. There is a lot of code out there using duration_since(Instant::now) most of it should probably use something else as it might panic.
2. A now_until like API would cover about 5% of the uses of duration since.
3. Counting up all the hits doing something like now_until we get 930. The now_until API could therefore be used more often then saturating_duration_since.

The third point feels a bit iffy to me so take it with a grain of salt. If we were to add sleep_until/thread_park_until the usage would decrease again. However I think there is now enough evidence to conclude this API could be worth it to add to the std.

[m-ou-se]

We discussed this briefly in the libs meetup. We thought it'd be useful to have functions like sleep_until. If we have those, then we don't think there is enough reason to make an even shorter syntax for deadline.saturating_duration_since(now()).