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