lbalance: add examples.
[ccan] / ccan / lbalance / lbalance.h
1 #ifndef CCAN_LBALANCE_H
2 #define CCAN_LBALANCE_H
3 #include "config.h"
4
5 struct lbalance;
6 struct lbalance_task;
7 struct timeval;
8 struct rusage;
9
10 /**
11  * lbalance_new - initialize a load balancing structure.
12  *
13  * Example:
14  *      struct lbalance *lb = lbalance_new();
15  *
16  *      // ...
17  *
18  *      lbalance_free(lb);
19  *      return 0;
20  */
21 struct lbalance *lbalance_new(void);
22
23 /**
24  * lbalance_free - free a load balancing structure.
25  * @lbalance: the load balancer from lbalance_new.
26  *
27  * Also frees any tasks still attached.
28  */
29 void lbalance_free(struct lbalance *lbalance);
30
31 /**
32  * lbalance_task_new - mark the starting of a new task.
33  * @lbalance: the load balancer from lbalance_new.
34  *
35  * Example:
36  *      static pid_t run_child(struct lbalance *lb, struct lbalance_task **task)
37  *      {
38  *              pid_t pid = fork();
39  *              if (pid != 0) {
40  *                      // We are the parent, return.
41  *                      *task = lbalance_task_new(lb);
42  *                      return pid;
43  *              }
44  *              // otherwise do some work...
45  *              exit(0);
46  *      }
47  */
48 struct lbalance_task *lbalance_task_new(struct lbalance *lbalance);
49
50 /**
51  * lbalance_task_free - mark the completion of a task.
52  * @task: the lbalance_task from lbalance_task_new, which will be freed.
53  * @usage: the resource usage for that task (or NULL).
54  *
55  * If @usage is NULL, you must have already wait()ed for the child so
56  * that lbalance_task_free() can derive it from the difference in
57  * getrusage() for the child processes.
58  *
59  * Otherwise, lbalance_task_free() is a noop, which is useful for failure
60  * paths.
61  *
62  * Example:
63  *      #include <sys/types.h>
64  *      #include <sys/time.h>
65  *      #include <sys/resource.h>
66  *      #include <sys/wait.h>
67  *
68  *      static void wait_for_child(struct lbalance_task *task)
69  *      {
70  *              struct rusage ru;
71  *              // Wait for child to finish, get usage.
72  *              wait4(-1, NULL, 0, &ru);
73  *              // Tell lbalancer about usage, free struct lbalance_task.
74  *              lbalance_task_free(task, &ru);
75  *      }
76  */
77 void lbalance_task_free(struct lbalance_task *task,
78                         const struct rusage *usage);
79
80 /**
81  * lbalance_target - how many tasks in parallel are recommended?
82  * @lbalance: the load balancer from lbalance_new.
83  *
84  * Normally you keep creating tasks until this limit is reached.  It's
85  * updated by stats from lbalance_task_free.
86  *
87  * Example:
88  *      int main(void)
89  *      {
90  *              unsigned int num_running = 0;
91  *              struct lbalance *lb = lbalance_new();
92  *
93  *              for (;;) {
94  *                      // Run more until we reach target.
95  *                      while (num_running < lbalance_target(lb)) {
96  *                              // Run another one.
97  *                      }
98  *
99  *                      // Wait for something to finish.
100  *              }
101  *      }
102  */
103 unsigned lbalance_target(struct lbalance *lbalance);
104
105 #endif /* CCAN_LBALANCE_H */