@abalkin, @pganssle (as time experts)

+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 it's 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 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?