API C для PyTime

Типы

type PyTime_t

Метка времени или длительность в наносекундах, представленная знаковым 64-разрядным целым числом.

Точка отсчёта для меток времени зависит от используемых часов. Например, PyTime_Time() возвращает метки времени относительно эпохи UNIX.

Поддерживаемый диапазон составляет примерно [-292,3 года; +292,3 года]. Если в качестве точки отсчёта использовать эпоху Unix (1 января 1970 года), поддерживаемый диапазон дат составит примерно [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]. (В современных системах переполнение целого числа, скорее всего, вызвано неправильной настройкой системного времени.)

Как и любые другие функции API C (если не указано иное), эти функции необходимо вызывать, удерживая GIL.

int PyTime_Monotonic(PyTime_t *result)

Считывает монотонные часы. Важные сведения об этих часах см. в разделе time.monotonic().

int PyTime_PerfCounter(PyTime_t *result)

Считывает счётчик производительности. Важные сведения об этих часах см. в разделе time.perf_counter().

int PyTime_Time(PyTime_t *result)

Считывает время «настенных часов». Подробные сведения об этих часах см. в разделе time.time().

Функции необработанных часов

Аналогичны функциям часов, но не устанавливают исключение при ошибке и не требуют от вызывающего кода удерживать GIL.

В случае успеха функции возвращают 0.

В случае ошибки они устанавливают *result в значение 0 и возвращают -1, не устанавливая исключение. Чтобы узнать причину ошибки, захватите GIL и вызовите обычную функцию (не Raw). Обратите внимание, что обычная функция может завершиться успешно, даже если функция Raw завершилась ошибкой.

int PyTime_MonotonicRaw(PyTime_t *result)

Аналогична PyTime_Monotonic(), но не устанавливает исключение при ошибке и не требует удерживать GIL.

int PyTime_PerfCounterRaw(PyTime_t *result)

Аналогична PyTime_PerfCounter(), но не устанавливает исключение при ошибке и не требует удерживать GIL.

int PyTime_TimeRaw(PyTime_t *result)

Аналогична PyTime_Time(), но не устанавливает исключение при ошибке и не требует удерживать GIL.

Функции преобразования

double PyTime_AsSecondsDouble(PyTime_t t)

Преобразует метку времени в количество секунд типа C double.

Функция не может завершиться ошибкой, но следует учитывать, что точность double ограничена для больших значений.