Clarify "system-wide" in docs for time.monotonic()

[orbisvicis]

The documentation for time.monotonic() currently states:

Changed in version 3.5: The function is now always available and always system-wide.

I didn't know what system-wide meant, and so propose expanding the documentation to:

Changed in version 3.5: The function is now always available and always system-wide, that is, the clock is the same for all processes on the system and the reference point does not change after start-up time.

Or anything equally enlightening. This would make it clear, that among other things, the delta may not be valid across reboots.

[arhadthedev]

@abalkin, @pganssle (as time experts)

[pkkm]

+1 from me. I've just spend time searching the Web and asking on IRC because I wanted to know whether it's safe to use time.monotonic() when starting connections on one thread and timing them out on another. I'd seen it described as a "system-wide" function in the docs, but I had assumed that this is some kind of CPython terminology for working in a similar way on every OS.

I think it would be good for the cross-thread and cross-process behavior of these functions to be documented in a clearer and more prominent way, rather than just being mentioned in the version change notes. Maybe something like this?

An explanation of some terminology and conventions is in order.

• The term clock scope specifies whether the values returned by a clock use the same reference point, and can be meaningfully compared, between any two processes in the system, between threads but not processes, or only within the same thread.

Functions

• time.monotonic()

  Clock scope: system.

• time.perf_counter()

  Clock scope: process on Windows XP and earlier, system everywhere else.

• time.process_time()

  Clock scope: process.

• time.thread_time()

  Clock scope: thread.

If this is too much text, then perhaps the docs could use a single suffix consistently (instead of "system-wide" and "process-wide", but "thread-specific") and define it at the top?

---

Edited to add: While we're discussing the docs of time.monotonic(), the version change notes are also unclear in a different way:

Changed in version 3.5: The function is now always available and always system-wide.
Changed in version 3.10: On macOS, the function is now system-wide.

So what about macOS on Python 3.5 to 3.9?