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_union - type for struct io_plan read/write fns.
   8  */
   9 union io_plan_union {
  10         char *cp;
  11         void *vp;
  12         const void *const_vp;
  13         size_t s;
  14         char c[sizeof(size_t)];
  15 };
  16
  17 /**
  18  * struct io_plan_arg - scratch space for struct io_plan read/write fns.
  19  */
  20 struct io_plan_arg {
  21         union io_plan_union u1, u2;
  22 };
  23
  24 enum io_direction {
  25         IO_IN,
  26         IO_OUT
  27 };
  28
  29 /**
  30  * io_plan_arg - get a conn's io_plan_arg for a given direction.
  31  * @conn: the connection.
  32  * @dir: IO_IN or IO_OUT.
  33  *
  34  * This is how an io helper gets scratch space to store into; you must call
  35  * io_set_plan() when you've initialized it.
  36  *
  37  * Example:
  38  * // Simple helper to read a single char.
  39  * static int do_readchar(int fd, struct io_plan_arg *arg)
  40  * {
  41  *      return read(fd, arg->u1.cp, 1) <= 0 ? -1 : 1;
  42  * }
  43  *
  44  * struct io_plan *io_read_char_(struct io_conn *conn, char *in,
  45  *                               struct io_plan *(*next)(struct io_conn*,void*),
  46  *                               void *arg)
  47  * {
  48  *      struct io_plan_arg *arg = io_get_plan_arg(conn, IO_IN);
  49  *
  50  *      // Store information we need in the plan unions u1 and u2.
  51  *      arg->u1.cp = in;
  52  *
  53  *      return io_set_plan(conn, IO_IN, do_readchar, next, arg);
  54  * }
  55  */
  56 struct io_plan_arg *io_plan_arg(struct io_conn *conn, enum io_direction dir);
  57
  58 /**
  59  * io_set_plan - set a conn's io_plan.
  60  * @conn: the connection.
  61  * @dir: IO_IN or IO_OUT.
  62  * @io: the IO function to call when the fd is ready.
  63  * @next: the next callback when @io returns 1.
  64  * @next_arg: the argument to @next.
  65  *
  66  * If @conn has debug set, the io function will be called immediately,
  67  * so it's important that this be the last thing in your function!
  68  *
  69  * See also:
  70  *      io_get_plan_arg()
  71  */
  72 struct io_plan *io_set_plan(struct io_conn *conn, enum io_direction dir,
  73                             int (*io)(int fd, struct io_plan_arg *arg),
  74                             struct io_plan *(*next)(struct io_conn *, void *),
  75                             void *next_arg);
  76 #endif /* CCAN_IO_PLAN_H */