time.get_clock_info(name)

获取指定时钟的信息。支持的时钟名称：

• "clock": time.clock()
• "monotonic": time.monotonic()
• "perf_counter": time.perf_counter()
• "process_time": time.process_time()
• "time": time.time()

返回一个 time.clock_info 对象，该对象具有以下属性：

• implementation (str)：底层操作系统函数的名称。示例："QueryPerformanceCounter()"、"clock_gettime(CLOCK_REALTIME)"。
• monotonic (bool)：如果时钟不能倒退，则为 True。
• adjustable (bool)：如果时钟可以自动（例如，通过 NTP 守护程序）或手动（通过系统管理员）更改，则为 True，否则为 False
• resolution (float)：时钟的秒级分辨率。

time.monotonic()

单调时钟，即不能倒退。它不受系统时钟更新的影响。返回值的参考点是未定义的，因此只有连续调用结果之间的差值有效，并且表示秒数。

在早于 Vista 的 Windows 版本上，time.monotonic() 会检测 GetTickCount() 整数溢出（32 位，49.7 天后翻转）。每次检测到溢出时，它会将内部纪元（参考时间）增加 2³²。纪元存储在进程局部状态中，因此在运行超过 49 天的两个 Python 进程中，time.monotonic() 的值可能不同。在更新的 Windows 版本和其他操作系统上，time.monotonic() 是系统范围的。

可用性：Windows、Mac OS X、Linux、FreeBSD、OpenBSD、Solaris。在 GNU/Hurd 上不可用。

伪代码[2]

if os.name == 'nt':
    # GetTickCount64() requires Windows Vista, Server 2008 or later
    if hasattr(_time, 'GetTickCount64'):
        def monotonic():
            return _time.GetTickCount64() * 1e-3
    else:
        def monotonic():
            ticks = _time.GetTickCount()
            if ticks < monotonic.last:
                # Integer overflow detected
                monotonic.delta += 2**32
            monotonic.last = ticks
            return (ticks + monotonic.delta) * 1e-3
        monotonic.last = 0
        monotonic.delta = 0

elif sys.platform == 'darwin':
    def monotonic():
        if monotonic.factor is None:
            factor = _time.mach_timebase_info()
            monotonic.factor = timebase[0] / timebase[1] * 1e-9
        return _time.mach_absolute_time() * monotonic.factor
    monotonic.factor = None

elif hasattr(time, "clock_gettime") and hasattr(time, "CLOCK_HIGHRES"):
    def monotonic():
        return time.clock_gettime(time.CLOCK_HIGHRES)

elif hasattr(time, "clock_gettime") and hasattr(time, "CLOCK_MONOTONIC"):
    def monotonic():
        return time.clock_gettime(time.CLOCK_MONOTONIC)

在 Windows 上，不使用 QueryPerformanceCounter()，即使它的分辨率优于 GetTickCount()。它不可靠，问题太多。

time.perf_counter()

具有最高可用分辨率的性能计数器，用于测量短持续时间。它包括休眠期间经过的时间，并且是系统范围的。返回值的参考点是未定义的，因此只有连续调用结果之间的差值有效，并且表示秒数。

它在所有平台上都可用。

伪代码

if os.name == 'nt':
    def _win_perf_counter():
        if _win_perf_counter.frequency is None:
            _win_perf_counter.frequency = _time.QueryPerformanceFrequency()
        return _time.QueryPerformanceCounter() / _win_perf_counter.frequency
    _win_perf_counter.frequency = None

def perf_counter():
    if perf_counter.use_performance_counter:
        try:
            return _win_perf_counter()
        except OSError:
            # QueryPerformanceFrequency() fails if the installed
            # hardware does not support a high-resolution performance
            # counter
            perf_counter.use_performance_counter = False
    if perf_counter.use_monotonic:
        # The monotonic clock is preferred over the system time
        try:
            return time.monotonic()
        except OSError:
            perf_counter.use_monotonic = False
    return time.time()
perf_counter.use_performance_counter = (os.name == 'nt')
perf_counter.use_monotonic = hasattr(time, 'monotonic')

time.process_time()

当前进程的系统和用户 CPU 时间之和。它不包括休眠期间经过的时间。它按定义是进程范围的。返回值的参考点是未定义的，因此只有连续调用结果之间的差值有效。

它在所有平台上都可用。

伪代码[2]

if os.name == 'nt':
    def process_time():
        handle = _time.GetCurrentProcess()
        process_times = _time.GetProcessTimes(handle)
        return (process_times['UserTime'] + process_times['KernelTime']) * 1e-7
else:
    try:
        import resource
    except ImportError:
        has_resource = False
    else:
        has_resource = True

    def process_time():
        if process_time.clock_id is not None:
            try:
                return time.clock_gettime(process_time.clock_id)
            except OSError:
                process_time.clock_id = None
        if process_time.use_getrusage:
            try:
                usage = resource.getrusage(resource.RUSAGE_SELF)
                return usage[0] + usage[1]
            except OSError:
                process_time.use_getrusage = False
        if process_time.use_times:
            try:
                times = _time.times()
                cpu_time = times.tms_utime + times.tms_stime
                return cpu_time / process_time.ticks_per_seconds
            except OSError:
                process_time.use_getrusage = False
        return _time.clock()
    if (hasattr(time, 'clock_gettime')
        and hasattr(time, 'CLOCK_PROF')):
        process_time.clock_id = time.CLOCK_PROF
    elif (hasattr(time, 'clock_gettime')
          and hasattr(time, 'CLOCK_PROCESS_CPUTIME_ID')):
        process_time.clock_id = time.CLOCK_PROCESS_CPUTIME_ID
    else:
        process_time.clock_id = None
    process_time.use_getrusage = has_resource
    process_time.use_times = hasattr(_time, 'times')
    if process_time.use_times:
        # sysconf("SC_CLK_TCK"), or the HZ constant, or 60
        process_time.ticks_per_seconds = _times.ticks_per_seconds

time.time()

系统时间通常是民用时间。它按定义是系统范围的。它可以由系统管理员手动设置，或由 NTP 守护程序自动设置。

它在所有平台上都可用，并且不会失败。

伪代码[2]

if os.name == "nt":
    def time():
        return _time.GetSystemTimeAsFileTime()
else:
    def time():
        if hasattr(time, "clock_gettime"):
            try:
                return time.clock_gettime(time.CLOCK_REALTIME)
            except OSError:
                # CLOCK_REALTIME is not supported (unlikely)
                pass
        if hasattr(_time, "gettimeofday"):
            try:
                return _time.gettimeofday()
            except OSError:
                # gettimeofday() should not fail
                pass
        if hasattr(_time, "ftime"):
            return _time.ftime()
        else:
            return _time.time()

time.sleep()

暂停执行给定的秒数。实际的暂停时间可能小于请求的时间，因为任何捕获到的信号都会在执行该信号的捕获例程后终止 time.sleep()。此外，由于系统中其他活动的调度，暂停时间可能比请求的时间任意延长。

伪代码[2]

try:
    import select
except ImportError:
    has_select = False
else:
    has_select = hasattr(select, "select")

if has_select:
    def sleep(seconds):
        return select.select([], [], [], seconds)

elif hasattr(_time, "delay"):
    def sleep(seconds):
        milliseconds = int(seconds * 1000)
        _time.delay(milliseconds)

elif os.name == "nt":
    def sleep(seconds):
        milliseconds = int(seconds * 1000)
        win32api.ResetEvent(hInterruptEvent);
        win32api.WaitForSingleObject(sleep.sigint_event, milliseconds)

    sleep.sigint_event = win32api.CreateEvent(NULL, TRUE, FALSE, FALSE)
    # SetEvent(sleep.sigint_event) will be called by the signal handler of SIGINT

elif os.name == "os2":
    def sleep(seconds):
        milliseconds = int(seconds * 1000)
        DosSleep(milliseconds)

else:
    def sleep(seconds):
        seconds = int(seconds)
        _time.sleep(seconds)

time.clock()

在 Unix 上，返回当前处理器时间作为以秒表示的浮点数。它按定义是进程范围的。分辨率，以及“处理器时间”含义的精确定义，取决于同名 C 函数的定义，但在任何情况下，这都是用于基准测试 Python 或计时算法的函数。

在 Windows 上，此函数返回自首次调用此函数以来经过的挂钟秒数，作为浮点数，基于 Win32 函数 QueryPerformanceCounter()。分辨率通常优于一微秒。它是系统范围的。

伪代码[2]

if os.name == 'nt':
    def clock():
        try:
            return _win_perf_counter()
        except OSError:
            # QueryPerformanceFrequency() fails if the installed
            # hardware does not support a high-resolution performance
            # counter
            pass
        return _time.clock()
else:
    clock = _time.clock

一个带有标志的函数：time.monotonic(fallback=True)

• time.monotonic(fallback=True) 在没有单调时钟可用或单调时钟失败时回退到系统时间。
• 如果单调时钟失败，time.monotonic(fallback=False) 会引发 OSError；如果系统不提供单调时钟，则会引发 NotImplementedError

作为调用者中的常量传递的关键字参数通常是糟糕的 API。

为函数引发 NotImplementedError 在 Python 中并不常见，应避免。

一个 time.monotonic() 函数，无标志

time.monotonic() 返回 (time: float, is_monotonic: bool)。

另一种方法是使用函数属性：time.monotonic.is_monotonic。在首次调用 time.monotonic() 之前，属性值将为 None。

mach_absolute_time

Mac OS X 提供了一个单调时钟：mach_absolute_time()。它基于自系统启动以来的绝对经过时间。它未被调整，也无法设置。

mach_timebase_info() 提供了一个分数，用于将时钟值转换为纳秒数。另请参阅 Technical Q&A QA1398。

mach_absolute_time() 在 PowerPC CPU 上休眠时停止，但在 Intel CPU 上不停止：mach_absolute_time() 在 i386/ppc 上的不同行为。

CLOCK_MONOTONIC, CLOCK_MONOTONIC_RAW, CLOCK_BOOTTIME

CLOCK_MONOTONIC 和 CLOCK_MONOTONIC_RAW 表示自某个未指定起点以来的单调时间。它们无法设置。可以使用 clock_getres() 读取分辨率。

文档：请参阅您操作系统的手册页。示例：

• FreeBSD clock_gettime() 手册页
• Linux clock_gettime() 手册页

CLOCK_MONOTONIC 至少在以下操作系统上可用：

• DragonFly BSD, FreeBSD >= 5.0, OpenBSD, NetBSD
• Linux
• Solaris

以下操作系统不支持 CLOCK_MONOTONIC：

• GNU/Hurd（参见开放问题/ clock_gettime）
• Mac OS X
• Windows

在 Linux 上，NTP 可能会调整 CLOCK_MONOTONIC 速率（倾斜），但它不能向后跳跃。

CLOCK_MONOTONIC_RAW 特定于 Linux。它类似于 CLOCK_MONOTONIC，但提供对不受 NTP 调整的原始硬件时间访问。CLOCK_MONOTONIC_RAW 需要 Linux 2.6.28 或更高版本。

Linux 2.6.39 和 glibc 2.14 引入了一个新时钟：CLOCK_BOOTTIME。CLOCK_BOOTTIME 与 CLOCK_MONOTONIC 相同，只是它还包括在暂停期间花费的任何时间。另请阅读 Waking systems from suspend（2011 年 3 月）。

机器暂停时 CLOCK_MONOTONIC 停止。

自 Linux 2.6.32 起，Linux 还提供了 CLOCK_MONOTONIC_COARSE。它类似于 CLOCK_MONOTONIC，精度较低但速度更快。

如果系统不支持指定的时钟，即使标准 C 库支持，clock_gettime() 也会失败。例如，CLOCK_MONOTONIC_RAW 需要内核版本 2.6.28 或更高版本。

Windows: QueryPerformanceCounter

高分辨率性能计数器。它是单调的。计数器的频率可以使用 QueryPerformanceFrequency() 读取。分辨率是 1 / QueryPerformanceFrequency()。

它具有更高的分辨率，但长期精度低于 GetTickCount() 和 timeGetTime() 时钟。例如，与低精度时钟相比，它会漂移。

文档

• MSDN: QueryPerformanceCounter() 文档
• MSDN: QueryPerformanceFrequency() 文档

QueryPerformanceCounter 使用的硬件时钟

• Windows XP：Intel 处理器上的 RDTSC 指令，时钟频率是处理器频率（200 MHz 到 3 GHz 之间，现在通常大于 1 GHz）。
• Windows 2000：ACPI 电源管理计时器，频率 = 3,549,545 Hz。可以通过 boot.ini 中的“/usepmtimer”标志强制使用。

QueryPerformanceFrequency() 只应调用一次：系统运行时频率不会改变。如果安装的硬件不支持高分辨率性能计数器，它将失败。

QueryPerformanceCounter() 无法调整：SetSystemTimeAdjustment() 只调整系统时间。

错误

• 由于硬件错误，性能计数器值可能会意外地向前跳跃，请参阅 KB274323。
• 在 VirtualBox 上，QueryPerformanceCounter() 在低位溢出时不会每次都增加高位，请参阅 单调计时器 (2009)。
• VirtualBox 的 HPET 虚拟设备有一个错误：QueryPerformanceCounter() 大约跳跃了 42 秒（问题 #8707）。
• Windows XP 存在一个错误（参见 KB896256）：在多处理器计算机上，QueryPerformanceCounter() 为每个处理器返回不同的值。该错误已在 Windows XP SP2 中修复。
• 变频处理器问题：频率根据工作负载改变以降低功耗。
• Chromium 不在 Athlon X2 CPU（型号 15）上使用 QueryPerformanceCounter()，因为“QueryPerformanceCounter 不可靠”（参见 Chromium 源代码中的 base/time_win.cc）

Windows: GetTickCount(), GetTickCount64()

GetTickCount() 和 GetTickCount64() 是单调的，不会失败，并且不受 SetSystemTimeAdjustment() 调整。MSDN 文档：GetTickCount()，GetTickCount64()。分辨率可以使用 GetSystemTimeAdjustment() 读取。

GetTickCount() 或 GetTickCount64() 检索的经过时间包括系统在睡眠或休眠中花费的时间。

GetTickCount64() 已添加到 Windows Vista 和 Windows Server 2008。

可以使用未文档化的 NtSetTimerResolution() 函数来提高精度。有一些应用程序使用此未文档化函数，例如：计时器分辨率。

WaitForSingleObject() 使用与 GetTickCount() 相同的计时器，具有相同的精度。

Windows: timeGetTime

timeGetTime 函数以毫秒为单位检索系统时间。系统时间是自 Windows 启动以来经过的时间。阅读 timeGetTime() 文档。

timeGetTime() 的返回类型是一个 32 位无符号整数。与 GetTickCount() 一样，timeGetTime() 在 2^32 毫秒（49.7 天）后溢出。

timeGetTime() 检索到的经过时间包括系统在睡眠中花费的时间。

timeGetTime 函数的默认精度可以是五毫秒或更高，具体取决于机器。

timeBeginPeriod() 可用于将 timeGetTime() 的精度提高到 1 毫秒，但这会负面影响功耗。调用 timeBeginPeriod() 还会影响其他一些计时调用的粒度，例如 CreateWaitableTimer()、WaitForSingleObject() 和 Sleep()。

Solaris: CLOCK_HIGHRES

Solaris 操作系统有一个 CLOCK_HIGHRES 计时器，它尝试使用最佳硬件源，并且可能提供接近纳秒的分辨率。CLOCK_HIGHRES 是不可调的、高分辨率时钟。对于使用 CLOCK_HIGHRES 的 clockid_t 值创建的计时器，系统将尝试使用最佳硬件源。

CLOCK_HIGHRES 的分辨率可以使用 clock_getres() 读取。

Solaris: gethrtime

gethrtime() 函数返回当前高分辨率实时。时间表示为自过去某个任意时间以来的纳秒数；它与一天中的时间没有任何关联，因此不受 adjtime() 或 settimeofday() 的重置或漂移影响。高分辨率计时器非常适合性能测量任务，需要廉价、准确的间隔计时。

gethrtime() 的线性度在挂起-恢复周期中不保留（Bug 4272663）。

阅读 Solaris 11 的 gethrtime() 手册页。

在 Solaris 上，gethrtime() 与 clock_gettime(CLOCK_MONOTONIC) 相同。

Windows: GetSystemTimeAsFileTime

系统时间可以使用 GetSystemTimeAsFileTime()、ftime() 和 time() 读取。系统时间的分辨率可以使用 GetSystemTimeAdjustment() 读取。

阅读 GetSystemTimeAsFileTime() 文档。

系统时间可以使用 SetSystemTime() 设置。

UNIX 上的系统时间

gettimeofday()、ftime()、time() 和 clock_gettime(CLOCK_REALTIME) 返回系统时间。CLOCK_REALTIME 的分辨率可以使用 clock_getres() 读取。

系统时间可以使用 settimeofday() 或 clock_settime(CLOCK_REALTIME) 设置。

自 Linux 2.6.32 起，Linux 还提供了 CLOCK_REALTIME_COARSE。它类似于 CLOCK_REALTIME，精度较低但速度更快。

Alexander Shishkin 为 Linux 提出了一个 API，用于在系统时钟更改时收到通知：timerfd: 添加 TFD_NOTIFY_CLOCK_SET 以监视时钟更改（API 的第 4 版，2011 年 3 月）。该 API 尚未被接受，但 CLOCK_BOOTTIME 提供了类似的功能。

函数

• Windows: GetProcessTimes()。分辨率可以使用 GetSystemTimeAdjustment() 读取。
• clock_gettime(CLOCK_PROCESS_CPUTIME_ID)：来自 CPU 的高分辨率每进程计时器。分辨率可以使用 clock_getres() 读取。
• clock()。分辨率为 1 / CLOCKS_PER_SEC。
  • Windows：自进程启动以来经过的挂钟时间（以秒为单位的经过时间乘以 CLOCKS_PER_SEC）。包括休眠期间经过的时间。它可能会失败。
  • UNIX：返回程序使用的处理器时间的近似值。
• getrusage(RUSAGE_SELF) 返回当前进程资源使用情况的结构。ru_utime 是用户 CPU 时间，ru_stime 是系统 CPU 时间。
• times()：进程时间结构。分辨率为 1 / ticks_per_seconds，其中 ticks_per_seconds 是 sysconf(_SC_CLK_TCK) 或 HZ 常量。

Python 源代码包含一个可移植库，用于获取进程时间（CPU 时间）：Tools/pybench/systimes.py。

另请参阅 QueryProcessCycleTime() 函数（所有线程的周期时间之和）和 clock_getcpuclockid()。

函数

• Windows: GetThreadTimes()。分辨率可以使用 GetSystemTimeAdjustment() 读取。
• clock_gettime(CLOCK_THREAD_CPUTIME_ID)：线程专用 CPU 时间时钟。它使用 CPU 周期数，而不是秒数。分辨率可以使用 clock_getres() 读取。

另请参阅 QueryThreadCycleTime() 函数（指定线程的周期时间）和 pthread_getcpuclockid()。

函数

• sleep(seconds)
• usleep(microseconds)
• nanosleep(nanoseconds, remaining)：Linux nanosleep() 手册页
• delay(milliseconds)

clock_nanosleep

clock_nanosleep(clock_id, flags, nanoseconds, remaining)：Linux clock_nanosleep() 手册页。

如果 flags 是 TIMER_ABSTIME，则请求被解释为由时钟 clock_id 测量的绝对时间。如果请求小于或等于时钟的当前值，则 clock_nanosleep() 会立即返回，而不暂停调用线程。

POSIX.1 规定，通过 clock_settime(2) 更改 CLOCK_REALTIME 时钟的值不应对在相对 clock_nanosleep() 上阻塞的线程产生影响。

select()

select(nfds, readfds, writefds, exceptfs, timeout)。

自 Linux 2.6.28 起，select() 使用高分辨率计时器来处理超时。一个进程有一个“松弛”属性来配置超时的精度，默认松弛为 50 微秒。在 Linux 2.6.28 之前，select() 的超时由主计时子系统以 jiffy 级别的分辨率处理。另请阅读 高分辨率（但不要太高）超时 和 计时器松弛。

其他函数

• poll()、epoll()
• sigtimedwait()。POSIX：“如果支持单调时钟选项，则应使用 CLOCK_MONOTONIC 时钟来测量 timeout 参数指定的时间间隔。”
• pthread_cond_timedwait()、pthread_condattr_setclock()。“时钟属性的默认值应指系统时间。”
• sem_timedwait()：“如果支持计时器选项，超时将基于 CLOCK_REALTIME 时钟。如果不支持计时器选项，超时将基于 time() 函数返回的系统时间。超时的精度应为基于的时钟的精度。”
• WaitForSingleObject()：使用与 GetTickCount() 相同的计时器，具有相同的精度。