PyTime C API
************

Added in version 3.13.

时钟 C API 提供对系统时钟的访问。它类似于 Python "time" 模块。

有关与 "datetime" 模块相关的 C API，请参阅 DateTime 对象。


类型
====

type PyTime_t

   以纳秒为单位的时间戳或持续时间，表示为带符号的 64 位整数。

   时间戳的参考点取决于所使用的时钟。例如，"PyTime_Time()" 返回相对于
   UNIX 纪元的时间戳。

   支持的范围约为 [-292.3 年; +292.3 年]。以 Unix 纪元（1970 年 1 月 1
   日）为参考，支持的日期范围约为 [1677-09-21; 2262-04-11]。确切的限制
   以常量形式公开：

PyTime_t PyTime_MIN

   "PyTime_t" 的最小值。

PyTime_t PyTime_MAX

   "PyTime_t" 的最大值。


时钟函数
========

以下函数采用指向 PyTime_t 的指针，并将其设置为特定时钟的值。每个时钟的
详细信息在相应的 Python 函数的文档中给出。

成功时函数返回 "0"，失败时返回 "-1" (设置一个异常)。

在整数溢出时，它们会设置 "PyExc_OverflowError" 异常，并将 "*result" 设
置为钳位到 "[PyTime_MIN; PyTime_MAX]" 范围的值。 （在当前系统上，整数
溢出可能是由于系统时间配置错误引起的。）

与任何其他 C API 一样（除非另有说明），必须使用持有的 *attached thread
state* 来调用函数。

int PyTime_Monotonic(PyTime_t *result)

   读取单调时钟。有关该时钟的重要详细信息，请参阅 "time.monotonic()"。

int PyTime_PerfCounter(PyTime_t *result)

   读取性能计数器。有关该时钟的重要详细信息，请参阅
   "time.perf_counter()"。

int PyTime_Time(PyTime_t *result)

   读取"wall clock"时间。有关该时钟的重要详细信息，请参阅
   "time.time()"。


原始时钟函数
============

与时钟函数类似，但不设置错误异常，也不要求调用者具有 *attached thread
state*。

成功时，函数返回 "0"。

失败时，它们将 "*result" 设置为 "0" 并返回 "-1"，*不* 设置异常。要了解
错误原因，请 *附加* *thread state*，并调用常规 (非 "Raw") 函数。 请注
意，常规函数可能会在 "Raw" 函数失败后成功。

int PyTime_MonotonicRaw(PyTime_t *result)

   与 "PyTime_Monotonic()" 类似，但在错误时不设置异常，并且不需要
   *attached thread state*.

int PyTime_PerfCounterRaw(PyTime_t *result)

   与 "PyTime_PerfCounter()" 类似，但在错误时不设置异常，并且不需要
   *attached thread state*.

int PyTime_TimeRaw(PyTime_t *result)

   与 "PyTime_Time()" 类似，但在错误时不设置异常，并且不需要 *attached
   thread state*。


转换函数
========

double PyTime_AsSecondsDouble(PyTime_t t)

   将时间戳转换为 C double 形式的秒数。

   该函数不会失败，但请注意 double 对于大值的精度有限。
