#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
* 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;
* }
*
* {
* 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();
* 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;
* 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);
*