git.ozlabs.org Git - ccan/blob - ccan/io/io_plan.h

   1 /* Licensed under LGPLv2.1+ - see LICENSE file for details */
   2 #ifndef CCAN_IO_PLAN_H
   3 #define CCAN_IO_PLAN_H
   4 struct io_conn;
   5
   6 /**
   7  * union io_plan_arg - scratch space for struct io_plan read/write fns.
   8  */
   9 union io_plan_arg {
  10         char *cp;
  11         void *vp;
  12         const void *const_vp;
  13         size_t s;
  14         char c[sizeof(size_t)];
  15 };
  16
  17 enum io_plan_status {
  18         /* As before calling next function. */
  19         IO_UNSET,
  20         /* Normal. */
  21         IO_POLLING,
  22         /* Waiting for io_wake */
  23         IO_WAITING,
  24         /* Always do this. */
  25         IO_ALWAYS,
  26         /* Closing (both plans will be the same). */
  27         IO_CLOSING
  28 };
  29
  30 enum io_direction {
  31         IO_IN,
  32         IO_OUT
  33 };
  34
  35 /**
  36  * struct io_plan - one half of I/O to do
  37  * @status: the status of this plan.
  38  * @io: function to call when fd becomes read/writable, returns 0 to be
  39  *      called again, 1 if it's finished, and -1 on error (fd will be closed)
  40  * @next: the next function which is called if io returns 1.
  41  * @next_arg: the argument to @next
  42  * @u1, @u2: scratch space for @io.
  43  */
  44 struct io_plan {
  45         enum io_plan_status status;
  46
  47         int (*io)(int fd, struct io_plan *plan);
  48
  49         struct io_plan *(*next)(struct io_conn *, void *arg);
  50         void *next_arg;
  51
  52         union io_plan_arg u1, u2;
  53 };
  54
  55 /**
  56  * io_get_plan - get a conn's io_plan for a given direction.
  57  * @conn: the connection.
  58  * @dir: IO_IN or IO_OUT.
  59  *
  60  * This is how an io helper gets a plan to store into; you must call
  61  * io_done_plan() when you've initialized it.
  62  *
  63  * Example:
  64  * // Simple helper to read a single char.
  65  * static int do_readchar(int fd, struct io_plan *plan)
  66  * {
  67  *      return read(fd, plan->u1.cp, 1) <= 0 ? -1 : 1;
  68  * }
  69  *
  70  * struct io_plan *io_read_char_(struct io_conn *conn, char *in,
  71  *                               struct io_plan *(*next)(struct io_conn*,void*),
  72  *                               void *arg)
  73  * {
  74  *      struct io_plan *plan = io_get_plan(conn, IO_IN);
  75  *
  76  *      // Store information we need in the plan unions u1 and u2.
  77  *      plan->u1.cp = in;
  78  *
  79  *      return io_set_plan(conn, plan, do_readchar, next, arg);
  80  * }
  81  */
  82 struct io_plan *io_get_plan(struct io_conn *conn, enum io_direction dir);
  83
  84 /**
  85  * io_set_plan - set a conn's io_plan.
  86  * @conn: the connection.
  87  * @plan: the plan
  88  * @io: the IO function to call when the fd is ready.
  89  * @next: the next callback when @io returns 1.
  90  * @next_arg: the argument to @next.
  91  *
  92  * If @conn has debug set, the io function will be called immediately,
  93  * so it's important that this be the last thing in your function!
  94  *
  95  * See also:
  96  *      io_get_plan()
  97  */
  98 struct io_plan *io_set_plan(struct io_conn *conn, struct io_plan *plan,
  99                             int (*io)(int fd, struct io_plan *plan),
 100                             struct io_plan *(*next)(struct io_conn *, void *),
 101                             void *next_arg);
 102 #endif /* CCAN_IO_PLAN_H */