Skip to content

Commit

Permalink
Unrolled build for rust-lang#119242
Browse files Browse the repository at this point in the history
Rollup merge of rust-lang#119242 - BenWiederhake:dev-from-nanos, r=joshtriplett

Suggest less bug-prone construction of Duration in docs

std::time::Duration has a well-known quirk: Duration::as_nanos() returns u128 [1], but Duration::from_nanos() takes u64 [2]. So these methods cannot easily roundtrip [3]. It is not possible to simply accept u128 in from_nanos [4], because it requires breaking other API [5].

It seems to me that callers have basically only two options:
1. `Duration::from_nanos(d.as_nanos() as u64)`, which is the "obvious" and buggy approach.
2. `Duration::new(d.as_secs(), d.subsecs_nanos())`, which only becomes apparent after reading and digesting the entire Duration struct documentation.

I suggest that the documentation of `from_nanos` is changed to make option 2 more easily discoverable.

There are two major usecases for this:
- "Weird math" operations that should not be supported directly by `Duration`, like squaring.
- "Disconnected roundtrips", where the u128 value is passed through various other stack frames, and perhaps reconstructed into a Duration on a different machine.

In both cases, it seems like a good idea to not tempt people into thinking "Eh, u64 is good enough, what could possibly go wrong!". That's why I want to add a note that points out the similarly-easy and *safe* way to reconstruct a Duration.

[1] https://doc.rust-lang.org/stable/std/time/struct.Duration.html#method.as_nanos
[2] https://doc.rust-lang.org/stable/std/time/struct.Duration.html#method.from_nanos
[3] https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=fa6bab2b6b72f20c14b5243610ea1dde
[4] rust-lang#103332
[5] rust-lang#51107 (comment)
  • Loading branch information
rust-timer committed Feb 11, 2024
2 parents 899c895 + 27ba1c1 commit e250592
Showing 1 changed file with 5 additions and 0 deletions.
5 changes: 5 additions & 0 deletions library/core/src/time.rs
Original file line number Diff line number Diff line change
Expand Up @@ -273,6 +273,11 @@ impl Duration {

/// Creates a new `Duration` from the specified number of nanoseconds.
///
/// Note: Using this on the return value of `as_nanos()` might cause unexpected behavior:
/// `as_nanos()` returns a u128, and can return values that do not fit in u64, e.g. 585 years.
/// Instead, consider using the pattern `Duration::new(d.as_secs(), d.subsec_nanos())`
/// if you cannot copy/clone the Duration directly.
///
/// # Examples
///
/// ```
Expand Down

0 comments on commit e250592

Please sign in to comment.