|
@@ -15,11 +15,29 @@
|
|
|
* of tens of milliseconds.
|
|
|
*/
|
|
|
|
|
|
-/* Q: Should you use monotime or monotime_coarse as your source?
|
|
|
+/* Q: When should I use monotonic time?
|
|
|
+ *
|
|
|
+ * A: If you need a time that never decreases, use monotonic time. If you need
|
|
|
+ * to send a time to a user or another process, or store a time, use the
|
|
|
+ * wall-clock time.
|
|
|
+ *
|
|
|
+ * Q: Should you use monotime or monotime_coarse as your source?
|
|
|
*
|
|
|
* A: Generally, you get better precision with monotime, but better
|
|
|
* performance with monotime_coarse.
|
|
|
*
|
|
|
+ * Q: What is a "monotonic" time, exactly?
|
|
|
+ *
|
|
|
+ * A: Monotonic times are strictly non-decreasing. The difference between any
|
|
|
+ * previous monotonic time, and the current monotonic time, is always greater
|
|
|
+ * than *or equal to* zero.
|
|
|
+ * Zero deltas happen more often:
|
|
|
+ * - on Windows (due to an OS bug),
|
|
|
+ * - when using monotime_coarse, or on systems with low-resolution timers,
|
|
|
+ * - on platforms where we emulate monotonic time using wall-clock time, and
|
|
|
+ * - when using time units that are larger than nanoseconds (due to
|
|
|
+ * truncation on division).
|
|
|
+ *
|
|
|
* Q: Should you use monotime_t or monotime_coarse_t directly? Should you use
|
|
|
* usec? msec? "stamp units?"
|
|
|
*
|
|
@@ -95,7 +113,7 @@
|
|
|
* All, "timestamp units": Cheap everywhere: it never divides.
|
|
|
*
|
|
|
* Q: This is only somewhat related, but how much precision could I hope for
|
|
|
- * from a libevent time.?
|
|
|
+ * from a libevent time?
|
|
|
*
|
|
|
* A: Actually, it's _very_ related if you're timing in order to have a
|
|
|
* timeout happen.
|
|
@@ -182,26 +200,36 @@ void monotime_init(void);
|
|
|
void monotime_get(monotime_t *out);
|
|
|
/**
|
|
|
* Return the number of nanoseconds between <b>start</b> and <b>end</b>.
|
|
|
+ * The returned value may be equal to zero.
|
|
|
*/
|
|
|
int64_t monotime_diff_nsec(const monotime_t *start, const monotime_t *end);
|
|
|
/**
|
|
|
* Return the number of microseconds between <b>start</b> and <b>end</b>.
|
|
|
+ * The returned value may be equal to zero.
|
|
|
+ * Fractional units are truncated, not rounded.
|
|
|
*/
|
|
|
int64_t monotime_diff_usec(const monotime_t *start, const monotime_t *end);
|
|
|
/**
|
|
|
* Return the number of milliseconds between <b>start</b> and <b>end</b>.
|
|
|
+ * The returned value may be equal to zero.
|
|
|
+ * Fractional units are truncated, not rounded.
|
|
|
*/
|
|
|
int64_t monotime_diff_msec(const monotime_t *start, const monotime_t *end);
|
|
|
/**
|
|
|
* Return the number of nanoseconds since the timer system was initialized.
|
|
|
+ * The returned value may be equal to zero.
|
|
|
*/
|
|
|
uint64_t monotime_absolute_nsec(void);
|
|
|
/**
|
|
|
* Return the number of microseconds since the timer system was initialized.
|
|
|
+ * The returned value may be equal to zero.
|
|
|
+ * Fractional units are truncated, not rounded.
|
|
|
*/
|
|
|
MOCK_DECL(uint64_t, monotime_absolute_usec,(void));
|
|
|
/**
|
|
|
* Return the number of milliseconds since the timer system was initialized.
|
|
|
+ * The returned value may be equal to zero.
|
|
|
+ * Fractional units are truncated, not rounded.
|
|
|
*/
|
|
|
uint64_t monotime_absolute_msec(void);
|
|
|
|
|
@@ -225,6 +253,9 @@ void monotime_add_msec(monotime_t *out, const monotime_t *val, uint32_t msec);
|
|
|
* Set <b>out</b> to the current coarse time.
|
|
|
*/
|
|
|
void monotime_coarse_get(monotime_coarse_t *out);
|
|
|
+/**
|
|
|
+ * Like monotime_absolute_*(), but faster on some platforms.
|
|
|
+ */
|
|
|
uint64_t monotime_coarse_absolute_nsec(void);
|
|
|
uint64_t monotime_coarse_absolute_usec(void);
|
|
|
uint64_t monotime_coarse_absolute_msec(void);
|
|
@@ -248,18 +279,27 @@ uint32_t monotime_coarse_to_stamp(const monotime_coarse_t *t);
|
|
|
/**
|
|
|
* Convert a difference, expressed in the units of monotime_coarse_to_stamp,
|
|
|
* into an approximate number of milliseconds.
|
|
|
+ *
|
|
|
+ * The returned value may be equal to zero.
|
|
|
+ * Fractional units are truncated, not rounded.
|
|
|
*/
|
|
|
uint64_t monotime_coarse_stamp_units_to_approx_msec(uint64_t units);
|
|
|
uint64_t monotime_msec_to_approx_coarse_stamp_units(uint64_t msec);
|
|
|
uint32_t monotime_coarse_get_stamp(void);
|
|
|
|
|
|
#if defined(MONOTIME_COARSE_TYPE_IS_DIFFERENT)
|
|
|
+/**
|
|
|
+ * Like monotime_diff_*(), but faster on some platforms.
|
|
|
+ */
|
|
|
int64_t monotime_coarse_diff_nsec(const monotime_coarse_t *start,
|
|
|
const monotime_coarse_t *end);
|
|
|
int64_t monotime_coarse_diff_usec(const monotime_coarse_t *start,
|
|
|
const monotime_coarse_t *end);
|
|
|
int64_t monotime_coarse_diff_msec(const monotime_coarse_t *start,
|
|
|
const monotime_coarse_t *end);
|
|
|
+/**
|
|
|
+ * Like monotime_*(), but faster on some platforms.
|
|
|
+ */
|
|
|
void monotime_coarse_zero(monotime_coarse_t *out);
|
|
|
int monotime_coarse_is_zero(const monotime_coarse_t *val);
|
|
|
void monotime_coarse_add_msec(monotime_coarse_t *out,
|
|
@@ -278,6 +318,9 @@ void monotime_coarse_add_msec(monotime_coarse_t *out,
|
|
|
*
|
|
|
* Requires that the difference fit into an int32_t; not for use with
|
|
|
* large time differences.
|
|
|
+ *
|
|
|
+ * The returned value may be equal to zero.
|
|
|
+ * Fractional units are truncated, not rounded.
|
|
|
*/
|
|
|
int32_t monotime_coarse_diff_msec32_(const monotime_coarse_t *start,
|
|
|
const monotime_coarse_t *end);
|
|
@@ -287,6 +330,9 @@ int32_t monotime_coarse_diff_msec32_(const monotime_coarse_t *start,
|
|
|
*
|
|
|
* Requires that the difference fit into an int32_t; not for use with
|
|
|
* large time differences.
|
|
|
+ *
|
|
|
+ * The returned value may be equal to zero.
|
|
|
+ * Fractional units are truncated, not rounded.
|
|
|
*/
|
|
|
static inline int32_t
|
|
|
monotime_coarse_diff_msec32(const monotime_coarse_t *start,
|