gh-88494: Use QueryPerformanceCounter() for time.monotonic()

[vstinner]

On Windows, time.monotonic() now uses the QueryPerformanceCounter() clock to have a resolution better than 1 us, instead of the gGetTickCount64() clock which has a resolution of 15.6 ms.

• Issue: time.monotonic() should use a different clock source on Windows #88494

---

📚 Documentation preview 📚: https://cpython-previews--116781.org.readthedocs.build/

[vstinner]

See also #115638 and issue gh-115637.

[vstinner]

Script to measure the effective clock resolution:

import time

def compute_resolution(func):
    resolution = None
    points = 0
    timeout = time.monotonic() + 1.0
    previous = func()
    while time.monotonic() < timeout or points < 3:
        for loop in range(10):
            t1 = func()
            t2 = func()
            dt = t2 - t1
            if 0 < dt:
                break
        else:
            dt = t2 - previous
            if dt <= 0.0:
                continue
        if resolution is not None:
            resolution = min(resolution, dt)
        else:
            resolution = dt
        points += 1
        previous = func()
    return resolution

def format_duration(dt):
    if dt >= 1e-3:
        return "%.0f ms" % (dt * 1e3)
    if dt >= 1e-6:
        return "%.0f us" % (dt * 1e6)
    else:
        return "%.0f ns" % (dt * 1e9)

def test_clock(name, func):
    print("%s:" % name)
    resolution = compute_resolution(func)
    print("- efffective resolution: %s" % format_duration(resolution))


clocks = ['time', 'perf_counter', 'monotonic']
for name in clocks:
    func = getattr(time, name)
    test_clock("%s()" % name, func)
    info = time.get_clock_info(name)
    print("- implementation: %s" % info.implementation)
    print("- resolution: %s" % format_duration(info.resolution))
    print()

Results before (release build):

time():
- efffective resolution: 2 ms
- implementation: GetSystemTimeAsFileTime()
- resolution: 16 ms

perf_counter():
- efffective resolution: 100 ns
- implementation: QueryPerformanceCounter()
- resolution: 100 ns

monotonic():
- efffective resolution: 15 ms
- implementation: GetTickCount64()
- resolution: 16 ms

Results after (release build):

Running Release|x64 interpreter...
time():
- efffective resolution: 1 ms
- implementation: GetSystemTimeAsFileTime()
- resolution: 16 ms

perf_counter():
- efffective resolution: 100 ns
- implementation: QueryPerformanceCounter()
- resolution: 100 ns

monotonic():
- efffective resolution: 100 ns
- implementation: QueryPerformanceCounter()
- resolution: 100 ns

monotonic() resolution changes from 15.6 ms to 100 ns: it's 156,000x more accurate than before!

[MaxShvets]

@vstinner could you, please, help me figure out why the script works this way? Specifically, by taking 10 clock readings to measure dt, don't we end up measuring resolution times 10?

[vstinner]

With precise clocks such as QueryPerformanceCounter(), you don't go into the "else" block of the "for". The "else" is only there for low-resolution clocks.

[MaxShvets]

Got it, thanks