1 /* Licensed under LGPLv2.1+ - see LICENSE file for details */
4 #include <ccan/tal/tal.h>
5 #include <ccan/typesafe_cb/typesafe_cb.h>
13 * struct io_plan - a plan for input or output.
15 * Each io_conn has zero to two of these active at any time.
20 * struct io_conn - a connection associated with an fd.
25 * io_new_conn - create a new connection.
26 * @ctx: the context to tal from (or NULL)
27 * @fd: the file descriptor.
28 * @init: the function to call for a new connection
29 * @arg: the argument to @init.
31 * This creates a connection which owns @fd, it then calls
32 * @init to initialize the connection, which sets up an io_plan.
34 * Returns NULL on error (and sets errno).
37 * // Dumb init function to print string and tell conn to close.
38 * static struct io_plan *conn_init(struct io_conn *conn, const char *msg)
40 * printf("Created conn %p: %s", conn, msg);
41 * return io_close(conn);
44 * static void create_self_closing_pipe(void)
47 * struct io_conn *conn;
50 * conn = io_new_conn(NULL, fd[0], conn_init, (const char *)"hi!");
55 #define io_new_conn(ctx, fd, init, arg) \
56 io_new_conn_((ctx), (fd), \
57 typesafe_cb_preargs(struct io_plan *, void *, \
59 struct io_conn *conn), \
62 struct io_conn *io_new_conn_(const tal_t *ctx, int fd,
63 struct io_plan *(*init)(struct io_conn *, void *),
67 * io_set_finish - set finish function on a connection.
68 * @conn: the connection.
69 * @finish: the function to call when it's closed or fails.
70 * @arg: the argument to @finish.
72 * @finish will be called when an I/O operation fails, or you call
73 * io_close() on the connection. errno will be set to the value
74 * after the failed I/O, or at the call to io_close(). The fd
75 * will be closed before @finish is called.
78 * static void finish(struct io_conn *conn, const char *msg)
80 * // errno is not 0 after success, so this is a bit useless.
81 * printf("Conn %p closed with errno %i (%s)\n", conn, errno, msg);
84 * // Dumb init function to print string and tell conn to close.
85 * static struct io_plan *conn_init(struct io_conn *conn, const char *msg)
87 * io_set_finish(conn, finish, msg);
88 * return io_close(conn);
91 #define io_set_finish(conn, finish, arg) \
92 io_set_finish_((conn), \
93 typesafe_cb_preargs(void, void *, \
97 void io_set_finish_(struct io_conn *conn,
98 void (*finish)(struct io_conn *, void *),
103 * io_new_listener - create a new accepting listener.
104 * @ctx: the context to tal from (or NULL)
105 * @fd: the file descriptor.
106 * @init: the function to call for a new connection
107 * @arg: the argument to @init.
109 * When @fd becomes readable, we accept(), create a new connection,
110 * (tal'ocated off @ctx) and pass that to init().
112 * Returns NULL on error (and sets errno).
115 * #include <sys/types.h>
116 * #include <sys/socket.h>
121 * // Set up a listening socket, return it.
122 * static struct io_listener *do_listen(const char *port)
124 * struct addrinfo *addrinfo, hints;
127 * memset(&hints, 0, sizeof(hints));
128 * hints.ai_family = AF_UNSPEC;
129 * hints.ai_socktype = SOCK_STREAM;
130 * hints.ai_flags = AI_PASSIVE;
131 * hints.ai_protocol = 0;
133 * if (getaddrinfo(NULL, port, &hints, &addrinfo) != 0)
136 * fd = socket(addrinfo->ai_family, addrinfo->ai_socktype,
137 * addrinfo->ai_protocol);
141 * freeaddrinfo(addrinfo);
142 * setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &on, sizeof(on));
143 * if (bind(fd, addrinfo->ai_addr, addrinfo->ai_addrlen) != 0) {
147 * if (listen(fd, 1) != 0) {
151 * return io_new_listener(NULL, fd, conn_init, (const char *)"listened!");
154 #define io_new_listener(ctx, fd, init, arg) \
155 io_new_listener_((ctx), (fd), \
156 typesafe_cb_preargs(struct io_plan *, void *, \
158 struct io_conn *conn), \
160 struct io_listener *io_new_listener_(const tal_t *ctx, int fd,
161 struct io_plan *(*init)(struct io_conn *,
166 * io_close_listener - delete a listener.
167 * @listener: the listener returned from io_new_listener.
169 * This closes the fd and frees @listener.
173 * struct io_listener *l = do_listen("8111");
175 * io_loop(NULL, NULL);
176 * io_close_listener(l);
179 void io_close_listener(struct io_listener *listener);
182 * io_write - output plan to write data.
183 * @conn: the connection that plan is for.
184 * @data: the data buffer.
185 * @len: the length to write.
186 * @next: function to call output is done.
187 * @arg: @next argument
189 * This updates the output plan, to write out a data buffer. Once it's all
190 * written, the @next function will be called: on an error, the finish
191 * function is called instead.
193 * Note that the I/O may actually be done immediately.
196 * static struct io_plan *write_to_conn(struct io_conn *conn, const char *msg)
198 * // Write message, then close.
199 * return io_write(conn, msg, strlen(msg), io_close_cb, NULL);
202 #define io_write(conn, data, len, next, arg) \
203 io_write_((conn), (data), (len), \
204 typesafe_cb_preargs(struct io_plan *, void *, \
205 (next), (arg), struct io_conn *), \
207 struct io_plan *io_write_(struct io_conn *conn,
208 const void *data, size_t len,
209 struct io_plan *(*next)(struct io_conn *, void *),
213 * io_read - input plan to read data.
214 * @conn: the connection that plan is for.
215 * @data: the data buffer.
216 * @len: the length to read.
217 * @next: function to call once input is done.
218 * @arg: @next argument
220 * This creates a plan to read data into a buffer. Once it's all
221 * read, the @next function will be called: on an error, the finish
222 * function is called instead.
224 * Note that the I/O may actually be done immediately.
227 * static struct io_plan *read_from_conn(struct io_conn *conn, char *buf)
229 * // Read message, then close.
230 * return io_read(conn, buf, 12, io_close_cb, NULL);
233 #define io_read(conn, data, len, next, arg) \
234 io_read_((conn), (data), (len), \
235 typesafe_cb_preargs(struct io_plan *, void *, \
236 (next), (arg), struct io_conn *), \
238 struct io_plan *io_read_(struct io_conn *conn,
239 void *data, size_t len,
240 struct io_plan *(*next)(struct io_conn *, void *),
245 * io_read_partial - input plan to read some data.
246 * @conn: the connection that plan is for.
247 * @data: the data buffer.
248 * @maxlen: the maximum length to read
249 * @lenp: set to the length actually read.
250 * @next: function to call once input is done.
251 * @arg: @next argument
253 * This creates a plan to read data into a buffer. Once any data is
254 * read, @len is updated and the @next function will be called: on an
255 * error, the finish function is called instead.
257 * Note that the I/O may actually be done immediately.
265 * static struct io_plan *dump(struct io_conn *conn, struct buf *b)
267 * printf("Partial read: '%*s'\n", (int)b->len, b->buf);
269 * return io_close(conn);
272 * static struct io_plan *read_part(struct io_conn *conn, struct buf *b)
274 * // Read message, then dump and close.
275 * return io_read_partial(conn, b->buf, sizeof(b->buf), &b->len, dump, b);
278 #define io_read_partial(conn, data, maxlen, lenp, next, arg) \
279 io_read_partial_((conn), (data), (maxlen), (lenp), \
280 typesafe_cb_preargs(struct io_plan *, void *, \
284 struct io_plan *io_read_partial_(struct io_conn *conn,
285 void *data, size_t maxlen, size_t *lenp,
286 struct io_plan *(*next)(struct io_conn *,
291 * io_write_partial - output plan to write some data.
292 * @conn: the connection that plan is for.
293 * @data: the data buffer.
294 * @maxlen: the maximum length to write
295 * @lenp: set to the length actually written.
296 * @next: function to call once output is done.
297 * @arg: @next argument
299 * This creates a plan to write data from a buffer. Once any data is
300 * written, @len is updated and the @next function will be called: on an
301 * error, the finish function is called instead.
303 * Note that the I/O may actually be done immediately.
311 * static struct io_plan *show_partial(struct io_conn *conn, struct buf *b)
313 * printf("Only wrote: '%*s'\n", (int)b->len, b->buf);
315 * return io_close(conn);
318 * static struct io_plan *write_part(struct io_conn *conn, struct buf *b)
320 * // Write message, then dump and close.
321 * strcpy(b->buf, "Hello world");
322 * return io_write_partial(conn, b->buf, strlen(b->buf),
323 * &b->len, show_partial, b);
326 #define io_write_partial(conn, data, maxlen, lenp, next, arg) \
327 io_write_partial_((conn), (data), (maxlen), (lenp), \
328 typesafe_cb_preargs(struct io_plan *, void *, \
332 struct io_plan *io_write_partial_(struct io_conn *conn,
333 const void *data, size_t maxlen, size_t *lenp,
334 struct io_plan *(*next)(struct io_conn *,
339 * io_always - plan to immediately call next callback
340 * @conn: the connection that plan is for.
341 * @next: function to call.
342 * @arg: @next argument
344 * Sometimes it's neater to plan a callback rather than call it directly;
345 * for example, if you only need to read data for one path and not another.
348 * static struct io_plan *init_conn_with_nothing(struct io_conn *conn,
351 * // Silly example: close on next time around loop.
352 * return io_always(conn, io_close_cb, NULL);
355 #define io_always(conn, next, arg) \
356 io_always_((conn), typesafe_cb_preargs(struct io_plan *, void *, \
361 struct io_plan *io_always_(struct io_conn *conn,
362 struct io_plan *(*next)(struct io_conn *, void *),
366 * io_out_always - output plan to immediately call next callback
367 * @conn: the connection that plan is for.
368 * @next: function to call.
369 * @arg: @next argument
371 * This is a variant of io_always() which uses the output plan; it only
372 * matters if you are using io_duplex, and thus have two plans running at
375 #define io_out_always(conn, next, arg) \
376 io_out_always_((conn), typesafe_cb_preargs(struct io_plan *, void *, \
381 struct io_plan *io_out_always_(struct io_conn *conn,
382 struct io_plan *(*next)(struct io_conn *,
387 * io_connect - create an asynchronous connection to a listening socket.
388 * @conn: the connection that plan is for.
389 * @addr: where to connect.
390 * @init: function to call once it's connected
391 * @arg: @init argument
393 * This initiates a connection, and creates a plan for
394 * (asynchronously) completing it. Once complete, the @init function
398 * #include <sys/types.h>
399 * #include <sys/socket.h>
402 * // Write, then close socket.
403 * static struct io_plan *init_connect(struct io_conn *conn,
404 * struct addrinfo *addrinfo)
406 * return io_connect(conn, addrinfo, io_close_cb, NULL);
412 * struct addrinfo *addrinfo;
414 * fd = socket(AF_INET, SOCK_STREAM, 0);
415 * getaddrinfo("localhost", "8111", NULL, &addrinfo);
416 * io_new_conn(NULL, fd, init_connect, addrinfo);
419 #define io_connect(conn, addr, next, arg) \
420 io_connect_((conn), (addr), \
421 typesafe_cb_preargs(struct io_plan *, void *, \
426 struct io_plan *io_connect_(struct io_conn *conn, const struct addrinfo *addr,
427 struct io_plan *(*next)(struct io_conn *, void *),
431 * io_duplex - set plans for both input and output.
432 * @conn: the connection that plan is for.
433 * @in: the input plan
434 * @out: the output plan
436 * Most plans are either for input or output; io_duplex creates a plan
437 * which does both. This is often used in the init function to create
438 * two independent streams, though it can be used once on any connection.
440 * Note that if either plan closes the connection, it will be closed.
448 * static struct io_plan *read_and_write(struct io_conn *conn, struct buf *b)
450 * return io_duplex(conn,
451 * io_read(conn, b->in, sizeof(b->in), io_close_cb, b),
452 * io_write(conn, b->out, sizeof(b->out), io_close_cb,b));
455 #define io_duplex(conn, in_plan, out_plan) \
456 (io_duplex_prepare(conn), io_duplex_(in_plan, out_plan))
458 struct io_plan *io_duplex_(struct io_plan *in_plan, struct io_plan *out_plan);
459 void io_duplex_prepare(struct io_conn *conn);
462 * io_halfclose - close half of an io_duplex connection.
463 * @conn: the connection that plan is for.
465 * It's common to want to close a duplex connection after both input and
466 * output plans have completed. If either calls io_close() the connection
467 * closes immediately. Instead, io_halfclose() needs to be called twice.
475 * static struct io_plan *finish(struct io_conn *conn, struct buf *b)
477 * return io_halfclose(conn);
480 * static struct io_plan *read_and_write(struct io_conn *conn, struct buf *b)
482 * return io_duplex(conn,
483 * io_read(conn, b->in, sizeof(b->in), finish, b),
484 * io_write(conn, b->out, sizeof(b->out), finish, b));
487 struct io_plan *io_halfclose(struct io_conn *conn);
490 * io_wait - leave a plan idle until something wakes us.
491 * @conn: the connection that plan is for.
492 * @waitaddr: the address to wait on.
493 * @next: function to call after waiting.
494 * @arg: @next argument
496 * This leaves the input or output idle: io_wake(@waitaddr) will be
497 * called later to restart the connection.
500 * // Silly example to wait then close.
501 * static struct io_plan *wait(struct io_conn *conn, void *b)
503 * return io_wait(conn, b, io_close_cb, NULL);
506 #define io_wait(conn, waitaddr, next, arg) \
507 io_wait_((conn), (waitaddr), \
508 typesafe_cb_preargs(struct io_plan *, void *, \
513 struct io_plan *io_wait_(struct io_conn *conn,
515 struct io_plan *(*next)(struct io_conn *, void *),
520 * io_out_wait - leave the output plan idle until something wakes us.
521 * @conn: the connection that plan is for.
522 * @waitaddr: the address to wait on.
523 * @next: function to call after waiting.
524 * @arg: @next argument
526 * io_wait() makes the input plan idle: if you're not using io_duplex it
527 * doesn't matter which plan is waiting. Otherwise, you may need to use
528 * io_out_wait() instead, to specify explicitly that the output plan is
531 #define io_out_wait(conn, waitaddr, next, arg) \
532 io_out_wait_((conn), (waitaddr), \
533 typesafe_cb_preargs(struct io_plan *, void *, \
538 struct io_plan *io_out_wait_(struct io_conn *conn,
540 struct io_plan *(*next)(struct io_conn *, void *),
544 * io_wake - wake up any connections waiting on @wait
545 * @waitaddr: the address to trigger.
547 * All io_conns who have returned io_wait() on @waitaddr will move on
548 * to their next callback.
551 * static struct io_plan *wake_it(struct io_conn *conn, void *b)
554 * return io_close(conn);
557 void io_wake(const void *wait);
560 * io_break - return from io_loop()
561 * @ret: non-NULL value to return from io_loop().
563 * This breaks out of the io_loop. As soon as the current function
564 * returns, any io_close()'d connections will have their finish
565 * callbacks called, then io_loop() with return with @ret.
567 * If io_loop() is called again, then @plan will be carried out.
570 * static struct io_plan *fail_on_timeout(struct io_conn *conn, char *msg)
573 * return io_close(conn);
576 void io_break(const void *ret);
579 * io_never - assert if callback is called.
580 * @conn: the connection that plan is for.
581 * @unused: an unused parameter to make this suitable for use as a callback.
583 * Sometimes you want to make it clear that a callback should never happen
584 * (eg. for io_break). This will assert() if called.
587 * static struct io_plan *break_out(struct io_conn *conn, void *unused)
590 * // We won't ever return from io_break
591 * return io_never(conn, NULL);
594 struct io_plan *io_never(struct io_conn *conn, void *unused);
596 /* FIXME: io_recvfrom/io_sendto */
599 * io_close - plan to close a connection.
600 * @conn: the connection to close.
602 * On return to io_loop, the connection will be closed. It doesn't have
603 * to be the current connection and it doesn't need to be idle. No more
604 * IO or callbacks will occur.
606 * You can close a connection twice without harmful effects.
609 * static struct io_plan *close_on_timeout(struct io_conn *conn, const char *msg)
611 * printf("closing: %s\n", msg);
612 * return io_close(conn);
615 struct io_plan *io_close(struct io_conn *conn);
618 * io_close_cb - helper callback to close a connection.
619 * @conn: the connection.
621 * This schedules a connection to be closed; designed to be used as
622 * a callback function.
625 * #define close_on_timeout io_close_cb
627 struct io_plan *io_close_cb(struct io_conn *, void *unused);
630 * io_loop - process fds until all closed on io_break.
631 * @timers - timers which are waiting to go off (or NULL for none)
632 * @expired - a list filled with expired timers (can be NULL if @timers is)
634 * This is the core loop; it exits with the io_break() arg, or NULL if
635 * all connections and listeners are closed, or with @expired set to a
636 * list of expired timers (if @timers isn't NULL).
639 * io_loop(NULL, NULL);
641 void *io_loop(struct timers *timers, struct list_head *expired);
644 * io_conn_fd - get the fd from a connection.
645 * @conn: the connection.
647 * Sometimes useful, eg for getsockname().
649 int io_conn_fd(const struct io_conn *conn);
652 * io_set_debug - set synchronous mode on a connection.
653 * @conn: the connection.
654 * @debug: whether to enable or disable debug.
656 * Once @debug is true on a connection, all I/O is done synchronously
657 * as soon as it is set, until it is unset or @conn is closed. This
658 * makes it easy to debug what's happening with a connection, but note
659 * that other connections are starved while this is being done.
661 * See also: io_debug_complete()
664 * // Dumb init function to set debug and tell conn to close.
665 * static struct io_plan *conn_init(struct io_conn *conn, const char *msg)
667 * io_set_debug(conn, true);
668 * return io_close(conn);
671 void io_set_debug(struct io_conn *conn, bool debug);
674 * io_debug_complete - empty function called when conn is closing/waiting.
675 * @conn: the connection.
677 * This is for putting a breakpoint onto, when debugging. It is called
678 * when a conn with io_set_debug() true can no longer be synchronous:
679 * 1) It is io_close()'d
680 * 2) It enters io_wait() (sychronous debug will resume after io_wake())
681 * 3) io_break() is called (sychronous debug will resume after io_loop())
683 void io_debug_complete(struct io_conn *conn);
684 #endif /* CCAN_IO_H */