json_out: make json_out_finished finish buffer.
[ccan] / 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  * #include <ccan/io/io_plan.h>
39  *
40  * // Simple helper to read a single char.
41  * static int do_readchar(int fd, struct io_plan_arg *arg)
42  * {
43  *      return read(fd, arg->u1.cp, 1) <= 0 ? -1 : 1;
44  * }
45  *
46  * static struct io_plan *io_read_char_(struct io_conn *conn, char *in,
47  *                               struct io_plan *(*next)(struct io_conn*,void*),
48  *                               void *next_arg)
49  * {
50  *      struct io_plan_arg *arg = io_plan_arg(conn, IO_IN);
51  *
52  *      // Store information we need in the plan unions u1 and u2.
53  *      arg->u1.cp = in;
54  *
55  *      return io_set_plan(conn, IO_IN, do_readchar, next, next_arg);
56  * }
57  */
58 struct io_plan_arg *io_plan_arg(struct io_conn *conn, enum io_direction dir);
59
60 /**
61  * io_set_plan - set a conn's io_plan.
62  * @conn: the connection.
63  * @dir: IO_IN or IO_OUT.
64  * @io: the IO function to call when the fd is ready.
65  * @next: the next callback when @io returns 1.
66  * @next_arg: the argument to @next.
67  *
68  * If @conn has debug set, the io function will be called immediately,
69  * so it's important that this be the last thing in your function!
70  *
71  * See also:
72  *      io_get_plan_arg()
73  */
74 struct io_plan *io_set_plan(struct io_conn *conn, enum io_direction dir,
75                             int (*io)(int fd, struct io_plan_arg *arg),
76                             struct io_plan *(*next)(struct io_conn *, void *),
77                             void *next_arg);
78 #endif /* CCAN_IO_PLAN_H */