Change:
///    } /// } /// ``` <ins> /// /// # 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. /// </ins> #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] #[stable(feature = "time2", since = "1.8.0")] pub struct SystemTime(time::SystemTime);

Discussion:
talks about what it uses to query time on the various platforms, but that is an implementation detail. The API documentation should define minimum precision guarantees for these APIs, so the user can make an informed decision whether using these APIs will provide sufficient precision for their use case on all supported platforms. For example, if a user wanted to use these APIs to limit framerate in a video game, second precision wouldn't cut it, but millisecond precision should be sufficient for most cases, so if these APIs guarantee at least millisecond precision, then they can be used for this purpose.
Should we guarantee precision or document which system APIs these things use?
I definitely agree this should be documented, at least for major platforms. If it's not documented, all you can do is test the precision, but then you have to make assumptions about future systems. If we guarantee a precision, that leaves open the question of what to do for a system that can't support such a precision. Panic?
We already can't guarantee any particular precision. Linux for example runs on processors with a wide variety of timing hardware, with all sorts of different precisions.
Perhaps we need another API to query the precision.
If it's not possible to provide any guarantees, we should at least document the precision for major (tier-1) platforms, and explicitly state that there are no guarantees for other platforms.
Does "tier-1 platform" include guest Linux on VMWare? Its clock is known to be freaky. POSIX has which return the (finest) unit of time supported by the system, but they don't guarantee measurements are that accurate. When OSs don't guarantee anything, what can Rust do? Perhaps we can just add a wrapper of these query APIs if that is convenient to somebody.
Hrrm. If truly nothing else can be done, then at least let's document the platform APIs we use for at least the major platforms, so the user doesn't have to look them up in the RFCs. That's at least more information about the precision than nothing at all.
Do we aim for at least some level of precision where possible? <sWhat is the purpose of ? Does it aim to be suitable for any kind of use?

Obviously, if it doesn't aim to be useful for anything, then it's useless.</sWell, the documentation does say it's "often useful for tasks such as measuring benchmarks or timing how long an operation takes". I guess that's something.
We aim for the highest precision available on whatever platform you're running on.
Then we could put that into the documentation. That's useful information.
I tried adding etc to libstd, only to find out the libc crate lacks ...
Triage: no changes I'm aware of.
I see that you mentioned this issue in your PR! You're still interested in picking this up?
Does the Library Team want to establish a minimum guaranteed precision for std::time APIs? Or desires to have platform-specific API calls being mentioned? Otherwise we can close this issue! I personally think that listing platform-specific APIs is not a good idea since they might change over time and are a hassle to maintain for the docs-team. I don't really think a minimum precision is required either, but can be if desired. Ps. Right now I pinged everyone of the libs team (I heard team pings don't work anymore), is there any convention to follow when wanting to get in contact with the libs team on a certain issue?
I think at the bare minimum precision with respect to reading time from the system should probably documented (or rather I don't think anyone would object to that). For example Windows you get something like 10ns precision between taking timing samples whereas on Linux it's 1ns (IIRC). The precision of will always be to the nanosecond. I think one of the main remaining questions is what the precision of is. Currently has a platform-specific representation which means that it has different precisions on different platforms, but this has been considered a bug before by a few issues here and there. I do not think we should document and/or try to guarantee the precision of while we're figuring out these bugs. We don't want the documentation to tie our hands one way or another.
Thanks for your response! So if I understood you correctly the task for this issue is: Figure out the underlying API calls for and documenting the precision for each platform. Do I understand this correctly? I am currently abroad, but I can probably create a PR for this once I get home.

I see that the current page already states that it operates on nanosecond precision, so we don't have to change it's documentation.
I believe so, yes. As usual though the documentation needs to be careful to indicate what's captured in this thread about how we call some APIs, but those APIs aren't guaranteed to be called. Additionally system configuration may mean the API calls are less precise. (etc, etc)