ACP: Add Instant::epoch()

[orlp]

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.

[kennytm]

Return an instant which occurs no later than any other.

This description is strange, since you can just create let t = Instant::epoch() - Duration::from_secs(1);, in which Instant::epoch() will be later than t.

Perhaps you mean "an instant which is earlier than any Instant::now() call during the process's lifetime"?

---

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).

Since 2⁶⁴ ns = 584 years, almost any choice would be OK for "store in u64 nanosecond timestamps" task). So would Instant::epoch() returning the equivalent of SystemTime::UNIX_EPOCH be "reasonable"?

For the motivation, maybe we do need to guarantee that Instant::epoch() returns an instant near the process's start. If it is linked to the process I wonder if this should be Instant::epoch() or std::process::epoch().

[orlp]

I completely forgot that Instants can be modified by adding/subtracting Duration... oops. This makes "make this Instant as late as feasibly possible" impossible to optimize for with the original definition.

So this only would make sense if either

1. epoch() is at complete representable internal zero, or signed::MIN if the representation is signed (making it potentially useless for u64 nanosecond timestamps on some platforms),
2. epoch() is defined as process start, or
3. epoch() is defined as some point no later than the first call to now().

I'm not sure if 'process start' is possible on all platforms, especially considering cases where Rust does not control the entry point and is instead loaded dynamically into another process.

[scottmcm]

I think that epoch as a name to me sounds too consistent, and it should be weakened somehow. Maybe process_epoch or something? Because just calling it epoch to me sounds like I should expect it to have the same value all the time, which I don't think we want to promise across platforms.

such that any timestamps like epoch().elapsed() are as small as reasonably possible

I would suggest at minimum not promising "as small as reasonable possible", because that's a recipe for bugs. https://learn.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount was infamous for causing bugs if you don't restart for 7 weeks, for example. Debug builds of Windows start at a higher number to help catch this mistake.

See also https://randomascii.wordpress.com/2012/02/13/dont-store-that-in-a-float/ which suggests starting your game time at 4 billion seconds to avoid implicit assumptions of small values.

[orlp]

I think that epoch as a name to me sounds too consistent, and it should be weakened somehow.

I'm not too attached to the name epoch. Feel free to brainstorm.

---

I have a somewhat hacky, but actually kind-of-reasonable idea. This is completely portable to all platforms, does not add a burden to initialize an epoch to Instant::now() or do pre-main initialization, and allows small enough timestamps that they can be stored as i64 nanoseconds for applications that need efficiency.

/// Return an instant which is no later than any call to `Instant::now()`
/// that occurred in the past 100 years.
///
/// This instant may differ from one program invocation to the next, but
/// is always the same within one process. The returned instant is no
/// older than 100 years before the first call to epoch().
fn epoch() -> Instant {
    static EPOCH: LazyLock<Instant> = LazyLock::new(|| {
        Instant::now().saturating_sub(Duration::from_secs(60 * 60 * 24 * 365 * 100))
    });
    *EPOCH
}

[cuviper]

IMO, Instant::ZERO would suffice in most cases, and it would allow const-initialization. The meaning of 0 can be documented as unspecified, making no promises about elapsed with subtracted instants.

[orlp]

@cuviper Instant::ZERO would not suffice for storing subsequent timestamps in 64-bit integers without further guarantees on all platforms. This is important for performance-sensitive code, and serialization.

That said I'm definitely not against also introducing a const fn Instant::zero() for whenever you don't need the above guarantee and/or want static init.

[cuviper]

It's not good for timestamps anyway when you consider the clock ambiguity:

Note, however, that instants are not guaranteed to be steady. In other words, each tick of the underlying clock might not be the same length (e.g. some seconds may be longer than others). An instant may jump forwards or experience time dilation (slow down or speed up), but it will never go backwards. As part of this non-guarantee it is also not specified whether system suspends count as elapsed time or not.

[orlp]

I don't think this is the time and place to open that discussion up again. Whether the 'timestamp' is linear or has pauses has no bearing on the desire to have a reference epoch such that you get (64-bit) integers that are amenable to performance-sensitive manipulation (e.g. sorting or bucketing) and serialization. For example in my personal use-case: re-ordering events based on rough order of arrival after parallel processing has occurred. If this parallel processing was done on a cluster instead of one machine I would have wanted serialization as well. This use-case doesn't care at all about your time suspension snafu.

There are other efforts underway to add multiple clocks to Rust which specify whether or not they count elapsed time, and I think adding some sort of 'recent epoch before any now() calls' to all of them is useful.

[ChrisDenton]

Instant::ZERO can be guaranteed to occur before any Instant::now(). In practice it also fulfils the requirement that the epoch not be in the too distant past (typically it's boot time but could be the system epoch).

I could imagine a system that sets their epoch in the Jurassic for some reason and doesn't have an equivalent of a boot time clock but in that case we could adjust the offset so typical values fit in a u64.

[tgross35]

Perhaps MIN rather than ZERO in case a platform uses signed integers for some reason?

[jdahlstrom]

Prior discussions:

https://internals.rust-lang.org/t/instant-systemtime-min-max/21375 (2024)

https://internals.rust-lang.org/t/os-specific-extensions-for-creating-instant/22408/5 (2025)

https://internals.rust-lang.org/t/instant-past-value-constant/24297 (2026)