std: make Instant a signed Duration on all platforms

[joboet]

This fixes #156142 for all targets using a very principled solution: representing Instant the same way on all platforms.

Currently, not all platforms have the same range and precision of Instant: while all UNIX platforms (and Hermit) represent Instant using a pair consisting of an 64-bit signed second field and a non-negative nanosecond offset and thus are able to represent timepoints well before the system epoch, most other platforms use a Duration with the result that operations like Instant::now() - Duration::from(/* 100 years */) do not succeed. SOLID even represents Instant using a microsecond counter, which means that nanosecond arithmetic is lossy.

To improve the portability of time arithmetic, I propose using the same representation for Instant on all platforms: a 64-bit signed second field and a non-negative nanosecond offset (i.e. a signed Duration). This means that:

• Since all platform timestamp types can either represent the same time range or a smaller one, Instant::now can never fail due to an out-of-bounds timestamp from the platform.
• Time arithmetic works identically on all platforms, operations like adding or subtracting large but not unreasonable durations do not fail (as long as the platform chooses a reasonable epoch).

Note that this does not add any significant conversion cost since all platforms currently convert to some seconds-based unit anyway.

I've split this PR into two parts: the first makes the actual changes to the implementation, the second adjusts the documentation to remove any mentions of platform-specific representations.

[rustbot]

r? @Darksonn

rustbot has assigned @Darksonn.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: @ChrisDenton, libs
• @ChrisDenton, libs expanded to 13 candidates
• Random selection from 6 candidates

[joboet]

This does more than required for the conversion – but the existing implementation was both incorrect (the TSC-based time passed 1000 times slower than real time due to a faulty conversion) and lossy. Since our UEFI code isn't free from issues anyway I took the liberty of adjusting this to what I see as a better algorithm. I can split this out if you'd like.

View changes since the review

[ChrisDenton]

So to state this explicitly, this makes Instant a signed Duration?

[joboet]

So to state this explicitly, this makes Instant a signed Duration?

Yes, exactly.

[Amanieu]

@rfcbot merge libs

[rust-rfcbot]

@Amanieu has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @cuviper
• @joshtriplett
• @the8472
• @thomcc

Concerns:

• input-from-andrew-gallant (std: make Instant a signed Duration on all platforms #158368 (comment))

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[the8472]

Since this changes the windows implementation to do more work it would be good to have a benchmark how this affects throughput/latency of Instant::now()

[joboet]

Since this changes the windows implementation to do more work it would be good to have a benchmark how this affects throughput/latency of Instant::now()

It doesn't, the Windows implementation already converts to seconds/nanoseconds on every Instant::now. The difference is that between unsigned division and remainder and signed div_euclid/rem_euclid, which I think is safe to assume negligible.

[Darksonn]

@rustbot label -S-waiting-on-review +S-waiting-on-fcp

[rust-bors]

☔ The latest upstream changes made this pull request unmergeable. Please resolve the merge conflicts by rebasing.

[joboet]

@rustbot label +I-libs-nominated

Just to make sure this doesn't get forgotten... or are there any concerns?

[joshtriplett]

This seems generally reasonable to me.

@rfcbot reviewed

Two thoughts, though:

First: I'd like to hear from @BurntSushi, as the author of jiff, before we merge this.

@rfcbot concern input-from-andrew-gallant

Second, and this is not a blocker for this proposal: I'm wondering if we should provide SignedDuration as a library type. It seems useful in other contexts.

(I briefly entertained the idea of SignedDuration stealing a sign bit from the nanoseconds, in order to have the same maximum as Duration and let conversions to it and signed-difference subtractions be infallible, but I don't think it's worth the complexity in practice, and conversions from it back to Duration would still be fallible.)