lbalance: new module for load balancing
[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 struct lbalance *lbalance_new(void);
14
15 /**
16  * lbalance_task_new - mark the starting of a new task.
17  * @lbalance: the load balancer from lbalance_new.
18  */
19 struct lbalance_task *lbalance_task_new(struct lbalance *lbalance);
20
21 /**
22  * lbalance_task_free - mark the completion of a task.
23  * @task: the lbalance_task from lbalance_task_new, which will be freed.
24  * @usage: the resource usage for that task (or NULL).
25  *
26  * If @usage is NULL, you must have already wait()ed for the child so
27  * that lbalance_task_free() can derive it from the difference in
28  * getrusage() for the child processes.
29  *
30  * Otherwise, lbalance_task_free() is a noop, which is useful for failure
31  * paths.
32  */
33 void lbalance_task_free(struct lbalance_task *task,
34                         const struct rusage *usage);
35
36 /**
37  * lbalance_target - how many tasks in parallel are recommended?
38  * @lbalance: the load balancer from lbalance_new.
39  *
40  * Normally you keep creating tasks until this limit is reached.  It's
41  * updated by stats from lbalance_task_free.
42  */
43 unsigned lbalance_target(struct lbalance *lbalance);
44
45 /**
46  * lbalance_free - free a load balancing structure.
47  * @lbalance: the load balancer from lbalance_new.
48  *
49  * Also frees any tasks still attached.
50  */
51 void lbalance_free(struct lbalance *lbalance);
52 #endif /* CCAN_LBALANCE_H */