Document minimum precision guarantees for the various std::time APIs

[crumblingstatue]

#29894 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.

[sfackler]

Should we guarantee precision or document which system APIs these things use?

[durka]

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?

[mbrubeck]

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.

[durka]

Perhaps we need another API to query the precision.

[crumblingstatue]

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.

[nodakai]

@crumblingstatue Does "tier-1 platform" include guest Linux on VMWare? Its clock is known to be freaky.

POSIX has clock_getres(3) and Win32 has QueryPerformanceFrequency 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.

[crumblingstatue]

@nodakai 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.

[crumblingstatue]

Do we aim for at least some level of precision where possible? What is the purpose of Instant? 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. Well, 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.

[sfackler]

We aim for the highest precision available on whatever platform you're running on.

[crumblingstatue]

@sfackler Then we could put that into the documentation. That's useful information.

[nodakai]

I tried adding Duration::resolution() etc to libstd, only to find out the libc crate lacks clock_getres(3)...