complete and factorize clocks API

Signed-off-by: Rémi Lefèvre <remi.lefevre@parrot.com>

diff --git a/src/clocks.c b/src/clocks.c
index f8dc9b628342072bf4ca2eeecb4107205b5f49f1..88d3783e8e6c6233ea26ce17617b76a352890014 100644 (file)
--- a/src/clocks.c
+++ b/src/clocks.c
@@ -11,55 +11,63 @@ inline int clock_gettime(clockid_t clk_id, struct timespec *ts) {
 }
 #endif
 
-inline time_t now_realtime_sec(void) {
+static inline time_t now_sec(clockid_t clk_id) {
     struct timespec ts;
-    if(unlikely(clock_gettime(CLOCK_REALTIME, &ts) == -1))
+    if(unlikely(clock_gettime(clk_id, &ts) == -1))
         return 0;
     return ts.tv_sec;
 }
 
-inline int now_realtime_timeval(struct timeval *tv) {
+static inline usec_t now_usec(clockid_t clk_id) {
+    struct timespec ts;
+    if(unlikely(clock_gettime(clk_id, &ts) == -1))
+        return 0;
+    return (usec_t)ts.tv_sec * USEC_PER_SEC + ts.tv_nsec / NSEC_PER_USEC;
+}
+
+static inline int now_timeval(clockid_t clk_id, struct timeval *tv) {
     struct timespec ts;
-    if(unlikely(clock_gettime(CLOCK_REALTIME, &ts) == -1))
+    if(unlikely(clock_gettime(clk_id, &ts) == -1))
         return -1;
     tv->tv_sec = ts.tv_sec;
     tv->tv_usec = ts.tv_nsec / NSEC_PER_USEC;
     return 0;
 }
 
+inline time_t now_realtime_sec(void) {
+    return now_sec(CLOCK_REALTIME);
+}
+
 inline usec_t now_realtime_usec(void) {
-    struct timespec ts;
-    if(unlikely(clock_gettime(CLOCK_REALTIME, &ts) == -1))
-        return 0;
-    return (usec_t)ts.tv_sec * USEC_PER_SEC + ts.tv_nsec / NSEC_PER_USEC;
+    return now_usec(CLOCK_REALTIME);
+}
+
+inline int now_realtime_timeval(struct timeval *tv) {
+    return now_timeval(CLOCK_REALTIME, tv);
 }
 
 inline time_t now_monotonic_sec(void) {
-    struct timespec ts;
-    if(unlikely(clock_gettime(CLOCK_MONOTONIC, &ts) == -1))
-        return 0;
-    return ts.tv_sec;
+    return now_sec(CLOCK_MONOTONIC);
 }
 
 inline usec_t now_monotonic_usec(void) {
-    struct timespec ts;
-    if(unlikely(clock_gettime(CLOCK_MONOTONIC, &ts) == -1))
-        return 0;
-    return (usec_t)ts.tv_sec * USEC_PER_SEC + ts.tv_nsec / NSEC_PER_USEC;
+    return now_usec(CLOCK_MONOTONIC);
+}
+
+inline int now_monotonic_timeval(struct timeval *tv) {
+    return now_timeval(CLOCK_MONOTONIC, tv);
 }
 
 inline time_t now_boottime_sec(void) {
-    struct timespec ts;
-    if(unlikely(clock_gettime(CLOCK_BOOTTIME, &ts) == -1))
-        return 0;
-    return ts.tv_sec;
+    return now_sec(CLOCK_BOOTTIME);
 }
 
 inline usec_t now_boottime_usec(void) {
-    struct timespec ts;
-    if(unlikely(clock_gettime(CLOCK_BOOTTIME, &ts) == -1))
-        return 0;
-    return (usec_t)ts.tv_sec * USEC_PER_SEC + ts.tv_nsec / NSEC_PER_USEC;
+    return now_usec(CLOCK_BOOTTIME);
+}
+
+inline int now_boottime_timeval(struct timeval *tv) {
+    return now_timeval(CLOCK_BOOTTIME, tv);
 }
 
 inline usec_t timeval_usec(struct timeval *tv) {

diff --git a/src/clocks.h b/src/clocks.h
index 39c0436f8327b4a86df06339e04b53a3fcddec2e..895f09ab4dbeac2b7caba20fed887a9df6b69b88 100644 (file)
--- a/src/clocks.h
+++ b/src/clocks.h
@@ -54,40 +54,44 @@ int clock_gettime(clockid_t clk_id, struct timespec *ts);
 extern int clock_gettime(clockid_t clk_id, struct timespec *ts);
 #endif
 
-/* Fills struct timeval with time since EPOCH from real-time clock (i.e. wall-clock).
- * - Hibernation/suspend time is included
- * - adjtime()/NTP adjustments affect this clock
- * Return 0 on succes, -1 else with errno set appropriately.
+/*
+ * Three clocks are available (cf. man 3 clock_gettime):
+ *
+ * REALTIME clock (i.e. wall-clock):
+ *  This clock is affected by discontinuous jumps in the system time
+ *  (e.g., if the system administrator manually changes the clock), and by the incremental adjustments performed by adjtime(3) and NTP.
+ *
+ * MONOTONIC clock
+ *  Clock that cannot be set and represents monotonic time since some unspecified starting point.
+ *  This clock is not affected by discontinuous jumps in the system time
+ *  (e.g., if the system administrator manually changes the clock), but is affected by the incremental adjustments performed by adjtime(3) and NTP.
+ *  If not available on the system, this clock falls back to REALTIME clock.
+ *
+ * BOOTTIME clock
+ *  Identical to  CLOCK_MONOTONIC, except it also includes any time that the system is suspended.
+ *  This allows applications to get a suspend-aware monotonic clock without having to deal with the complications of CLOCK_REALTIME,
+ *  which may have discontinuities if the time is changed using settimeofday(2).
+ *  If not available on the system, this clock falls back to MONOTONIC clock.
+ *
+ * All now_*_timeval() functions fill the `struct timeval` with the time from the appropriate clock.
+ * Those functions return 0 on success, -1 else with errno set appropriately.
+ *
+ * All now_*_sec() functions return the time in seconds from the approriate clock, or 0 on error.
+ * All now_*_usec() functions return the time in microseconds from the approriate clock, or 0 on error.
  */
 extern int now_realtime_timeval(struct timeval *tv);
-
-/* Returns time since EPOCH from real-time clock (i.e. wall-clock).
- * - Hibernation/suspend time is included
- * - adjtime()/NTP adjustments affect this clock
- */
 extern time_t now_realtime_sec(void);
 extern usec_t now_realtime_usec(void);
 
-/* Returns time from monotonic clock if available, real-time clock else.
- * If monotonic clock is available:
- * - hibernation/suspend time is not included
- * - adjtime()/NTP adjusments affect this clock
- * If monotonic clock is not available, this fallbacks to now_realtime().
- */
+extern int now_monotonic_timeval(struct timeval *tv);
 extern time_t now_monotonic_sec(void);
 extern usec_t now_monotonic_usec(void);
 
-/* Returns time from boottime clock if available,
- * monotonic clock else if available, real-time clock else.
- * If boottime clock is available:
- * - hibernation/suspend time is included
- * - adjtime()/NTP adjusments affect this clock
- * If boottime clock is not available, this fallbacks to now_monotonic().
- * If monotonic clock is not available, this fallbacks to now_realtime().
- */
+extern int now_boottime_timeval(struct timeval *tv);
 extern time_t now_boottime_sec(void);
 extern usec_t now_boottime_usec(void);
 
+
 extern usec_t timeval_usec(struct timeval *ts);
 extern usec_t dt_usec(struct timeval *now, struct timeval *old);