Skip to content

Latest commit

 

History

History
114 lines (71 loc) · 3.36 KB

time.rst

File metadata and controls

114 lines (71 loc) · 3.36 KB

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_tAtimestampordurationinnanoseconds, representedasa signed 64-bitinteger. Thereferencepointfortimestampsdependsontheclockused. Forexample, :c:func:`PyTime_Time` returnstimestampsrelativetotheUNIXepoch. Thesupportedrangeisaround [-292.3years; +292.3years]. UsingtheUnixepoch (January1st, 1970) asreference, thesupporteddaterangeisaround [1677-09-21; 2262-04-11]. Theexactlimitsareexposedasconstants:
.. c:var:: PyTime_tPyTime_MINMinimumvalueof :c:type:`PyTime_t`.
.. c:var:: PyTime_tPyTime_MAXMaximumvalueof :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 an :term:`attached thread state`.

.. c:function:: intPyTime_Monotonic(PyTime_t*result) Readthemonotonicclock. See :func:`time.monotonic` forimportantdetailsonthisclock.
.. c:function:: intPyTime_PerfCounter(PyTime_t*result) Readtheperformancecounter. See :func:`time.perf_counter` forimportantdetailsonthisclock.
.. c:function:: intPyTime_Time(PyTime_t*result) Readthe “wallclock” time. See :func:`time.time` fordetailsimportantonthisclock.

Raw Clock Functions

Similar to clock functions, but don't set an exception on error and don't require the caller to have an :term:`attached thread state`.

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, :term:`attach <attached thread state>` a :term:`thread state`, and call the regular (non-Raw) function. Note that the regular function may succeed after the Raw one failed.

.. c:function:: intPyTime_MonotonicRaw(PyTime_t*result) Similarto :c:func:`PyTime_Monotonic`, butdon't set an exception on error and don'trequirean :term:`attachedthreadstate`.
.. c:function:: intPyTime_PerfCounterRaw(PyTime_t*result) Similarto :c:func:`PyTime_PerfCounter`, butdon't set an exception on error and don'trequirean :term:`attachedthreadstate`.
.. c:function:: intPyTime_TimeRaw(PyTime_t*result) Similarto :c:func:`PyTime_Time`, butdon't set an exception on error and don'trequirean :term:`attachedthreadstate`.

Conversion functions

.. c:function:: doublePyTime_AsSecondsDouble(PyTime_tt) ConvertatimestamptoanumberofsecondsasaC :c:expr:`double`. Thefunctioncannotfail, butnotethat :c:expr:`double` haslimitedaccuracyforlargevalues.
close