rust-lang / rust-lang/libs-team
ACP: Add Instant::epoch()
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 178
- Forks
- 28
- Avg merge
- 15m
- Merged PRs (30d)
- 1
Description
Proposal
Problem statement
It's a common need to store or transfer durations (as timestamps or otherwise) in a program. Often an API only accepts an Instant (or it is based on Instant::now()) in which case you need a reference point. Currently Rust provides no such reference point.
Motivating examples or use cases
There are 167 matches on Github for LazyLock<Instant>, most of which consist of some kind of hand-rolled epoch. However some of these are subtly incorrect.
Unless you are very sure that your epoch gets initialized before the Instant in question, you've now got a timestamp before your instant. So EPOCH.elapsed() is fine, but some_instant - EPOCH is not.
Solution sketch
We add a new function to Instant, which is guaranteed to return a historic instant:
impl Instant {
/// Return an instant which occurs no later than any other.
///
/// This instant may differ from one program invocation to the next,
/// but is always the same within one process.
pub fn epoch() -> Self { ... }
}
No further guarantees are given. It would be nice if the library developers make this Instant as late as feasibly possible, such that any timestamps like epoch().elapsed() are as small as reasonably possible (so that they may e.g. be stored in u64 nanosecond timestamps).
Alternatives
There is the mentioned LazyLock alternative, but with the mentioned pitfall of being initialized too late.
Open problems
I'm not 100% certain this function can be implemented on all platforms, when also taking into account dynamic linking, at least not without slowing down Instant::now() itself with a check to see if the epoch is initialized.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Instant API and its platform implementations, focusing on whether a process-wide historic value can be guaranteed without changing Instant::now(). Consider the stated dynamic-linking and cross-platform concerns; done requires a resolved implementation strategy and corresponding library tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- api
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100