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