time: new module for dealing with time.

[ccan] / ccan / time / time.h

diff --git a/ccan/time/time.h b/ccan/time/time.h
new file mode 100644 (file)
index 0000000..e3a5791
--- /dev/null
+++ b/ccan/time/time.h
@@ -0,0 +1,183 @@
+#ifndef CCAN_TIME_H
+#define CCAN_TIME_H
+#include "config.h"
+#include <sys/time.h>
+#include <stdint.h>
+#include <stdbool.h>
+
+/**
+ * time_now - return the current time
+ *
+ * Example:
+ *     printf("Now is %lu seconds since epoch\n", (long)time_now().tv_sec);
+ */
+struct timeval time_now(void);
+
+/**
+ * time_greater - is a after b?
+ * @a: one time.
+ * @b: another time.
+ *
+ * Example:
+ *     static bool timed_out(const struct timeval *start)
+ *     {
+ *     #define TIMEOUT time_from_msec(1000)
+ *             return time_greater(time_now(), time_add(*start, TIMEOUT));
+ *     }
+ */
+bool time_greater(struct timeval a, struct timeval b);
+
+/**
+ * time_less - is a before b?
+ * @a: one time.
+ * @b: another time.
+ *
+ * Example:
+ *     static bool still_valid(const struct timeval *start)
+ *     {
+ *     #define TIMEOUT time_from_msec(1000)
+ *             return time_less(time_now(), time_add(*start, TIMEOUT));
+ *     }
+ */
+bool time_less(struct timeval a, struct timeval b);
+
+/**
+ * time_eq - is a equal to b?
+ * @a: one time.
+ * @b: another time.
+ *
+ * Example:
+ *     #include <sys/types.h>
+ *     #include <sys/wait.h>
+ *
+ *     // Can we fork in under a microsecond?
+ *     static bool fast_fork(void)
+ *     {
+ *             struct timeval start = time_now();
+ *             if (fork() != 0) {
+ *                     exit(0);
+ *             }
+ *             wait(NULL);
+ *             return time_eq(start, time_now());
+ *     }
+ */
+bool time_eq(struct timeval a, struct timeval b);
+
+/**
+ * time_sub - subtract two times
+ * @recent: the larger (more recent) time.
+ * @old: the smaller (less recent) time.
+ *
+ * This returns a well formed struct timeval.
+ *
+ * Example:
+ *     static bool was_recent(const struct timeval *start)
+ *     {
+ *             return time_sub(time_now(), *start).tv_sec < 1;
+ *     }
+ */
+struct timeval time_sub(struct timeval recent, struct timeval old);
+
+/**
+ * time_add - add two times
+ * @a: one time.
+ * @b: another time.
+ *
+ * The times must not overflow, or the results are undefined.
+ *
+ * Example:
+ *     // We do one every second.
+ *     static struct timeval next_time(void)
+ *     {
+ *             return time_add(time_now(), time_from_msec(1000));
+ *     }
+ */
+struct timeval time_add(struct timeval a, struct timeval b);
+
+/**
+ * time_divide - divide a time by a value.
+ * @t: a time.
+ * @div: number to divide it by.
+ *
+ * Example:
+ *     // How long does it take to do a fork?
+ *     static struct timeval forking_time(void)
+ *     {
+ *             struct timeval start = time_now();
+ *             unsigned int i;
+ *
+ *             for (i = 0; i < 1000; i++) {
+ *                     if (fork() != 0) {
+ *                             exit(0);
+ *                     }
+ *                     wait(NULL);
+ *             }
+ *             return time_divide(time_sub(time_now(), start), i);
+ *     }
+ */
+struct timeval time_divide(struct timeval t, unsigned long div);
+
+/**
+ * time_multiply - multiply a time by a value.
+ * @t: a time.
+ * @mult: number to multiply it by.
+ *
+ * Example:
+ *     ...
+ *     printf("Time to do 100000 forks would be %u sec\n",
+ *            (unsigned)time_multiply(forking_time(), 1000000).tv_sec);
+ */
+struct timeval time_multiply(struct timeval t, unsigned long mult);
+
+/**
+ * time_to_msec - return number of milliseconds
+ * @t: a time
+ *
+ * It's often more convenient to deal with time values as
+ * milliseconds.  Note that this will fit into a 32-bit variable if
+ * it's a time difference of less than ~7 weeks.
+ *
+ * Example:
+ *     ...
+ *     printf("Forking time is %u msec\n",
+ *            (unsigned)time_to_msec(forking_time()));
+ */
+uint64_t time_to_msec(struct timeval t);
+
+/**
+ * time_to_usec - return number of microseconds
+ * @t: a time
+ *
+ * It's often more convenient to deal with time values as
+ * microseconds.  Note that this will fit into a 32-bit variable if
+ * it's a time difference of less than ~1 hour.
+ *
+ * Example:
+ *     ...
+ *     printf("Forking time is %u usec\n",
+ *            (unsigned)time_to_usec(forking_time()));
+ *
+ */
+uint64_t time_to_usec(struct timeval t);
+
+/**
+ * time_from_msec - convert milliseconds to a timeval
+ * @msec: time in milliseconds
+ *
+ * Example:
+ *     // 1/2 second timeout
+ *     #define TIMEOUT time_from_msec(500)
+ */
+struct timeval time_from_msec(uint64_t msec);
+
+/**
+ * time_from_usec - convert microseconds to a timeval
+ * @usec: time in microseconds
+ *
+ * Example:
+ *     // 1/2 second timeout
+ *     #define TIMEOUT time_from_usec(500000)
+ */
+struct timeval time_from_usec(uint64_t usec);
+
+#endif /* CCAN_TIME_H */