1 /* Licensed under LGPLv2.1+ - see LICENSE file for details */
4 #include <ccan/tal/tal.h>
5 #include <ccan/typesafe_cb/typesafe_cb.h>
10 * struct io_plan - a plan for input or output.
12 * Each io_conn has zero to two of these active at any time.
17 * struct io_conn - a connection associated with an fd.
22 * io_new_conn - create a new connection.
23 * @ctx: the context to tal from (or NULL)
24 * @fd: the file descriptor.
25 * @init: the function to call for a new connection
26 * @arg: the argument to @init.
28 * This creates a connection which owns @fd, it then calls
29 * @init to initialize the connection, which sets up an io_plan.
31 * Returns NULL on error (and sets errno).
34 * // Dumb init function to print string and tell conn to close.
35 * static struct io_plan *conn_init(struct io_conn *conn, const char *msg)
37 * printf("Created conn %p: %s", conn, msg);
38 * return io_close(conn);
41 * static void create_self_closing_pipe(void)
44 * struct io_conn *conn;
47 * conn = io_new_conn(NULL, fd[0], conn_init, (const char *)"hi!");
52 #define io_new_conn(ctx, fd, init, arg) \
53 io_new_conn_((ctx), (fd), \
54 typesafe_cb_preargs(struct io_plan *, void *, \
56 struct io_conn *conn), \
59 struct io_conn *io_new_conn_(const tal_t *ctx, int fd,
60 struct io_plan *(*init)(struct io_conn *, void *),
64 * io_set_finish - set finish function on a connection.
65 * @conn: the connection.
66 * @finish: the function to call when it's closed or fails.
67 * @arg: the argument to @finish.
69 * @finish will be called when an I/O operation fails, or you call
70 * io_close() on the connection. errno will be set to the value
71 * after the failed I/O, or at the call to io_close(). The fd
72 * will be closed before @finish is called.
75 * static void finish(struct io_conn *conn, const char *msg)
77 * // errno is not 0 after success, so this is a bit useless.
78 * printf("Conn %p closed with errno %i (%s)\n", conn, errno, msg);
81 * // Dumb init function to print string and tell conn to close.
82 * static struct io_plan *conn_init(struct io_conn *conn, const char *msg)
84 * io_set_finish(conn, finish, msg);
85 * return io_close(conn);
88 #define io_set_finish(conn, finish, arg) \
89 io_set_finish_((conn), \
90 typesafe_cb_preargs(void, void *, \
94 void io_set_finish_(struct io_conn *conn,
95 void (*finish)(struct io_conn *, void *),
100 * io_new_listener - create a new accepting listener.
101 * @ctx: the context to tal from (or NULL)
102 * @fd: the file descriptor.
103 * @init: the function to call for a new connection
104 * @arg: the argument to @init.
106 * When @fd becomes readable, we accept(), create a new connection,
107 * (tal'ocated off @ctx) and pass that to init().
109 * Returns NULL on error (and sets errno).
112 * #include <sys/types.h>
113 * #include <sys/socket.h>
118 * // Set up a listening socket, return it.
119 * static struct io_listener *do_listen(const char *port)
121 * struct addrinfo *addrinfo, hints;
124 * memset(&hints, 0, sizeof(hints));
125 * hints.ai_family = AF_UNSPEC;
126 * hints.ai_socktype = SOCK_STREAM;
127 * hints.ai_flags = AI_PASSIVE;
128 * hints.ai_protocol = 0;
130 * if (getaddrinfo(NULL, port, &hints, &addrinfo) != 0)
133 * fd = socket(addrinfo->ai_family, addrinfo->ai_socktype,
134 * addrinfo->ai_protocol);
138 * freeaddrinfo(addrinfo);
139 * setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &on, sizeof(on));
140 * if (bind(fd, addrinfo->ai_addr, addrinfo->ai_addrlen) != 0) {
144 * if (listen(fd, 1) != 0) {
148 * return io_new_listener(NULL, fd, conn_init, (const char *)"listened!");
151 #define io_new_listener(ctx, fd, init, arg) \
152 io_new_listener_((ctx), (fd), \
153 typesafe_cb_preargs(struct io_plan *, void *, \
155 struct io_conn *conn), \
157 struct io_listener *io_new_listener_(const tal_t *ctx, int fd,
158 struct io_plan *(*init)(struct io_conn *,
163 * io_close_listener - delete a listener.
164 * @listener: the listener returned from io_new_listener.
166 * This closes the fd and frees @listener.
170 * struct io_listener *l = do_listen("8111");
173 * io_close_listener(l);
176 void io_close_listener(struct io_listener *listener);
179 * io_write - output plan to write data.
180 * @conn: the connection that plan is for.
181 * @data: the data buffer.
182 * @len: the length to write.
183 * @next: function to call output is done.
184 * @arg: @next argument
186 * This updates the output plan, to write out a data buffer. Once it's all
187 * written, the @next function will be called: on an error, the finish
188 * function is called instead.
190 * Note that the I/O may actually be done immediately.
193 * static struct io_plan *write_to_conn(struct io_conn *conn, const char *msg)
195 * // Write message, then close.
196 * return io_write(conn, msg, strlen(msg), io_close_cb, NULL);
199 #define io_write(conn, data, len, next, arg) \
200 io_write_((conn), (data), (len), \
201 typesafe_cb_preargs(struct io_plan *, void *, \
202 (next), (arg), struct io_conn *), \
204 struct io_plan *io_write_(struct io_conn *conn,
205 const void *data, size_t len,
206 struct io_plan *(*next)(struct io_conn *, void *),
210 * io_read - input plan to read data.
211 * @conn: the connection that plan is for.
212 * @data: the data buffer.
213 * @len: the length to read.
214 * @next: function to call once input is done.
215 * @arg: @next argument
217 * This creates a plan to read data into a buffer. Once it's all
218 * read, the @next function will be called: on an error, the finish
219 * function is called instead.
221 * Note that the I/O may actually be done immediately.
224 * static struct io_plan *read_from_conn(struct io_conn *conn, char *buf)
226 * // Read message, then close.
227 * return io_read(conn, buf, 12, io_close_cb, NULL);
230 #define io_read(conn, data, len, next, arg) \
231 io_read_((conn), (data), (len), \
232 typesafe_cb_preargs(struct io_plan *, void *, \
233 (next), (arg), struct io_conn *), \
235 struct io_plan *io_read_(struct io_conn *conn,
236 void *data, size_t len,
237 struct io_plan *(*next)(struct io_conn *, void *),
242 * io_read_partial - input plan to read some data.
243 * @conn: the connection that plan is for.
244 * @data: the data buffer.
245 * @maxlen: the maximum length to read
246 * @lenp: set to the length actually read.
247 * @next: function to call once input is done.
248 * @arg: @next argument
250 * This creates a plan to read data into a buffer. Once any data is
251 * read, @len is updated and the @next function will be called: on an
252 * error, the finish function is called instead.
254 * Note that the I/O may actually be done immediately.
262 * static struct io_plan *dump(struct io_conn *conn, struct buf *b)
264 * printf("Partial read: '%*s'\n", (int)b->len, b->buf);
266 * return io_close(conn);
269 * static struct io_plan *read_part(struct io_conn *conn, struct buf *b)
271 * // Read message, then dump and close.
272 * return io_read_partial(conn, b->buf, sizeof(b->buf), &b->len, dump, b);
275 #define io_read_partial(conn, data, maxlen, lenp, next, arg) \
276 io_read_partial_((conn), (data), (maxlen), (lenp), \
277 typesafe_cb_preargs(struct io_plan *, void *, \
281 struct io_plan *io_read_partial_(struct io_conn *conn,
282 void *data, size_t maxlen, size_t *lenp,
283 struct io_plan *(*next)(struct io_conn *,
288 * io_write_partial - output plan to write some data.
289 * @conn: the connection that plan is for.
290 * @data: the data buffer.
291 * @maxlen: the maximum length to write
292 * @lenp: set to the length actually written.
293 * @next: function to call once output is done.
294 * @arg: @next argument
296 * This creates a plan to write data from a buffer. Once any data is
297 * written, @len is updated and the @next function will be called: on an
298 * error, the finish function is called instead.
300 * Note that the I/O may actually be done immediately.
308 * static struct io_plan *show_partial(struct io_conn *conn, struct buf *b)
310 * printf("Only wrote: '%*s'\n", (int)b->len, b->buf);
312 * return io_close(conn);
315 * static struct io_plan *write_part(struct io_conn *conn, struct buf *b)
317 * // Write message, then dump and close.
318 * strcpy(b->buf, "Hello world");
319 * return io_write_partial(conn, b->buf, strlen(b->buf),
320 * &b->len, show_partial, b);
323 #define io_write_partial(conn, data, maxlen, lenp, next, arg) \
324 io_write_partial_((conn), (data), (maxlen), (lenp), \
325 typesafe_cb_preargs(struct io_plan *, void *, \
329 struct io_plan *io_write_partial_(struct io_conn *conn,
330 const void *data, size_t maxlen, size_t *lenp,
331 struct io_plan *(*next)(struct io_conn *,
336 * io_always - plan to immediately call next callback
337 * @conn: the connection that plan is for.
338 * @next: function to call.
339 * @arg: @next argument
341 * Sometimes it's neater to plan a callback rather than call it directly;
342 * for example, if you only need to read data for one path and not another.
345 * static struct io_plan *init_conn_with_nothing(struct io_conn *conn,
348 * // Silly example: close on next time around loop.
349 * return io_always(conn, io_close_cb, NULL);
352 #define io_always(conn, next, arg) \
353 io_always_((conn), typesafe_cb_preargs(struct io_plan *, void *, \
358 struct io_plan *io_always_(struct io_conn *conn,
359 struct io_plan *(*next)(struct io_conn *, void *),
363 * io_connect - create an asynchronous connection to a listening socket.
364 * @conn: the connection that plan is for.
365 * @addr: where to connect.
366 * @init: function to call once it's connected
367 * @arg: @init argument
369 * This initiates a connection, and creates a plan for
370 * (asynchronously) completing it. Once complete, the @init function
374 * #include <sys/types.h>
375 * #include <sys/socket.h>
378 * // Write, then close socket.
379 * static struct io_plan *init_connect(struct io_conn *conn,
380 * struct addrinfo *addrinfo)
382 * return io_connect(conn, addrinfo, io_close_cb, NULL);
388 * struct addrinfo *addrinfo;
390 * fd = socket(AF_INET, SOCK_STREAM, 0);
391 * getaddrinfo("localhost", "8111", NULL, &addrinfo);
392 * io_new_conn(NULL, fd, init_connect, addrinfo);
395 #define io_connect(conn, addr, next, arg) \
396 io_connect_((conn), (addr), \
397 typesafe_cb_preargs(struct io_plan *, void *, \
402 struct io_plan *io_connect_(struct io_conn *conn, const struct addrinfo *addr,
403 struct io_plan *(*next)(struct io_conn *, void *),
407 * io_duplex - set plans for both input and output.
408 * @conn: the connection that plan is for.
409 * @in: the input plan
410 * @out: the output plan
412 * Most plans are either for input or output; io_duplex creates a plan
413 * which does both. This is often used in the init function to create
414 * two independent streams, though it can be used once on any connection.
416 * Note that if either plan closes the connection, it will be closed.
418 * Note that if one plan is io_wait or io_always, that causes a problem:
419 * they look at the input and output plan slots to figure out which to
420 * use, but if the other plan hasn't been evaluated yet, that will fail.
421 * In this case, you'll need to ensure the other plan is evaluated first,
422 * eg. "struct io_plan *r = io_read(...); return io_duplex(r, io_always(...))"
430 * static struct io_plan *read_and_write(struct io_conn *conn, struct buf *b)
432 * return io_duplex(io_read(conn, b->in, sizeof(b->in), io_close_cb, b),
433 * io_write(conn, b->out, sizeof(b->out), io_close_cb, b));
436 struct io_plan *io_duplex(struct io_plan *in_plan, struct io_plan *out_plan);
439 * io_wait - leave a plan idle until something wakes us.
440 * @conn: the connection that plan is for.
441 * @waitaddr: the address to wait on.
442 * @next: function to call after waiting.
443 * @arg: @next argument
445 * This leaves the input or output idle: io_wake(@waitaddr) will be
446 * called later to restart the connection.
449 * // Silly example to wait then close.
450 * static struct io_plan *wait(struct io_conn *conn, void *b)
452 * return io_wait(conn, b, io_close_cb, NULL);
455 #define io_wait(conn, waitaddr, next, arg) \
456 io_wait_((conn), (waitaddr), \
457 typesafe_cb_preargs(struct io_plan *, void *, \
462 struct io_plan *io_wait_(struct io_conn *conn,
464 struct io_plan *(*next)(struct io_conn *, void *),
469 * io_wake - wake up any connections waiting on @wait
470 * @waitaddr: the address to trigger.
472 * All io_conns who have returned io_wait() on @waitaddr will move on
473 * to their next callback.
476 * static struct io_plan *wake_it(struct io_conn *conn, void *b)
479 * return io_close(conn);
482 void io_wake(const void *wait);
485 * io_break - return from io_loop()
486 * @ret: non-NULL value to return from io_loop().
488 * This breaks out of the io_loop. As soon as the current function
489 * returns, any io_close()'d connections will have their finish
490 * callbacks called, then io_loop() with return with @ret.
492 * If io_loop() is called again, then @plan will be carried out.
495 * static struct io_plan *fail_on_timeout(struct io_conn *conn, char *msg)
498 * return io_close(conn);
501 void io_break(const void *ret);
504 * io_never - assert if callback is called.
505 * @conn: the connection that plan is for.
506 * @unused: an unused parameter to make this suitable for use as a callback.
508 * Sometimes you want to make it clear that a callback should never happen
509 * (eg. for io_break). This will assert() if called.
512 * static struct io_plan *break_out(struct io_conn *conn, void *unused)
515 * // We won't ever return from io_break
516 * return io_never(conn, NULL);
519 struct io_plan *io_never(struct io_conn *conn, void *unused);
521 /* FIXME: io_recvfrom/io_sendto */
524 * io_close - plan to close a connection.
525 * @conn: the connection to close.
527 * On return to io_loop, the connection will be closed. It doesn't have
528 * to be the current connection and it doesn't need to be idle. No more
529 * IO or callbacks will occur.
531 * You can close a connection twice without harmful effects.
534 * static struct io_plan *close_on_timeout(struct io_conn *conn, const char *msg)
536 * printf("closing: %s\n", msg);
537 * return io_close(conn);
540 struct io_plan *io_close(struct io_conn *conn);
543 * io_close_cb - helper callback to close a connection.
544 * @conn: the connection.
546 * This schedules a connection to be closed; designed to be used as
547 * a callback function.
550 * #define close_on_timeout io_close_cb
552 struct io_plan *io_close_cb(struct io_conn *, void *unused);
555 * io_loop - process fds until all closed on io_break.
557 * This is the core loop; it exits with the io_break() arg, or NULL if
558 * all connections and listeners are closed.
566 * io_conn_fd - get the fd from a connection.
567 * @conn: the connection.
569 * Sometimes useful, eg for getsockname().
571 int io_conn_fd(const struct io_conn *conn);
572 #endif /* CCAN_IO_H */