Python 时钟八条:monotonic、sleep 与 wait 量出的三种毫秒
我把同一段「等一毫秒」的代码换了五种写法,在一台 Windows 11 build 26300 的机器上各跑二十到三十遍,用 CPython 3.13.14 记录实际耗时。结果不是「有点误差」,是同一个意图拿到了相差十倍的数字:time.sleep(0.001) 中位 1.56 毫秒,threading.Event().wait(0.001) 中位 15.62 毫秒,kernel32.Sleep(1) 中位 15.33 毫秒。
这篇文章不讨论「哪个计时函数更快」,而是回答一个更靠前的问题:你用来测时间的那把尺子,本身准不准、量的是谁的时间。八条结论全部可以在你自己的机器上复现,代码在文末,报错原文全部来自本机实际抛出的文本。
TL;DR:测耗时用 perf_counter_ns(),测截止时间用 monotonic(),只统计 CPU 用 process_time(),三者不能互换;get_clock_info().resolution 报的数字不是实际粒度;短睡眠请按截止时间循环,不要指望单次 sleep 精确。
get_clock_info("process_time").resolution报1e-07,实测量子是0.015625秒(15.625 毫秒),差五个数量级- 用
process_time()量 1 毫秒和 5 毫秒的忙循环,五次采样全部读回 0.0 process_time()在sleep(1.0)期间增量是0.000000,perf_counter()同期是1.000696- 等 1 毫秒:
time.sleep中位 1.56 毫秒,Event.wait中位 15.62 毫秒,最快与最慢相差 15 倍 - 调用
timeBeginPeriod(1)后两者同时塌到 1–2 毫秒,timeEndPeriod(1)后Event.wait回到 14.66 毫秒,这是根因证据 - 一百次
sleep(0.01)实付 1.093 秒(多 9.3%),两百次sleep(0.001)实付 0.280 秒(多 40.2%) - epoch 尺度下
time.time()的 float 步长固定是 2⁻²² 秒(238 纳秒),20 万次背靠背调用只有 171,695 个不同值 perf_counter()与monotonic()在 3.13 上是同一只钟;Windows 上还没有time.CLOCK_*,clock_gettime直接报 AttributeError
八个现象摆在一张表里
| 现象 | 通常的假设 | 本机实测(Win11 26300 / CPython 3.13.14) |
|---|---|---|
process_time 的粒度 | 分辨率字段写的 100 纳秒 | 量子 15.625 毫秒,1 毫秒忙循环读回 0.0 |
process_time 量等待 | 能代表一次请求的耗时 | 睡 1 秒,增量 0.000000 |
| 等 1 毫秒 | 就是 1 毫秒 | time.sleep 1.56 毫秒,Event.wait 15.62 毫秒 |
| 等待的稳定性 | 误差在几微秒内 | Event.wait(0.001) 最快 1.14、最慢 17.63 毫秒 |
| 循环睡眠的精度 | 误差不累积 | 两百次 1 毫秒多付 40.2% |
time.time() 的精度 | 微秒级 | float 步长 238 纳秒,14% 的调用与前一次同值 |
perf_counter 与 monotonic | 两个独立的钟 | 同一个 QueryPerformanceCounter() |
time.time() 会不会倒退 | 单调递增 | adjustable=True,文档写明可能返回更小值 |
一、get_clock_info 报的分辨率,不是它实际跳动的步长
先看五个时钟的自述。这段代码不需要任何第三方库:
import time
for name in ("time", "monotonic", "perf_counter", "process_time", "thread_time"):
ci = time.get_clock_info(name)
print(f"{name:13s} {ci.implementation:32s} mono={ci.monotonic} adj={ci.adjustable} res={ci.resolution}")
本机输出:
time GetSystemTimePreciseAsFileTime() mono=False adj=True res=1e-07
monotonic QueryPerformanceCounter() mono=True adj=False res=1e-07
perf_counter QueryPerformanceCounter() mono=True adj=False res=1e-07
process_time GetProcessTimes() mono=True adj=False res=1e-07
thread_time GetThreadTimes() mono=True adj=False res=1e-07
五个时钟,五个一模一样的 1e-07。这明显不可能是真的:GetProcessTimes 在 Windows 上由调度器的时钟中断驱动,怎么可能每 100 纳秒更新一次。于是我写了一个忙循环去量它的实际步长——不停读值,只记录「值变了」那一刻的增量,最后去重打印:
def quantum(fn, iterations=3_000_000):
prev = fn()
deltas = []
for _ in range(iterations):
cur = fn()
if cur != prev:
deltas.append(cur - prev)
prev = cur
return sorted(set(deltas))
跑了三百万次迭代(约 1.2 秒),process_time 一共变了 77 次,增量只有一个值:0.015625。thread_time 同样,70 次变化,唯一的增量也是 0.015625。也就是 1/64 秒,正好是 Windows 默认时钟中断的 15.625 毫秒。
对比一下 time.time() 在同样条件下的最小增量:2.384185791015625e-07,也就是 2⁻²² 秒。这个数字不是系统的精度,是 float64 在 1.79e9 这个量级上能表示的最小台阶——后面第六条会单独说。
结论很直接:resolution 描述的是「这个返回值能表示到多细」,不是「它多久更新一次」。对 process_time 和 thread_time,这两个数字相差 156,250 倍。
再补一刀。用 process_time 去量短忙循环,括号里第一个数字是 process_time 的增量,第二个是 perf_counter 的:
target=1 ms -> (0.0, 0.001099) (0.0, 0.001173) (0.0, 0.001039) (0.0, 0.001020) (0.0, 0.001020)
target=5 ms -> (0.0, 0.005028) (0.0, 0.005097) (0.0, 0.005089) (0.0, 0.005305) (0.0, 0.005026)
target=10 ms -> (0.0, 0.010195) (0.0, 0.010060) (0.015625, 0.010045) (0.0, 0.010036) (0.015625, 0.010078)
五次采样,1 毫秒和 5 毫秒两档 process_time 全部读回 0.0;10 毫秒那档只有两次跨过 tick。如果你在写一个「单次请求 CPU 时间」的埋点,而请求只花几毫秒,这个字段会稳定地记 0——日志看起来像「几乎没消耗 CPU」,其实只是没跨过那个 15.625 毫秒的台阶。
二、process_time 量不到等待:睡一秒,增量为零
官方文档对 process_time() 的定义是「当前进程的系统 CPU 时间与用户 CPU 时间之和」,并明确写了一句 It does not include time elapsed during sleep.
这句话看着无害,直到你用错地方。实测:
sleep(1.0) 期间:process_time 增量 = 0.000000,perf_counter 增量 = 1.000696
忙循环 0.73 秒:process_time = 0.734375,perf_counter = 0.731267
0.734375 这个数值得盯一眼:它等于 47 × 0.015625,正好 47 个 tick。忙循环的真实耗时是 0.731 秒,process_time 报 0.734 秒,误差 3 毫秒——在秒级测量里这无所谓,在毫秒级测量里这就是全部误差。
所以判断标准只有一条:你测的是「这段代码占了多少 CPU」还是「用户等了多久」。查询数据库、等网络、等锁、等磁盘,全都是第二种,用 process_time 会得到一个漂亮且完全错误的低数字。反过来说,如果你要判断一个进程是不是在空转,process_time 才是对的:它不会被十分钟的阻塞调用污染。
三、同样等一毫秒:一个 1.5 毫秒,一个 15.6 毫秒
这是本轮最值钱的一条。三次调用,意图完全相同——「等 1 毫秒」:
| 写法 | 最快 | 中位 | 最慢 |
|---|---|---|---|
time.sleep(0.001) | 1.076 ms | 1.564 ms | 2.329 ms |
kernel32.Sleep(1)(ctypes) | 1.375 ms | 15.326 ms | 16.881 ms |
threading.Event().wait(0.001) | 1.140 ms | 15.620 ms | 17.630 ms |
把请求改成 10 毫秒,time.sleep 老老实实 10.33 毫秒,而 Sleep(10) 是 16.84 毫秒,Event.wait(0.010) 是 16.74 毫秒——仍然被抬到下一个 15.625 毫秒的边界。
注意 Event.wait 的最快值 1.14 毫秒和中位 15.62 毫秒:同一个调用,落在 tick 边界附近就是 1 毫秒,落在边界刚过就是 17 毫秒。这种抖动比系统性偏慢更难查,因为它在采样里会呈现成「偶尔很快」,让人以为是偶发噪声。
这对代码意味着什么?一个轮询循环里写 event.wait(0.001) 做「1 毫秒退避」,实际退避是 15 毫秒起步;批量跑起来更明显:
500 ms 内完成 46 次 Event.wait(0.001),平均 10.886 ms/次(名义 1 ms)
500 ms 内完成 319 次 time.sleep(0.001),平均 1.568 ms/次
同一段时间,一个只能转 46 圈,一个能转 319 圈。如果你的 worker 用 Condition.wait(timeout=0.001) 做轮询、用 Queue.get(timeout=0.001) 做探测,这些地方都在按 15.6 毫秒的节拍走,而 time.sleep 那条路不是。
四、把系统计时器分辨率调高,两个数字一起塌下来
上面只是相关性。要坐实根因,得动一下变量:Windows 允许进程把系统计时器分辨率从默认的 15.625 毫秒改成 1 毫秒(timeBeginPeriod)。改完再测同一批调用,前后对比:
| 写法 | 默认分辨率 | timeBeginPeriod(1) 后 | timeEndPeriod(1) 后 |
|---|---|---|---|
time.sleep(0.001) | 1.564 ms | 1.566 ms | 未测 |
kernel32.Sleep(1) | 15.326 ms | 1.989 ms | 未测 |
Event.wait(0.001) | 15.620 ms | 1.107 ms | 14.662 ms |
Event.wait(0.010) | 16.742 ms | 10.383 ms | 未测 |
三个事实同时成立:第一,Sleep(1) 和 Event.wait(1ms) 的动作完全跟着分辨率走;第二,time.sleep 一动不动——它根本不走这条路径;第三,timeEndPeriod 之后立刻回弹。
这和官方文档能对上。微软的 Sleep 文档写的是「系统时钟以固定速率跳,如果 dwMilliseconds 小于系统时钟的分辨率,线程可能睡得比要求的更短;如果大于一个 tick 小于两个 tick,等待就落在这两个 tick 之间」,并建议需要更精确时调用 timeBeginPeriod。这里有个细节值得记下来:文档说「可能更短」,我实测是「更长」——方向相反,但都指向同一件事,这个参数的单位是 tick 数,不是精确时间。
Python 这一侧也能对上。time.sleep 的文档在 3.11 的变更里写着 On Windows, a waitable timer is now used,Windows 实现一节又写「Windows 10 及以上使用高分辨率计时器,分辨率 100 纳秒」。也就是说,3.11 之后的 time.sleep 绕开了系统计时器中断;而 Event.wait、Condition.wait、Queue.get(timeout=) 走的是锁的定时等待,仍然受系统分辨率约束。同一个标准库里,两条等待路径的精度差了十倍。
五、sleep 会累积:一百次 10 毫秒,实付 1.09 秒
单次睡眠「至少」是 N 毫秒,这个「至少」会累加。实测:
100 次 sleep(0.01):名义 1.000000,实际 1.093047,多 9.30%
200 次 sleep(0.001):名义 0.200000,实际 0.280489,多 40.24%
从单次数据能看出钱花在哪:sleep(0.01) 的中位是 10.347 毫秒,每次多付约 0.35 毫秒;sleep(0.001) 的中位是 1.564 毫秒,每次多付约 0.56 毫秒。睡得越短,相对误差越大,因为开销是固定的,而被除数很小。
这对限流器、心跳、轮询都是实际影响。一个「每秒 100 次」的令牌补充循环,如果写成 for _ in range(100): time.sleep(0.01),实际周期是 1.09 秒而不是 1 秒;跑一小时就差了两分多钟,而且它不会报错,只会让下游觉得你补得慢。
正确的写法是按截止时间睡,让误差自我抵消:
import time
def sleep_until(deadline):
while True:
left = max(0.0, deadline - time.monotonic())
if left == 0.0:
return
time.sleep(left)
t0 = time.monotonic()
for i in range(100):
sleep_until(t0 + (i + 1) * 0.01)
这样每一轮都会把前面多睡的时间扣掉。本机用这个写法跑 100 轮 10 毫秒,总时长是 1.0003 秒,误差从 9.3% 降到 0.03%。
六、float 只给你 238 纳秒,20 万次调用有 14% 是同值
time.time() 返回 float。epoch 秒现在大约是 1.795e9,换算成二进制需要 31 位整数部分,float64 的 52 位尾数只剩 21 位给小数——于是最小台阶就是 2⁻²² 秒。
实测两次都印证了:
忙循环 0.5 秒内的最小正增量:2.384185791015625e-07(共 258 种不同增量,全是它的整数倍)
200000 次背靠背 time.time():171,695 个不同值(85.8%)
200000 次背靠背 time.time_ns():200,000 个不同值(100%)
50000 次 datetime.now():40,586 个不同值(81.2%)
time_ns() 每次都不同,说明底层分辨率够;丢精度的是 float 这一步。毫秒级记录无所谓,但如果你拿 time.time() 当唯一键、做微秒级排序,或者用 == 比较两个时间戳是否相同,就会撞上这种「两个不同时刻,同一个 float」。
用 time_ns()、monotonic_ns()、perf_counter_ns() 就没有这个问题,它们返回 int。顺带一个容易忽略的坑:datetime.fromtimestamp(0.9999999) 在本机返回 1970-01-01 08:00:01,不是 08:00:00.999999——它按四舍五入进位,跨秒边界时会跳到下一秒。
七、perf_counter 和 monotonic 在 3.13 上是同一只钟
看第一条的 implementation 列,monotonic 和 perf_counter 都是 QueryPerformanceCounter()。这不是巧合,perf_counter() 的文档在 3.13 的变更里写着:Use the same clock as time.monotonic().
实测两只钟在 2 秒睡眠上的读数也几乎重合:monotonic 走 2.000646,perf_counter 走 2.000665,差 19 微秒,来自两次读取之间的时间差。3 秒对比 time.time() 与 perf_counter 的漂移是 3 微秒。
那为什么文档要把它们分成两个函数?因为这是平台契约,不是实现事实。文档给 monotonic() 写的是「不能被设置、不受系统时钟更新影响」,给 perf_counter() 写的是「可得最高分辨率、包含睡眠时间」。在 CPython 的某些平台和版本上,这两条会落到不同的底层时钟;只在 3.13 的 Windows 上才恰好是同一只。
实践含义:不要把「反正这里两个一样」写进设计。要测时长,用 perf_counter;要算超时截止时间,用 monotonic。两者混用不会在本机出错,但换到别的解释器或平台就可能变味。
另外,Windows 上根本不存在 time.CLOCK_* 系列常量,time.clock_gettime 这个属性也不存在:
hasattr(time, "CLOCK_MONOTONIC") = False
dir(time) 里的 CLOCK_ 常量 = []
time.clock_gettime -> AttributeError
文档对 clock_gettime、clock_getres 标注的是 Availability: Unix。所以从 Linux 抄过来的 time.clock_gettime(time.CLOCK_MONOTONIC) 在 Windows 上第一行就崩,而它崩的方式是属性不存在,不是「精度不同」。
八、time.time 可以被回拨,而且它的 Windows 时钟源刚换过
get_clock_info("time") 的 adjustable 是 True。文档对这个字段的解释是「时钟能否向前或向后跳变」,并特意补了一句 Does not refer to gradual NTP rate adjustments——也就是说,adjustable=False 不代表 NTP 的慢速校正不存在,只代表这个钟不能被你一键改掉。
time.time() 的文档则直接写明了风险:While this function normally returns non-decreasing values, it can return a lower value than a previous call if the system clock has been set back between the two calls.
这意味着任何 t1 - t0 的写法,只要两端都是 time.time(),理论上就可能得到负数。我没有实测改系统钟(需要管理员权限,也会影响这台机器上的其他任务),所以这一条按官方口径写,不冒充实验结论。
但有一个变化我可以实测确认:time.time() 在 Windows 上的时钟源,3.13 换过。文档的变更记录写着 Changed in version 3.13: On Windows, calls GetSystemTimePreciseAsFileTime() instead of GetSystemTimeAsFileTime(),而本机的 implementation 字段正是 GetSystemTimePreciseAsFileTime()。
这条为什么重要?因为网上流传很广的一句「Windows 上 time.time() 只有 15.6 毫秒精度」,在 3.13 上已经不成立了。我实测的最小增量是 238 纳秒——限制它的是 float,不是系统时钟。老结论不是错,是过期了;判断依据应该是 get_clock_info() 的 implementation,而不是记忆里的数字。
Troubleshooting:三个真实报错
这三个都是我在写测试脚本时实际撞出来的,报错原文照抄。
报错一:ValueError: sleep length must be non-negative
原因:把「剩余时间」直接传给了 sleep()。截止时间已经过去时,deadline - now 是负数。这在重试退避里很常见——第一次退避没做完,第二次算出来的剩余时间是负的。
改法:先夹到 0,再判断是否还需要睡。
left = deadline - time.monotonic()
if left == max(0.0, left) and left:
time.sleep(left)
报错二:TypeError: 'str' object cannot be interpreted as an integer
原因:sleep() 的参数来自配置文件或环境变量,值是字符串 "1" 或 "0.5"。sleep 不会替你转换,直接抛类型错误。同一条也适用于 Event.wait("0.001")。
改法:入口处统一 float(...),并且校验非负;负数会撞上第一条的 ValueError,两种错误藏在同一个字段里。
报错三:AttributeError: module 'time' has no attribute 'clock_gettime'
原因:从 Linux 代码里继承了 time.clock_gettime(time.CLOCK_MONOTONIC)。Windows 没有这组接口,也没有 CLOCK_* 常量。
改法:跨平台代码只用 time.monotonic() / monotonic_ns() 这一层封装;确实需要 CLOCK_* 的平台特定逻辑,用 hasattr(time, "CLOCK_MONOTONIC") 显式分支,而不是让它在运行时崩。
一份可以直接抄的测时代码
把上面的结论压成四条实践规则,对应四个函数:
import time
def elapsed_ms(fn):
"""测一段代码花了多久:用 perf_counter_ns,避开 float 精度"""
t0 = time.perf_counter_ns()
result = fn()
return (time.perf_counter_ns() - t0) / 1e6, result
def cpu_ms(fn):
"""只测 CPU 时间:等待、睡眠、阻塞 IO 都不计入"""
t0 = time.process_time_ns()
result = fn()
return (time.process_time_ns() - t0) / 1e6, result
def sleep_until(deadline_monotonic):
"""按截止时间睡,误差不累积"""
while True:
left = max(0.0, deadline_monotonic - time.monotonic())
if left == 0.0:
return
time.sleep(left)
def wait_or_poll(cond, timeout):
"""需要毫秒级轮询时,别用 Condition.wait,用 sleep 自己控节奏"""
deadline = time.monotonic() + timeout
while not cond():
left = deadline - time.monotonic()
if left == max(0.0, left) and left:
time.sleep(left)
else:
return False
return True
选择顺序:先问「我在量什么」。量用户等待,用 perf_counter_ns;量 CPU 占用,用 process_time_ns;量是否超时,用 monotonic 算截止时间;需要等待,优先 time.sleep,因为它在本机比条件变量精确十倍。
本文的边界
- 只测 Windows 11 build 26300 + CPython 3.13.14。Linux 与 macOS 的结论会不同:Linux 上
time.sleep走clock_nanosleep,CLOCK_MONOTONIC存在,time.time()的精度取决于clock_getres(CLOCK_REALTIME) - 系统计时器分辨率可能被别的进程悄悄改过(浏览器、游戏、音视频软件都会调
timeBeginPeriod),所以同一台机器不同时刻的Event.wait数字可能不一样,这也是我每组跑 20 到 30 次取中位的原因 - 没有实测修改系统时钟,第八条里「可能返回更小值」引用的是官方文档口径,不是本机实验
- 睡眠与等待只测了毫秒级;秒级、亚毫秒级和跨进程共享内存的等待没有覆盖
- 没有涉及 asyncio 的
call_later与事件循环时钟,那是另一条路径
同一类「返回值不等于结果」的坑,我另外测过几个相邻的层:用 profiler 读数而不是时钟本身判断热点,会踩八个剖析读数错误;超时与取消在 asyncio 里的语义是六个静默失效;而「时刻」这一侧的比较与夏令时问题,在zoneinfo 的六处坑里单独写过。这篇只管「时长」这一侧。
本文不含任何联盟推广链接。
FAQ
Q:time.perf_counter() 和 time.monotonic() 到底该用哪个?
测「这段代码花了多久」用 perf_counter(),它的文档承诺是最高可用分辨率;算「什么时候超时」用 monotonic(),它的承诺是不可倒退。在 3.13 的 Windows 上两者是同一个底层时钟,所以本机互换不会出错——但换平台就可能不同,不要把这个巧合写进设计。
Q:既然 Event.wait 要 15 毫秒,那所有 Queue.get(timeout=0.001) 都该改成 sleep 轮询?
不该。带超时的阻塞等待本来就不是精密计时器,它的语义是「等到有数据或超时」,不是「精确睡 N 毫秒」。只有当你的逻辑依赖「1 毫秒后立刻回来」时,才需要换成 time.sleep 自己控节奏。反过来,忙等会烧 CPU,也不该拿来替代阻塞。
Q:为什么同一台机器上两次测出来的 Event.wait 差别很大?
因为系统计时器分辨率是全局的,任何进程调用 timeBeginPeriod 都会把它改掉;另外你的调用落在 tick 边界的哪一侧也决定了这次是 1 毫秒还是 17 毫秒。要稳定复现,先固定分辨率(或用 clockres 之类工具看当前值),并且每组多跑几次取中位,别看单次。
Q:process_time 既然量不到等待,为什么还留着它?
因为它恰好能回答另一个问题:这段代码是真的在算,还是在等。一个进程占了多少 CPU、一段解析逻辑有没有空转、批处理是不是被 IO 拖住——这些用 perf_counter 会被等待污染,用 process_time 才干净。前提是你知道它按 15.625 毫秒跳,别拿它测短请求。
👉 立即参与小米 MiMo 开放平台:国内领先的 AI 大模型开放平台,高性价比推理服务
👉 立即参与阿里云 AI:汇集爆款 AI 产品,热门模型专属权益优惠券助力企业创新加速
📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点,专注于效率工具与 SaaS 真实评测
🔗 精选推荐工具
使用以下链接支持我们持续产出高质量内容(点击可直接前往购买):
作为亚马逊联盟会员,符合条件的购买会为我们带来佣金,不会增加你的购买成本。