rust-lang / rust-lang/libs-team

ACP: Add Instant::epoch()

Open
#850 11 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

api-change-proposal
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.