1#ifndef Py_LIMITED_API
2#ifndef Py_PYTIME_H
3#define Py_PYTIME_H
4
5#include "pyconfig.h" /* include for defines */
6#include "object.h"
7
8/**************************************************************************
9Symbols and macros to supply platform-independent interfaces to time related
10functions and constants
11**************************************************************************/
12#ifdef __cplusplus
13extern "C" {
14#endif
15
16#ifdef PY_INT64_T
17/* _PyTime_t: Python timestamp with subsecond precision. It can be used to
18 store a duration, and so indirectly a date (related to another date, like
19 UNIX epoch). */
20typedef PY_INT64_T _PyTime_t;
21#define _PyTime_MIN PY_LLONG_MIN
22#define _PyTime_MAX PY_LLONG_MAX
23#else
24# error "_PyTime_t need signed 64-bit integer type"
25#endif
26
27typedef enum {
28 /* Round towards minus infinity (-inf).
29 For example, used to read a clock. */
30 _PyTime_ROUND_FLOOR=0,
31 /* Round towards infinity (+inf).
32 For example, used for timeout to wait "at least" N seconds. */
33 _PyTime_ROUND_CEILING
34} _PyTime_round_t;
35
36/* Convert a time_t to a PyLong. */
37PyAPI_FUNC(PyObject *) _PyLong_FromTime_t(
38 time_t sec);
39
40/* Convert a PyLong to a time_t. */
41PyAPI_FUNC(time_t) _PyLong_AsTime_t(
42 PyObject *obj);
43
44/* Convert a number of seconds, int or float, to time_t. */
45PyAPI_FUNC(int) _PyTime_ObjectToTime_t(
46 PyObject *obj,
47 time_t *sec,
48 _PyTime_round_t);
49
50/* Convert a number of seconds, int or float, to a timeval structure.
51 usec is in the range [0; 999999] and rounded towards zero.
52 For example, -1.2 is converted to (-2, 800000). */
53PyAPI_FUNC(int) _PyTime_ObjectToTimeval(
54 PyObject *obj,
55 time_t *sec,
56 long *usec,
57 _PyTime_round_t);
58
59/* Convert a number of seconds, int or float, to a timespec structure.
60 nsec is in the range [0; 999999999] and rounded towards zero.
61 For example, -1.2 is converted to (-2, 800000000). */
62PyAPI_FUNC(int) _PyTime_ObjectToTimespec(
63 PyObject *obj,
64 time_t *sec,
65 long *nsec,
66 _PyTime_round_t);
67
68
69/* Create a timestamp from a number of seconds. */
70PyAPI_FUNC(_PyTime_t) _PyTime_FromSeconds(int seconds);
71
72/* Macro to create a timestamp from a number of seconds, no integer overflow.
73 Only use the macro for small values, prefer _PyTime_FromSeconds(). */
74#define _PYTIME_FROMSECONDS(seconds) \
75 ((_PyTime_t)(seconds) * (1000 * 1000 * 1000))
76
77/* Create a timestamp from a number of nanoseconds. */
78PyAPI_FUNC(_PyTime_t) _PyTime_FromNanoseconds(PY_LONG_LONG ns);
79
80/* Convert a number of seconds (Python float or int) to a timetamp.
81 Raise an exception and return -1 on error, return 0 on success. */
82PyAPI_FUNC(int) _PyTime_FromSecondsObject(_PyTime_t *t,
83 PyObject *obj,
84 _PyTime_round_t round);
85
86/* Convert a number of milliseconds (Python float or int, 10^-3) to a timetamp.
87 Raise an exception and return -1 on error, return 0 on success. */
88PyAPI_FUNC(int) _PyTime_FromMillisecondsObject(_PyTime_t *t,
89 PyObject *obj,
90 _PyTime_round_t round);
91
92/* Convert a timestamp to a number of seconds as a C double. */
93PyAPI_FUNC(double) _PyTime_AsSecondsDouble(_PyTime_t t);
94
95/* Convert timestamp to a number of milliseconds (10^-3 seconds). */
96PyAPI_FUNC(_PyTime_t) _PyTime_AsMilliseconds(_PyTime_t t,
97 _PyTime_round_t round);
98
99/* Convert timestamp to a number of microseconds (10^-6 seconds). */
100PyAPI_FUNC(_PyTime_t) _PyTime_AsMicroseconds(_PyTime_t t,
101 _PyTime_round_t round);
102
103/* Convert timestamp to a number of nanoseconds (10^-9 seconds) as a Python int
104 object. */
105PyAPI_FUNC(PyObject *) _PyTime_AsNanosecondsObject(_PyTime_t t);
106
107/* Convert a timestamp to a timeval structure (microsecond resolution).
108 tv_usec is always positive.
109 Raise an exception and return -1 if the conversion overflowed,
110 return 0 on success. */
111PyAPI_FUNC(int) _PyTime_AsTimeval(_PyTime_t t,
112 struct timeval *tv,
113 _PyTime_round_t round);
114
115/* Similar to _PyTime_AsTimeval(), but don't raise an exception on error. */
116PyAPI_FUNC(int) _PyTime_AsTimeval_noraise(_PyTime_t t,
117 struct timeval *tv,
118 _PyTime_round_t round);
119
120/* Convert a timestamp to a number of seconds (secs) and microseconds (us).
121 us is always positive. This function is similar to _PyTime_AsTimeval()
122 except that secs is always a time_t type, whereas the timeval structure
123 uses a C long for tv_sec on Windows.
124 Raise an exception and return -1 if the conversion overflowed,
125 return 0 on success. */
126PyAPI_FUNC(int) _PyTime_AsTimevalTime_t(
127 _PyTime_t t,
128 time_t *secs,
129 int *us,
130 _PyTime_round_t round);
131
132#if defined(HAVE_CLOCK_GETTIME) || defined(HAVE_KQUEUE)
133/* Convert a timestamp to a timespec structure (nanosecond resolution).
134 tv_nsec is always positive.
135 Raise an exception and return -1 on error, return 0 on success. */
136PyAPI_FUNC(int) _PyTime_AsTimespec(_PyTime_t t, struct timespec *ts);
137#endif
138
139/* Get the current time from the system clock.
140
141 The function cannot fail. _PyTime_Init() ensures that the system clock
142 works. */
143PyAPI_FUNC(_PyTime_t) _PyTime_GetSystemClock(void);
144
145/* Get the time of a monotonic clock, i.e. a clock that cannot go backwards.
146 The clock is not affected by system clock updates. The reference point of
147 the returned value is undefined, so that only the difference between the
148 results of consecutive calls is valid.
149
150 The function cannot fail. _PyTime_Init() ensures that a monotonic clock
151 is available and works. */
152PyAPI_FUNC(_PyTime_t) _PyTime_GetMonotonicClock(void);
153
154
155/* Structure used by time.get_clock_info() */
156typedef struct {
157 const char *implementation;
158 int monotonic;
159 int adjustable;
160 double resolution;
161} _Py_clock_info_t;
162
163/* Get the current time from the system clock.
164 * Fill clock information if info is not NULL.
165 * Raise an exception and return -1 on error, return 0 on success.
166 */
167PyAPI_FUNC(int) _PyTime_GetSystemClockWithInfo(
168 _PyTime_t *t,
169 _Py_clock_info_t *info);
170
171/* Get the time of a monotonic clock, i.e. a clock that cannot go backwards.
172 The clock is not affected by system clock updates. The reference point of
173 the returned value is undefined, so that only the difference between the
174 results of consecutive calls is valid.
175
176 Fill info (if set) with information of the function used to get the time.
177
178 Return 0 on success, raise an exception and return -1 on error. */
179PyAPI_FUNC(int) _PyTime_GetMonotonicClockWithInfo(
180 _PyTime_t *t,
181 _Py_clock_info_t *info);
182
183
184/* Initialize time.
185 Return 0 on success, raise an exception and return -1 on error. */
186PyAPI_FUNC(int) _PyTime_Init(void);
187
188#ifdef __cplusplus
189}
190#endif
191
192#endif /* Py_PYTIME_H */
193#endif /* Py_LIMITED_API */
194