tdb2: test: fix run-57-die-during-transaction.c to be more efficient.

[ccan] / ccan / lbalance / lbalance.h

diff --git a/ccan/lbalance/lbalance.h b/ccan/lbalance/lbalance.h
index d318a6fe84b78344dd993f2b83a82e19df248d1d..943e1636603ea037e1de05bfb091785ed8c61396 100644 (file)
--- a/ccan/lbalance/lbalance.h
+++ b/ccan/lbalance/lbalance.h
@@ -1,3 +1,4 @@
+/* Licensed under GPLv3+ - see LICENSE file for details */

 #ifndef CCAN_LBALANCE_H
 #define CCAN_LBALANCE_H
 #include "config.h"
 #ifndef CCAN_LBALANCE_H
 #define CCAN_LBALANCE_H
 #include "config.h"


@@ -9,12 +10,41 @@ struct rusage;
 
 /**
  * lbalance_new - initialize a load balancing structure.
 
 /**
  * lbalance_new - initialize a load balancing structure.

+ *
+ * Example:
+ *     struct lbalance *lb = lbalance_new();
+ *
+ *     // ...
+ *
+ *     lbalance_free(lb);
+ *     return 0;

  */
 struct lbalance *lbalance_new(void);
 
  */
 struct lbalance *lbalance_new(void);
 

+/**
+ * lbalance_free - free a load balancing structure.
+ * @lbalance: the load balancer from lbalance_new.
+ *
+ * Also frees any tasks still attached.
+ */
+void lbalance_free(struct lbalance *lbalance);
+

 /**
  * lbalance_task_new - mark the starting of a new task.
  * @lbalance: the load balancer from lbalance_new.
 /**
  * lbalance_task_new - mark the starting of a new task.
  * @lbalance: the load balancer from lbalance_new.

+ *
+ * Example:
+ *     static pid_t run_child(struct lbalance *lb, struct lbalance_task **task)
+ *     {
+ *             pid_t pid = fork();
+ *             if (pid != 0) {
+ *                     // We are the parent, return.
+ *                     *task = lbalance_task_new(lb);
+ *                     return pid;
+ *             }
+ *             // otherwise do some work...
+ *             exit(0);
+ *     }

  */
 struct lbalance_task *lbalance_task_new(struct lbalance *lbalance);
 
  */
 struct lbalance_task *lbalance_task_new(struct lbalance *lbalance);
 


@@ -29,6 +59,21 @@ struct lbalance_task *lbalance_task_new(struct lbalance *lbalance);
  *
  * Otherwise, lbalance_task_free() is a noop, which is useful for failure
  * paths.
  *
  * Otherwise, lbalance_task_free() is a noop, which is useful for failure
  * paths.

+ *
+ * Example:
+ *     #include <sys/types.h>
+ *     #include <sys/time.h>
+ *     #include <sys/resource.h>
+ *     #include <sys/wait.h>
+ *
+ *     static void wait_for_child(struct lbalance_task *task)
+ *     {
+ *             struct rusage ru;
+ *             // Wait for child to finish, get usage.
+ *             wait4(-1, NULL, 0, &ru);
+ *             // Tell lbalancer about usage, free struct lbalance_task.
+ *             lbalance_task_free(task, &ru);
+ *     }

  */
 void lbalance_task_free(struct lbalance_task *task,
                        const struct rusage *usage);
  */
 void lbalance_task_free(struct lbalance_task *task,
                        const struct rusage *usage);


@@ -39,14 +84,23 @@ void lbalance_task_free(struct lbalance_task *task,
  *
  * Normally you keep creating tasks until this limit is reached.  It's
  * updated by stats from lbalance_task_free.
  *
  * Normally you keep creating tasks until this limit is reached.  It's
  * updated by stats from lbalance_task_free.

+ *
+ * Example:
+ *     int main(void)
+ *     {
+ *             unsigned int num_running = 0;
+ *             struct lbalance *lb = lbalance_new();
+ *
+ *             for (;;) {
+ *                     // Run more until we reach target.
+ *                     while (num_running < lbalance_target(lb)) {
+ *                             // Run another one.
+ *                     }
+ *
+ *                     // Wait for something to finish.
+ *             }
+ *     }

  */
 unsigned lbalance_target(struct lbalance *lbalance);
 
  */
 unsigned lbalance_target(struct lbalance *lbalance);
 

-/**
- * lbalance_free - free a load balancing structure.
- * @lbalance: the load balancer from lbalance_new.
- *
- * Also frees any tasks still attached.
- */
-void lbalance_free(struct lbalance *lbalance);

 #endif /* CCAN_LBALANCE_H */
 #endif /* CCAN_LBALANCE_H */