Skip to content

Commit

Permalink
Rollup merge of rust-lang#63846 - DevQps:32626-document-time-system-c…
Browse files Browse the repository at this point in the history
…alls, r=rkruppe

Added table containing the system calls used by Instant and SystemTime.

# Description
See rust-lang#32626 for a discussion on documenting system calls used by Instant and SystemTime.

## Changes
- Added a table containing the system calls used by each platform.

EDIT: If I can format this table better (due to the large links) please let me know.
I'd also be happy to learn a quick command to generate the docs on my host machine! Currently I am using: `python x.py doc --stage 0 src/libstd` but that gives me some `unrecognized intrinsic` errors. Advice is always welcome :)

closes rust-lang#32626
  • Loading branch information
Centril authored Sep 14, 2019
2 parents 4576668 + b3b6713 commit c69a9f0
Showing 1 changed file with 46 additions and 0 deletions.
46 changes: 46 additions & 0 deletions src/libstd/time.rs
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,30 @@ pub use core::time::Duration;
/// println!("{}", now.elapsed().as_secs());
/// }
/// ```
///
/// # Underlying System calls
/// Currently, the following system calls are being used to get the current time using `now()`:
///
/// | Platform | System call |
/// |:---------:|:--------------------------------------------------------------------:|
/// | Cloud ABI | [clock_time_get (Monotonic Clock)] |
/// | SGX | [`insecure_time` usercall]. More information on [timekeeping in SGX] |
/// | UNIX | [clock_time_get (Monotonic Clock)] |
/// | Darwin | [mach_absolute_time] |
/// | VXWorks | [clock_gettime (Monotonic Clock)] |
/// | WASI | [__wasi_clock_time_get (Monotonic Clock)] |
/// | Windows | [QueryPerformanceCounter] |
///
/// [QueryPerformanceCounter]: https://docs.microsoft.com/en-us/windows/win32/api/profileapi/nf-profileapi-queryperformancecounter
/// [`insecure_time` usercall]: https://edp.fortanix.com/docs/api/fortanix_sgx_abi/struct.Usercalls.html#method.insecure_time
/// [timekeeping in SGX]: https://edp.fortanix.com/docs/concepts/rust-std/#codestdtimecode
/// [__wasi_clock_time_get (Monotonic Clock)]: https://github.com/CraneStation/wasmtime/blob/master/docs/WASI-api.md#clock_time_get
/// [clock_gettime (Monotonic Clock)]: https://linux.die.net/man/3/clock_gettime
/// [mach_absolute_time]: https://developer.apple.com/library/archive/documentation/Darwin/Conceptual/KernelProgramming/services/services.html
/// [clock_time_get (Monotonic Clock)]: https://github.com/NuxiNL/cloudabi/blob/master/cloudabi.txt
///
/// **Disclaimer:** These system calls might change over time.
///
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[stable(feature = "time2", since = "1.8.0")]
pub struct Instant(time::Instant);
Expand Down Expand Up @@ -114,6 +138,28 @@ pub struct Instant(time::Instant);
/// }
/// }
/// ```
///
/// # Underlying System calls
/// Currently, the following system calls are being used to get the current time using `now()`:
///
/// | Platform | System call |
/// |:---------:|:--------------------------------------------------------------------:|
/// | Cloud ABI | [clock_time_get (Realtime Clock)] |
/// | SGX | [`insecure_time` usercall]. More information on [timekeeping in SGX] |
/// | UNIX | [clock_gettime (Realtime Clock)] |
/// | DARWIN | [gettimeofday] |
/// | VXWorks | [clock_gettime (Realtime Clock)] |
/// | WASI | [__wasi_clock_time_get (Realtime Clock)] |
/// | Windows | [GetSystemTimeAsFileTime] |
///
/// [clock_time_get (Realtime Clock)]: https://github.com/NuxiNL/cloudabi/blob/master/cloudabi.txt
/// [gettimeofday]: http://man7.org/linux/man-pages/man2/gettimeofday.2.html
/// [clock_gettime (Realtime Clock)]: https://linux.die.net/man/3/clock_gettime
/// [__wasi_clock_time_get (Realtime Clock)]: https://github.com/CraneStation/wasmtime/blob/master/docs/WASI-api.md#clock_time_get
/// [GetSystemTimeAsFileTime]: https://docs.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimeasfiletime
///
/// **Disclaimer:** These system calls might change over time.
///
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[stable(feature = "time2", since = "1.8.0")]
pub struct SystemTime(time::SystemTime);
Expand Down

0 comments on commit c69a9f0

Please sign in to comment.