timers: implementation of lazily-ordered timers.

[ccan] / ccan / timer / _info

diff --git a/ccan/timer/_info b/ccan/timer/_info
new file mode 100644 (file)
index 0000000..cb6808b
--- /dev/null
+++ b/ccan/timer/_info
@@ -0,0 +1,80 @@
+#include <string.h>
+#include "config.h"
+
+/**
+ * timer - efficient implementation of rarely-expiring timers.
+ *
+ * This is a lazy implementation of timers: you can add and delete timers
+ * very quickly, and they are only sorted as their expiry approaches.
+ *
+ * This is a common case for timeouts, which must often be set, but
+ * rarely expire.
+ *
+ * Example:
+ *     // Silly example which outputs strings until timers expire.
+ *     #include <ccan/timer/timer.h>
+ *     #include <ccan/time/time.h>
+ *     #include <stdlib.h>
+ *     #include <stdio.h>
+ *
+ *     struct timed_string {
+ *             struct list_node node;
+ *             struct timer timer;
+ *             const char *string;
+ *     };
+ *
+ *     int main(int argc, char *argv[])
+ *     {
+ *             struct timers timers;
+ *             struct list_head strings;
+ *             struct list_head expired;
+ *             struct timed_string *s;
+ *
+ *             timers_init(&timers, time_now());
+ *             list_head_init(&strings);
+ *
+ *             while (argv[1]) {
+ *                     s = malloc(sizeof(*s));
+ *                     s->string = argv[1];
+ *                     timer_add(&timers, &s->timer,
+ *                               time_add(time_now(),
+ *                                        time_from_msec(atol(argv[2]))));
+ *                     list_add_tail(&strings, &s->node);
+ *                     argv += 2;
+ *             }
+ *
+ *             while (!list_empty(&strings)) {
+ *                     struct timespec now = time_now();
+ *                     list_for_each(&strings, s, node)
+ *                             printf("%s", s->string);
+ *                     timers_expire(&timers, now, &expired);
+ *                     while ((s = list_pop(&expired, struct timed_string,
+ *                                          timer.list)) != NULL) {
+ *                             list_del_from(&strings, &s->node);
+ *                             free(s);
+ *                     }
+ *             }
+ *
+ *             exit(0);
+ *     }
+ *
+ * License: LGPL (v2.1 or any later version)
+ * Author: Rusty Russell <rusty@rustcorp.com.au>
+ */
+int main(int argc, char *argv[])
+{
+       /* Expect exactly one argument */
+       if (argc != 2)
+               return 1;
+
+       if (strcmp(argv[1], "depends") == 0) {
+               printf("ccan/array_size\n");
+               printf("ccan/ilog\n");
+               printf("ccan/likely\n");
+               printf("ccan/list\n");
+               printf("ccan/time\n");
+               return 0;
+       }
+
+       return 1;
+}