lbalance: add examples.

[ccan] / ccan / lbalance / _info

diff --git a/ccan/lbalance/_info b/ccan/lbalance/_info
index c0d0ab0e5a4fa7fb362b0ebb8a0a15da53ee9627..e3e9c78e7a32434f858f27a2c4533f8b2afc1bdd 100644 (file)
--- a/ccan/lbalance/_info
+++ b/ccan/lbalance/_info
@@ -9,6 +9,72 @@
  *
  * License: GPL
  * Author: Rusty Russell <rusty@rustcorp.com.au>
+ *
+ * Example:
+ *     // Run 1000 of the given commandline at best-known parallel rate.
+ *     // See tools/lbalance.c for a sligtly more serious example.
+ *     #include <ccan/lbalance/lbalance.h>
+ *      #include <sys/types.h>
+ *      #include <sys/time.h>
+ *      #include <sys/resource.h>
+ *      #include <sys/wait.h>
+ *      #include <err.h>
+ *
+ *     #define MAX 1000
+ *
+ *     static pid_t spawn(char *args[])
+ *     {
+ *             pid_t pid = fork();
+ *
+ *             if (pid == -1)
+ *                     err(1, "forking");
+ *             if (pid == 0) {
+ *                     execvp(args[0], args);
+ *                     err(1, "exec failed");
+ *             }
+ *             return pid;
+ *     }
+ *
+ *     int main(int argc, char *argv[])
+ *     {
+ *             unsigned int num = 0, num_running = 0;
+ *             pid_t pids[MAX];
+ *             struct lbalance_task *tasks[MAX];
+ *             struct lbalance *lb;
+ *
+ *             if (argc == 1)
+ *                     errx(1, "Usage: %s cmdline...", argv[0]);
+ *
+ *             lb = lbalance_new();
+ *
+ *             while (num - num_running < MAX) {
+ *                     struct rusage ru;
+ *                     pid_t pid;
+ *                     unsigned int i;
+ *
+ *                     // Make sure we're running as many as lbalance says to. 
+ *                     while (num_running < lbalance_target(lb) && num < MAX) {
+ *                             pids[num] = spawn(argv+1);
+ *                             tasks[num] = lbalance_task_new(lb);
+ *                             num++;
+ *                             num_running++;
+ *                     }
+ *
+ *                     // Now wait for something to die.
+ *                     pid = wait3(NULL, 0, &ru);
+ *                     // Find it, tell lbalance it's finished.
+ *                     for (i = 0; i < num; i++) {
+ *                             if (pids[i] == pid) {
+ *                                     lbalance_task_free(tasks[i], &ru);
+ *                                     pids[i] = 0;
+ *                                     break;
+ *                             }
+ *                     }
+ *                     num_running--;
+ *             }
+ *             lbalance_free(lb);
+ *             return 0;
+ *     }
  */
 int main(int argc, char *argv[])
 {