X-Git-Url: https://git.ozlabs.org/?p=ccan;a=blobdiff_plain;f=ccan%2Fio%2F_info;h=235e6ba3d281df8ee8f7576030ceabcc9779e533;hp=0dfb43c60ef52d837d0a00dd7eb95c37a77af7c2;hb=641b511049e5c03d45ada0c3fd829691b173e5d1;hpb=57d9d1be33905691ec756b14b066181ca6850ced

diff --git a/ccan/io/_info b/ccan/io/_info
index 0dfb43c6..235e6ba3 100644
--- a/ccan/io/_info
+++ b/ccan/io/_info
@@ -3,12 +3,18 @@
 #include "config.h"
 
 /**
- * io - simple library for stateful io handling.
+ * io - simple library for asynchronous io handling.
  *
- * io provides a simple mechanism to write I/O servers with multiple
- * connections.  Handling of connections is multiplexed, and function
- * indicate what they want written or read, and what follow-on
- * function to call on success (or failure).
+ * io provides a mechanism to write I/O servers with multiple
+ * connections.  Each callback indicates what I/O they plan next
+ * (eg. read, write).  It is also possible to write custom I/O
+ * plans.
+ *
+ * When compiled with DEBUG, control flow is changed so that rather
+ * than returning to the main io_loop(), plans are executed sequentially
+ * providing a backtrace showing what has occurred on that connection.
+ * Which connection(s) do this depends on the user-specified io_debug
+ * function.
  *
  * Example:
  * // Given tr A-Z a-z outputs tr a-z a-z
@@ -46,7 +52,7 @@
  * static void reader_exit(struct io_conn *c, struct stdin_buffer *b)
  * {
  * 	assert(c == b->reader);
- * 	io_wake(b->writer, io_close(b->writer, NULL));
+ * 	io_wake(b->writer, io_close());
  * 	b->reader = NULL;
  * }
  *
@@ -54,7 +60,7 @@
  * {
  * 	assert(c == b->writer);
  *	if (!b->reader)
- *		return io_close(c, NULL);
+ *		return io_close();
  *	b->len = sizeof(b->inbuf);
  * 	io_wake(b->reader, io_read_partial(b->inbuf, &b->len, wake_writer, b));
  * 	return io_idle();
@@ -114,10 +120,8 @@
  *	sbuf.len = sizeof(sbuf.inbuf);
  * 	sbuf.reader = io_new_conn(STDIN_FILENO,
  *				  io_read_partial(sbuf.inbuf, &sbuf.len,
- *						  wake_writer, &sbuf),
- *				  reader_exit, &sbuf);
- * 	sbuf.writer = io_new_conn(tochild[1], io_idle(), fail_child_write,
- * 				  &sbuf);
+ *						  wake_writer, &sbuf));
+ * 	sbuf.writer = io_new_conn(tochild[1], io_idle());
  *
  *	out.max = 128;
  *	out.off = 0;
@@ -125,11 +129,13 @@
  *	out.buf = malloc(out.max);
  *	from_child = io_new_conn(fromchild[0],
  *				 io_read_partial(out.buf, &out.rlen,
- *						 read_from_child, &out),
- *				 NULL, NULL);
+ *						 read_from_child, &out));
  * 	if (!sbuf.reader || !sbuf.writer || !from_child)
  * 		err(1, "Allocating connections");
  *
+ *	io_set_finish(sbuf.reader, reader_exit, &sbuf);
+ *	io_set_finish(sbuf.writer, fail_child_write, &sbuf);
+ *
  * 	io_loop();
  * 	wait(&status);
  *