[thirdparty/Python/cpython.git] / Doc / c-api / time.rst

.. highlight:: c

PyTime C API
============

.. versionadded:: 3.13

The clock C API provides access to system clocks.
It is similar to the Python :mod:`time` module.

For C API related to the :mod:`datetime` module, see :ref:`datetimeobjects`.


Types
-----

.. c:type:: PyTime_t

   A timestamp or duration in nanoseconds, represented as a signed 64-bit
   integer.

   The reference point for timestamps depends on the clock used. For example,
   :c:func:`PyTime_Time` returns timestamps relative to the UNIX epoch.

   The supported range is around [-292.3 years; +292.3 years].
   Using the Unix epoch (January 1st, 1970) as reference, the supported date
   range is around [1677-09-21; 2262-04-11].
   The exact limits are exposed as constants:

.. c:var:: PyTime_t PyTime_MIN

   Minimum value of :c:type:`PyTime_t`.

.. c:var:: PyTime_t PyTime_MAX

   Maximum value of :c:type:`PyTime_t`.


Clock Functions
---------------

The following functions take a pointer to a :c:expr:`PyTime_t` that they
set to the value of a particular clock.
Details of each clock are given in the documentation of the corresponding
Python function.

The functions return ``0`` on success, or ``-1`` (with an exception set)
on failure.

On integer overflow, they set the :c:data:`PyExc_OverflowError` exception and
set ``*result`` to the value clamped to the ``[PyTime_MIN; PyTime_MAX]``
range.
(On current systems, integer overflows are likely caused by misconfigured
system time.)

As any other C API (unless otherwise specified), the functions must be called
with the :term:`GIL` held.

.. c:function:: int PyTime_Monotonic(PyTime_t *result)

   Read the monotonic clock.
   See :func:`time.monotonic` for important details on this clock.

.. c:function:: int PyTime_PerfCounter(PyTime_t *result)

   Read the performance counter.
   See :func:`time.perf_counter` for important details on this clock.

.. c:function:: int PyTime_Time(PyTime_t *result)

   Read the “wall clock” time.
   See :func:`time.time` for details important on this clock.


Raw Clock Functions
-------------------

Similar to clock functions, but don't set an exception on error and don't
require the caller to hold the GIL.

On success, the functions return ``0``.

On failure, they set ``*result`` to ``0`` and return ``-1``, *without* setting
an exception. To get the cause of the error, acquire the GIL and call the
regular (non-``Raw``) function. Note that the regular function may succeed after
the ``Raw`` one failed.

.. c:function:: int PyTime_MonotonicRaw(PyTime_t *result)

   Similar to :c:func:`PyTime_Monotonic`,
   but don't set an exception on error and don't require holding the GIL.

.. c:function:: int PyTime_PerfCounterRaw(PyTime_t *result)

   Similar to :c:func:`PyTime_PerfCounter`,
   but don't set an exception on error and don't require holding the GIL.

.. c:function:: int PyTime_TimeRaw(PyTime_t *result)

   Similar to :c:func:`PyTime_Time`,
   but don't set an exception on error and don't require holding the GIL.


Conversion functions
--------------------

.. c:function:: double PyTime_AsSecondsDouble(PyTime_t t)

   Convert a timestamp to a number of seconds as a C :c:expr:`double`.

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