Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/python3.8/pytime.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 #ifndef Py_LIMITED_API
jpayne@69 2 #ifndef Py_PYTIME_H
jpayne@69 3 #define Py_PYTIME_H
jpayne@69 4
jpayne@69 5 #include "pyconfig.h" /* include for defines */
jpayne@69 6 #include "object.h"
jpayne@69 7
jpayne@69 8 /**************************************************************************
jpayne@69 9 Symbols and macros to supply platform-independent interfaces to time related
jpayne@69 10 functions and constants
jpayne@69 11 **************************************************************************/
jpayne@69 12 #ifdef __cplusplus
jpayne@69 13 extern "C" {
jpayne@69 14 #endif
jpayne@69 15
jpayne@69 16 /* _PyTime_t: Python timestamp with subsecond precision. It can be used to
jpayne@69 17 store a duration, and so indirectly a date (related to another date, like
jpayne@69 18 UNIX epoch). */
jpayne@69 19 typedef int64_t _PyTime_t;
jpayne@69 20 #define _PyTime_MIN INT64_MIN
jpayne@69 21 #define _PyTime_MAX INT64_MAX
jpayne@69 22
jpayne@69 23 typedef enum {
jpayne@69 24 /* Round towards minus infinity (-inf).
jpayne@69 25 For example, used to read a clock. */
jpayne@69 26 _PyTime_ROUND_FLOOR=0,
jpayne@69 27 /* Round towards infinity (+inf).
jpayne@69 28 For example, used for timeout to wait "at least" N seconds. */
jpayne@69 29 _PyTime_ROUND_CEILING=1,
jpayne@69 30 /* Round to nearest with ties going to nearest even integer.
jpayne@69 31 For example, used to round from a Python float. */
jpayne@69 32 _PyTime_ROUND_HALF_EVEN=2,
jpayne@69 33 /* Round away from zero
jpayne@69 34 For example, used for timeout. _PyTime_ROUND_CEILING rounds
jpayne@69 35 -1e-9 to 0 milliseconds which causes bpo-31786 issue.
jpayne@69 36 _PyTime_ROUND_UP rounds -1e-9 to -1 millisecond which keeps
jpayne@69 37 the timeout sign as expected. select.poll(timeout) must block
jpayne@69 38 for negative values." */
jpayne@69 39 _PyTime_ROUND_UP=3,
jpayne@69 40 /* _PyTime_ROUND_TIMEOUT (an alias for _PyTime_ROUND_UP) should be
jpayne@69 41 used for timeouts. */
jpayne@69 42 _PyTime_ROUND_TIMEOUT = _PyTime_ROUND_UP
jpayne@69 43 } _PyTime_round_t;
jpayne@69 44
jpayne@69 45
jpayne@69 46 /* Convert a time_t to a PyLong. */
jpayne@69 47 PyAPI_FUNC(PyObject *) _PyLong_FromTime_t(
jpayne@69 48 time_t sec);
jpayne@69 49
jpayne@69 50 /* Convert a PyLong to a time_t. */
jpayne@69 51 PyAPI_FUNC(time_t) _PyLong_AsTime_t(
jpayne@69 52 PyObject *obj);
jpayne@69 53
jpayne@69 54 /* Convert a number of seconds, int or float, to time_t. */
jpayne@69 55 PyAPI_FUNC(int) _PyTime_ObjectToTime_t(
jpayne@69 56 PyObject *obj,
jpayne@69 57 time_t *sec,
jpayne@69 58 _PyTime_round_t);
jpayne@69 59
jpayne@69 60 /* Convert a number of seconds, int or float, to a timeval structure.
jpayne@69 61 usec is in the range [0; 999999] and rounded towards zero.
jpayne@69 62 For example, -1.2 is converted to (-2, 800000). */
jpayne@69 63 PyAPI_FUNC(int) _PyTime_ObjectToTimeval(
jpayne@69 64 PyObject *obj,
jpayne@69 65 time_t *sec,
jpayne@69 66 long *usec,
jpayne@69 67 _PyTime_round_t);
jpayne@69 68
jpayne@69 69 /* Convert a number of seconds, int or float, to a timespec structure.
jpayne@69 70 nsec is in the range [0; 999999999] and rounded towards zero.
jpayne@69 71 For example, -1.2 is converted to (-2, 800000000). */
jpayne@69 72 PyAPI_FUNC(int) _PyTime_ObjectToTimespec(
jpayne@69 73 PyObject *obj,
jpayne@69 74 time_t *sec,
jpayne@69 75 long *nsec,
jpayne@69 76 _PyTime_round_t);
jpayne@69 77
jpayne@69 78
jpayne@69 79 /* Create a timestamp from a number of seconds. */
jpayne@69 80 PyAPI_FUNC(_PyTime_t) _PyTime_FromSeconds(int seconds);
jpayne@69 81
jpayne@69 82 /* Macro to create a timestamp from a number of seconds, no integer overflow.
jpayne@69 83 Only use the macro for small values, prefer _PyTime_FromSeconds(). */
jpayne@69 84 #define _PYTIME_FROMSECONDS(seconds) \
jpayne@69 85 ((_PyTime_t)(seconds) * (1000 * 1000 * 1000))
jpayne@69 86
jpayne@69 87 /* Create a timestamp from a number of nanoseconds. */
jpayne@69 88 PyAPI_FUNC(_PyTime_t) _PyTime_FromNanoseconds(_PyTime_t ns);
jpayne@69 89
jpayne@69 90 /* Create a timestamp from nanoseconds (Python int). */
jpayne@69 91 PyAPI_FUNC(int) _PyTime_FromNanosecondsObject(_PyTime_t *t,
jpayne@69 92 PyObject *obj);
jpayne@69 93
jpayne@69 94 /* Convert a number of seconds (Python float or int) to a timetamp.
jpayne@69 95 Raise an exception and return -1 on error, return 0 on success. */
jpayne@69 96 PyAPI_FUNC(int) _PyTime_FromSecondsObject(_PyTime_t *t,
jpayne@69 97 PyObject *obj,
jpayne@69 98 _PyTime_round_t round);
jpayne@69 99
jpayne@69 100 /* Convert a number of milliseconds (Python float or int, 10^-3) to a timetamp.
jpayne@69 101 Raise an exception and return -1 on error, return 0 on success. */
jpayne@69 102 PyAPI_FUNC(int) _PyTime_FromMillisecondsObject(_PyTime_t *t,
jpayne@69 103 PyObject *obj,
jpayne@69 104 _PyTime_round_t round);
jpayne@69 105
jpayne@69 106 /* Convert a timestamp to a number of seconds as a C double. */
jpayne@69 107 PyAPI_FUNC(double) _PyTime_AsSecondsDouble(_PyTime_t t);
jpayne@69 108
jpayne@69 109 /* Convert timestamp to a number of milliseconds (10^-3 seconds). */
jpayne@69 110 PyAPI_FUNC(_PyTime_t) _PyTime_AsMilliseconds(_PyTime_t t,
jpayne@69 111 _PyTime_round_t round);
jpayne@69 112
jpayne@69 113 /* Convert timestamp to a number of microseconds (10^-6 seconds). */
jpayne@69 114 PyAPI_FUNC(_PyTime_t) _PyTime_AsMicroseconds(_PyTime_t t,
jpayne@69 115 _PyTime_round_t round);
jpayne@69 116
jpayne@69 117 /* Convert timestamp to a number of nanoseconds (10^-9 seconds) as a Python int
jpayne@69 118 object. */
jpayne@69 119 PyAPI_FUNC(PyObject *) _PyTime_AsNanosecondsObject(_PyTime_t t);
jpayne@69 120
jpayne@69 121 /* Create a timestamp from a timeval structure.
jpayne@69 122 Raise an exception and return -1 on overflow, return 0 on success. */
jpayne@69 123 PyAPI_FUNC(int) _PyTime_FromTimeval(_PyTime_t *tp, struct timeval *tv);
jpayne@69 124
jpayne@69 125 /* Convert a timestamp to a timeval structure (microsecond resolution).
jpayne@69 126 tv_usec is always positive.
jpayne@69 127 Raise an exception and return -1 if the conversion overflowed,
jpayne@69 128 return 0 on success. */
jpayne@69 129 PyAPI_FUNC(int) _PyTime_AsTimeval(_PyTime_t t,
jpayne@69 130 struct timeval *tv,
jpayne@69 131 _PyTime_round_t round);
jpayne@69 132
jpayne@69 133 /* Similar to _PyTime_AsTimeval(), but don't raise an exception on error. */
jpayne@69 134 PyAPI_FUNC(int) _PyTime_AsTimeval_noraise(_PyTime_t t,
jpayne@69 135 struct timeval *tv,
jpayne@69 136 _PyTime_round_t round);
jpayne@69 137
jpayne@69 138 /* Convert a timestamp to a number of seconds (secs) and microseconds (us).
jpayne@69 139 us is always positive. This function is similar to _PyTime_AsTimeval()
jpayne@69 140 except that secs is always a time_t type, whereas the timeval structure
jpayne@69 141 uses a C long for tv_sec on Windows.
jpayne@69 142 Raise an exception and return -1 if the conversion overflowed,
jpayne@69 143 return 0 on success. */
jpayne@69 144 PyAPI_FUNC(int) _PyTime_AsTimevalTime_t(
jpayne@69 145 _PyTime_t t,
jpayne@69 146 time_t *secs,
jpayne@69 147 int *us,
jpayne@69 148 _PyTime_round_t round);
jpayne@69 149
jpayne@69 150 #if defined(HAVE_CLOCK_GETTIME) || defined(HAVE_KQUEUE)
jpayne@69 151 /* Create a timestamp from a timespec structure.
jpayne@69 152 Raise an exception and return -1 on overflow, return 0 on success. */
jpayne@69 153 PyAPI_FUNC(int) _PyTime_FromTimespec(_PyTime_t *tp, struct timespec *ts);
jpayne@69 154
jpayne@69 155 /* Convert a timestamp to a timespec structure (nanosecond resolution).
jpayne@69 156 tv_nsec is always positive.
jpayne@69 157 Raise an exception and return -1 on error, return 0 on success. */
jpayne@69 158 PyAPI_FUNC(int) _PyTime_AsTimespec(_PyTime_t t, struct timespec *ts);
jpayne@69 159 #endif
jpayne@69 160
jpayne@69 161 /* Compute ticks * mul / div.
jpayne@69 162 The caller must ensure that ((div - 1) * mul) cannot overflow. */
jpayne@69 163 PyAPI_FUNC(_PyTime_t) _PyTime_MulDiv(_PyTime_t ticks,
jpayne@69 164 _PyTime_t mul,
jpayne@69 165 _PyTime_t div);
jpayne@69 166
jpayne@69 167 /* Get the current time from the system clock.
jpayne@69 168
jpayne@69 169 The function cannot fail. _PyTime_Init() ensures that the system clock
jpayne@69 170 works. */
jpayne@69 171 PyAPI_FUNC(_PyTime_t) _PyTime_GetSystemClock(void);
jpayne@69 172
jpayne@69 173 /* Get the time of a monotonic clock, i.e. a clock that cannot go backwards.
jpayne@69 174 The clock is not affected by system clock updates. The reference point of
jpayne@69 175 the returned value is undefined, so that only the difference between the
jpayne@69 176 results of consecutive calls is valid.
jpayne@69 177
jpayne@69 178 The function cannot fail. _PyTime_Init() ensures that a monotonic clock
jpayne@69 179 is available and works. */
jpayne@69 180 PyAPI_FUNC(_PyTime_t) _PyTime_GetMonotonicClock(void);
jpayne@69 181
jpayne@69 182
jpayne@69 183 /* Structure used by time.get_clock_info() */
jpayne@69 184 typedef struct {
jpayne@69 185 const char *implementation;
jpayne@69 186 int monotonic;
jpayne@69 187 int adjustable;
jpayne@69 188 double resolution;
jpayne@69 189 } _Py_clock_info_t;
jpayne@69 190
jpayne@69 191 /* Get the current time from the system clock.
jpayne@69 192 * Fill clock information if info is not NULL.
jpayne@69 193 * Raise an exception and return -1 on error, return 0 on success.
jpayne@69 194 */
jpayne@69 195 PyAPI_FUNC(int) _PyTime_GetSystemClockWithInfo(
jpayne@69 196 _PyTime_t *t,
jpayne@69 197 _Py_clock_info_t *info);
jpayne@69 198
jpayne@69 199 /* Get the time of a monotonic clock, i.e. a clock that cannot go backwards.
jpayne@69 200 The clock is not affected by system clock updates. The reference point of
jpayne@69 201 the returned value is undefined, so that only the difference between the
jpayne@69 202 results of consecutive calls is valid.
jpayne@69 203
jpayne@69 204 Fill info (if set) with information of the function used to get the time.
jpayne@69 205
jpayne@69 206 Return 0 on success, raise an exception and return -1 on error. */
jpayne@69 207 PyAPI_FUNC(int) _PyTime_GetMonotonicClockWithInfo(
jpayne@69 208 _PyTime_t *t,
jpayne@69 209 _Py_clock_info_t *info);
jpayne@69 210
jpayne@69 211
jpayne@69 212 /* Initialize time.
jpayne@69 213 Return 0 on success, raise an exception and return -1 on error. */
jpayne@69 214 PyAPI_FUNC(int) _PyTime_Init(void);
jpayne@69 215
jpayne@69 216 /* Converts a timestamp to the Gregorian time, using the local time zone.
jpayne@69 217 Return 0 on success, raise an exception and return -1 on error. */
jpayne@69 218 PyAPI_FUNC(int) _PyTime_localtime(time_t t, struct tm *tm);
jpayne@69 219
jpayne@69 220 /* Converts a timestamp to the Gregorian time, assuming UTC.
jpayne@69 221 Return 0 on success, raise an exception and return -1 on error. */
jpayne@69 222 PyAPI_FUNC(int) _PyTime_gmtime(time_t t, struct tm *tm);
jpayne@69 223
jpayne@69 224 /* Get the performance counter: clock with the highest available resolution to
jpayne@69 225 measure a short duration.
jpayne@69 226
jpayne@69 227 The function cannot fail. _PyTime_Init() ensures that the system clock
jpayne@69 228 works. */
jpayne@69 229 PyAPI_FUNC(_PyTime_t) _PyTime_GetPerfCounter(void);
jpayne@69 230
jpayne@69 231 /* Get the performance counter: clock with the highest available resolution to
jpayne@69 232 measure a short duration.
jpayne@69 233
jpayne@69 234 Fill info (if set) with information of the function used to get the time.
jpayne@69 235
jpayne@69 236 Return 0 on success, raise an exception and return -1 on error. */
jpayne@69 237 PyAPI_FUNC(int) _PyTime_GetPerfCounterWithInfo(
jpayne@69 238 _PyTime_t *t,
jpayne@69 239 _Py_clock_info_t *info);
jpayne@69 240
jpayne@69 241 #ifdef __cplusplus
jpayne@69 242 }
jpayne@69 243 #endif
jpayne@69 244
jpayne@69 245 #endif /* Py_PYTIME_H */
jpayne@69 246 #endif /* Py_LIMITED_API */