ccan/io: implement debug.

[ccan] / ccan / io / io_plan.h

diff --git a/ccan/io/io_plan.h b/ccan/io/io_plan.h
index 21a1921734f41e83d2ed836e157e4849496fb8ad..3bc2770ffb4abf8e997ad7aa6ea2e62ce6c54e86 100644 (file)
--- a/ccan/io/io_plan.h
+++ b/ccan/io/io_plan.h
@@ -52,7 +52,51 @@ struct io_plan {
        union io_plan_arg u1, u2;
 };
 
-/* Helper to get a conn's io_plan. */
+/**
+ * io_get_plan - get a conn's io_plan for a given direction.
+ * @conn: the connection.
+ * @dir: IO_IN or IO_OUT.
+ *
+ * This is how an io helper gets a plan to store into; you must call
+ * io_done_plan() when you've initialized it.
+ *
+ * Example:
+ * // Simple helper to read a single char.
+ * static int do_readchar(int fd, struct io_plan *plan)
+ * {
+ *     return read(fd, plan->u1.cp, 1) <= 0 ? -1 : 1;
+ * }
+ *
+ * struct io_plan *io_read_char_(struct io_conn *conn, char *in,
+ *                              struct io_plan *(*next)(struct io_conn*,void*),
+ *                              void *arg)
+ * {
+ *     struct io_plan *plan = io_get_plan(conn, IO_IN);
+ *
+ *     // Store information we need in the plan unions u1 and u2.
+ *     plan->u1.cp = in;
+ *
+ *     return io_set_plan(conn, plan, do_readchar, next, arg);
+ * }
+ */
 struct io_plan *io_get_plan(struct io_conn *conn, enum io_direction dir);
 
+/**
+ * io_set_plan - set a conn's io_plan.
+ * @conn: the connection.
+ * @plan: the plan
+ * @io: the IO function to call when the fd is ready.
+ * @next: the next callback when @io returns 1.
+ * @next_arg: the argument to @next.
+ *
+ * If @conn has debug set, the io function will be called immediately,
+ * so it's important that this be the last thing in your function!
+ *
+ * See also:
+ *     io_get_plan()
+ */
+struct io_plan *io_set_plan(struct io_conn *conn, struct io_plan *plan,
+                           int (*io)(int fd, struct io_plan *plan),
+                           struct io_plan *(*next)(struct io_conn *, void *),
+                           void *next_arg);
 #endif /* CCAN_IO_PLAN_H */