gh-110850: Add PyTime_TimeRaw() function (#118394)

Add "Raw" variant of PyTime functions:

* PyTime_MonotonicRaw()
* PyTime_PerfCounterRaw()
* PyTime_TimeRaw()

Changes:

* Add documentation and tests. Tests release the GIL while calling
  raw clock functions.
* py_get_system_clock() and py_get_monotonic_clock() now check that
  the GIL is hold by the caller if raise_exc is non-zero.
* Reimplement "Unchecked" functions with raw clock functions.

Co-authored-by: Petr Viktorin <encukou@gmail.com>

1 files changed, 29 insertions, 0 deletions

diff --git a/Doc/c-api/time.rst b/Doc/c-api/time.rst
index 7791cdb..5cfdef7 100644
--- a/Doc/c-api/time.rst
+++ b/Doc/c-api/time.rst
@@ -72,6 +72,35 @@ with the :term:`GIL` held.
    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
 --------------------