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