Debian Codegraph @

Doc/c-api/time.rst

raw
1 .. highlight:: c
2
3 .. _c-api-time:
4
5 PyTime C API
6 ============
7
8 .. versionadded:: 3.13
9
10 The clock C API provides access to system clocks.
11 It is similar to the Python :mod:`time` module.
12
13 For C API related to the :mod:`datetime` module, see :ref:`datetimeobjects`.
14
15
16 Types
17 -----
18
19 .. c:type:: PyTime_t
20
21 A timestamp or duration in nanoseconds, represented as a signed 64-bit
22 integer.
23
24 The reference point for timestamps depends on the clock used. For example,
25 :c:func:`PyTime_Time` returns timestamps relative to the UNIX epoch.
26
27 The supported range is around [-292.3 years; +292.3 years].
28 Using the Unix epoch (January 1st, 1970) as reference, the supported date
29 range is around [1677-09-21; 2262-04-11].
30 The exact limits are exposed as constants:
31
32 .. c:var:: PyTime_t PyTime_MIN
33
34 Minimum value of :c:type:`PyTime_t`.
35
36 .. c:var:: PyTime_t PyTime_MAX
37
38 Maximum value of :c:type:`PyTime_t`.
39
40
41 Clock Functions
42 ---------------
43
44 The following functions take a pointer to a :c:expr:`PyTime_t` that they
45 set to the value of a particular clock.
46 Details of each clock are given in the documentation of the corresponding
47 Python function.
48
49 The functions return ``0`` on success, or ``-1`` (with an exception set)
50 on failure.
51
52 On integer overflow, they set the :c:data:`PyExc_OverflowError` exception and
53 set ``*result`` to the value clamped to the ``[PyTime_MIN; PyTime_MAX]``
54 range.
55 (On current systems, integer overflows are likely caused by misconfigured
56 system time.)
57
58 As any other C API (unless otherwise specified), the functions must be called
59 with an :term:`attached thread state`.
60
61 .. c:function:: int PyTime_Monotonic(PyTime_t *result)
62
63 Read the monotonic clock.
64 See :func:`time.monotonic` for important details on this clock.
65
66 .. c:function:: int PyTime_PerfCounter(PyTime_t *result)
67
68 Read the performance counter.
69 See :func:`time.perf_counter` for important details on this clock.
70
71 .. c:function:: int PyTime_Time(PyTime_t *result)
72
73 Read the “wall clock” time.
74 See :func:`time.time` for details important on this clock.
75
76
77 Raw Clock Functions
78 -------------------
79
80 Similar to clock functions, but don't set an exception on error and don't
81 require the caller to have an :term:`attached thread state`.
82
83 On success, the functions return ``0``.
84
85 On failure, they set ``*result`` to ``0`` and return ``-1``, *without* setting
86 an exception. To get the cause of the error, :term:`attach <attached thread state>` a :term:`thread state`,
87 and call the regular (non-``Raw``) function. Note that the regular function may succeed after
88 the ``Raw`` one failed.
89
90 .. c:function:: int PyTime_MonotonicRaw(PyTime_t *result)
91
92 Similar to :c:func:`PyTime_Monotonic`,
93 but don't set an exception on error and don't require an :term:`attached thread state`.
94
95 .. c:function:: int PyTime_PerfCounterRaw(PyTime_t *result)
96
97 Similar to :c:func:`PyTime_PerfCounter`,
98 but don't set an exception on error and don't require an :term:`attached thread state`.
99
100 .. c:function:: int PyTime_TimeRaw(PyTime_t *result)
101
102 Similar to :c:func:`PyTime_Time`,
103 but don't set an exception on error and don't require an :term:`attached thread state`.
104
105
106 Conversion functions
107 --------------------
108
109 .. c:function:: double PyTime_AsSecondsDouble(PyTime_t t)
110
111 Convert a timestamp to a number of seconds as a C :c:expr:`double`.
112
113 The function cannot fail, but note that :c:expr:`double` has limited
114 accuracy for large values.