git.ozlabs.org Git - ccan/blob - 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 */