00b9b33db5e7884bfc969acee67247818d0cfa75
[ccan] / ccan / io / io.h
1 /* Licensed under LGPLv2.1+ - see LICENSE file for details */
2 #ifndef CCAN_IO_H
3 #define CCAN_IO_H
4 #include <ccan/tal/tal.h>
5 #include <ccan/typesafe_cb/typesafe_cb.h>
6 #include <stdbool.h>
7 #include <unistd.h>
8
9 /**
10  * struct io_plan - a plan for input or output.
11  *
12  * Each io_conn has zero to two of these active at any time.
13  */
14 struct io_plan;
15
16 /**
17  * struct io_conn - a connection associated with an fd.
18  */
19 struct io_conn;
20
21 /**
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.
27  *
28  * This creates a connection which owns @fd, it then calls
29  * @init to initialize the connection, which sets up an io_plan.
30  *
31  * Returns NULL on error (and sets errno).
32  *
33  * Example:
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)
36  * {
37  *      printf("Created conn %p: %s", conn, msg);
38  *      return io_close(conn);
39  * }
40  *
41  * static void create_self_closing_pipe(void)
42  * {
43  *      int fd[2];
44  *      struct io_conn *conn;
45  *
46  *      pipe(fd);
47  *      conn = io_new_conn(NULL, fd[0], conn_init, (const char *)"hi!");
48  *      if (!conn)
49  *              exit(1);
50  * }
51  */
52 #define io_new_conn(ctx, fd, init, arg)                                 \
53         io_new_conn_((ctx), (fd),                                       \
54                      typesafe_cb_preargs(struct io_plan *, void *,      \
55                                          (init), (arg),                 \
56                                          struct io_conn *conn),         \
57                      (void *)(arg))
58
59 struct io_conn *io_new_conn_(const tal_t *ctx, int fd,
60                              struct io_plan *(*init)(struct io_conn *, void *),
61                              void *arg);
62
63 /**
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.
68  *
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.
73  *
74  * Example:
75  * static void finish(struct io_conn *conn, const char *msg)
76  * {
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);
79  * }
80  *
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)
83  * {
84  *      io_set_finish(conn, finish, msg);
85  *      return io_close(conn);
86  * }
87  */
88 #define io_set_finish(conn, finish, arg)                                \
89         io_set_finish_((conn),                                          \
90                        typesafe_cb_preargs(void, void *,                \
91                                            (finish), (arg),             \
92                                            struct io_conn *),           \
93                        (void *)(arg))
94 void io_set_finish_(struct io_conn *conn,
95                     void (*finish)(struct io_conn *, void *),
96                     void *arg);
97
98
99 /**
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.
105  *
106  * When @fd becomes readable, we accept(), create a new connection,
107  * (tal'ocated off @ctx) and pass that to init().
108  *
109  * Returns NULL on error (and sets errno).
110  *
111  * Example:
112  * #include <sys/types.h>
113  * #include <sys/socket.h>
114  * #include <netdb.h>
115  *
116  * ...
117  *
118  * // Set up a listening socket, return it.
119  * static struct io_listener *do_listen(const char *port)
120  * {
121  *      struct addrinfo *addrinfo, hints;
122  *      int fd, on = 1;
123  *
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;
129  *
130  *      if (getaddrinfo(NULL, port, &hints, &addrinfo) != 0)
131  *              return NULL;
132  *
133  *      fd = socket(addrinfo->ai_family, addrinfo->ai_socktype,
134  *                  addrinfo->ai_protocol);
135  *      if (fd < 0)
136  *              return NULL;
137  *
138  *      freeaddrinfo(addrinfo);
139  *      setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &on, sizeof(on));
140  *      if (bind(fd, addrinfo->ai_addr, addrinfo->ai_addrlen) != 0) {
141  *              close(fd);
142  *              return NULL;
143  *      }
144  *      if (listen(fd, 1) != 0) {
145  *              close(fd);
146  *              return NULL;
147  *      }
148  *      return io_new_listener(NULL, fd, conn_init, (const char *)"listened!");
149  * }
150  */
151 #define io_new_listener(ctx, fd, init, arg)                             \
152         io_new_listener_((ctx), (fd),                                   \
153                          typesafe_cb_preargs(struct io_plan *, void *,  \
154                                              (init), (arg),             \
155                                              struct io_conn *conn),     \
156                          (void *)(arg))
157 struct io_listener *io_new_listener_(const tal_t *ctx, int fd,
158                                      struct io_plan *(*init)(struct io_conn *,
159                                                              void *),
160                                      void *arg);
161
162 /**
163  * io_close_listener - delete a listener.
164  * @listener: the listener returned from io_new_listener.
165  *
166  * This closes the fd and frees @listener.
167  *
168  * Example:
169  * ...
170  *      struct io_listener *l = do_listen("8111");
171  *      if (l) {
172  *              io_loop();
173  *              io_close_listener(l);
174  *      }
175  */
176 void io_close_listener(struct io_listener *listener);
177
178 /**
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
185  *
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.
189  *
190  * Note that the I/O may actually be done immediately.
191  *
192  * Example:
193  * static struct io_plan *write_to_conn(struct io_conn *conn, const char *msg)
194  * {
195  *      // Write message, then close.
196  *      return io_write(conn, msg, strlen(msg), io_close_cb, NULL);
197  * }
198  */
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 *), \
203                   (arg))
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 *),
207                           void *arg);
208
209 /**
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
216  *
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.
220  *
221  * Note that the I/O may actually be done immediately.
222  *
223  * Example:
224  * static struct io_plan *read_from_conn(struct io_conn *conn, char *buf)
225  * {
226  *      // Read message, then close.
227  *      return io_read(conn, buf, 12, io_close_cb, NULL);
228  * }
229  */
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 *),  \
234                  (arg))
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 *),
238                          void *arg);
239
240
241 /**
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
249  *
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.
253  *
254  * Note that the I/O may actually be done immediately.
255  *
256  * Example:
257  * struct buf {
258  *      size_t len;
259  *      char buf[12];
260  * };
261  *
262  * static struct io_plan *dump(struct io_conn *conn, struct buf *b)
263  * {
264  *      printf("Partial read: '%*s'\n", (int)b->len, b->buf);
265  *      free(b);
266  *      return io_close(conn);
267  * }
268  *
269  * static struct io_plan *read_part(struct io_conn *conn, struct buf *b)
270  * {
271  *      // Read message, then dump and close.
272  *      return io_read_partial(conn, b->buf, sizeof(b->buf), &b->len, dump, b);
273  * }
274  */
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 *,  \
278                                              (next), (arg),             \
279                                              struct io_conn *),         \
280                          (arg))
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 *,
284                                                          void *),
285                                  void *arg);
286
287 /**
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
295  *
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.
299  *
300  * Note that the I/O may actually be done immediately.
301  *
302  * Example:
303  * struct buf {
304  *      size_t len;
305  *      char buf[12];
306  * };
307  *
308  * static struct io_plan *show_partial(struct io_conn *conn, struct buf *b)
309  * {
310  *      printf("Only wrote: '%*s'\n", (int)b->len, b->buf);
311  *      free(b);
312  *      return io_close(conn);
313  * }
314  *
315  * static struct io_plan *write_part(struct io_conn *conn, struct buf *b)
316  * {
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);
321  * }
322  */
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 *, \
326                                               (next), (arg),            \
327                                               struct io_conn *),        \
328                           (arg))
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 *,
332                                                           void*),
333                                   void *arg);
334
335 /**
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
340  *
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.
343  *
344  * Example:
345  * static struct io_plan *init_conn_with_nothing(struct io_conn *conn,
346  *                                               void *unused)
347  * {
348  *      // Silly example: close on next time around loop.
349  *      return io_always(conn, io_close_cb, NULL);
350  * }
351  */
352 #define io_always(conn, next, arg)                                      \
353         io_always_((conn), typesafe_cb_preargs(struct io_plan *, void *, \
354                                                (next), (arg),           \
355                                                struct io_conn *),       \
356                    (arg))
357
358 struct io_plan *io_always_(struct io_conn *conn,
359                            struct io_plan *(*next)(struct io_conn *, void *),
360                            void *arg);
361
362 /**
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
368  *
369  * This initiates a connection, and creates a plan for
370  * (asynchronously) completing it.  Once complete, the @init function
371  * will be called.
372  *
373  * Example:
374  * #include <sys/types.h>
375  * #include <sys/socket.h>
376  * #include <netdb.h>
377  *
378  * // Write, then close socket.
379  * static struct io_plan *init_connect(struct io_conn *conn,
380  *                                     struct addrinfo *addrinfo)
381  * {
382  *      return io_connect(conn, addrinfo, io_close_cb, NULL);
383  * }
384  *
385  * ...
386  *
387  *      int fd;
388  *      struct addrinfo *addrinfo;
389  *
390  *      fd = socket(AF_INET, SOCK_STREAM, 0);
391  *      getaddrinfo("localhost", "8111", NULL, &addrinfo);
392  *      io_new_conn(NULL, fd, init_connect, addrinfo);
393  */
394 struct addrinfo;
395 #define io_connect(conn, addr, next, arg)                               \
396         io_connect_((conn), (addr),                                     \
397                     typesafe_cb_preargs(struct io_plan *, void *,       \
398                                         (next), (arg),                  \
399                                         struct io_conn *),              \
400                     (arg))
401
402 struct io_plan *io_connect_(struct io_conn *conn, const struct addrinfo *addr,
403                             struct io_plan *(*next)(struct io_conn *, void *),
404                             void *arg);
405
406 /**
407  * io_wait - leave a plan idle until something wakes us.
408  * @conn: the connection that plan is for.
409  * @waitaddr: the address to wait on.
410  * @next: function to call after waiting.
411  * @arg: @next argument
412  *
413  * This leaves the input or output idle: io_wake(@waitaddr) will be
414  * called later to restart the connection.
415  *
416  * Example:
417  * // Silly example to wait then close.
418  * static struct io_plan *wait(struct io_conn *conn, void *b)
419  * {
420  *      return io_wait(conn, b, io_close_cb, NULL);
421  * }
422  */
423 #define io_wait(conn, waitaddr, next, arg)                              \
424         io_wait_((conn), (waitaddr),                                    \
425                  typesafe_cb_preargs(struct io_plan *, void *,          \
426                                      (next), (arg),                     \
427                                      struct io_conn *),                 \
428                  (arg))
429
430 struct io_plan *io_wait_(struct io_conn *conn,
431                          const void *wait,
432                          struct io_plan *(*next)(struct io_conn *, void *),
433                          void *arg);
434
435
436 /**
437  * io_wake - wake up any connections waiting on @wait
438  * @waitaddr: the address to trigger.
439  *
440  * All io_conns who have returned io_wait() on @waitaddr will move on
441  * to their next callback.
442  *
443  * Example:
444  * static struct io_plan *wake_it(struct io_conn *conn, void *b)
445  * {
446  *      io_wake(b);
447  *      return io_close(conn);
448  * }
449  */
450 void io_wake(const void *wait);
451
452 /**
453  * io_break - return from io_loop()
454  * @ret: non-NULL value to return from io_loop().
455  *
456  * This breaks out of the io_loop.  As soon as the current function
457  * returns, any io_close()'d connections will have their finish
458  * callbacks called, then io_loop() with return with @ret.
459  *
460  * If io_loop() is called again, then @plan will be carried out.
461  *
462  * Example:
463  *      static struct io_plan *fail_on_timeout(struct io_conn *conn, char *msg)
464  *      {
465  *              io_break(msg);
466  *              return io_close(conn);
467  *      }
468  */
469 void io_break(const void *ret);
470
471 /**
472  * io_never - assert if callback is called.
473  * @conn: the connection that plan is for.
474  *
475  * Sometimes you want to make it clear that a callback should never happen
476  * (eg. for io_break).  This will assert() if called.
477  *
478  * Example:
479  * static struct io_plan *break_out(struct io_conn *conn, void *unused)
480  * {
481  *      io_break(conn);
482  *      // We won't ever return from io_break
483  *      return io_never(conn);
484  * }
485  */
486 struct io_plan *io_never(struct io_conn *conn);
487
488 /* FIXME: io_recvfrom/io_sendto */
489
490 /**
491  * io_close - plan to close a connection.
492  * @conn: the connection to close.
493  *
494  * On return to io_loop, the connection will be closed.  It doesn't have
495  * to be the current connection and it doesn't need to be idle.  No more
496  * IO or callbacks will occur.
497  *
498  * You can close a connection twice without harmful effects.
499  *
500  * Example:
501  * static struct io_plan *close_on_timeout(struct io_conn *conn, const char *msg)
502  * {
503  *      printf("closing: %s\n", msg);
504  *      return io_close(conn);
505  * }
506  */
507 struct io_plan *io_close(struct io_conn *conn);
508
509 /**
510  * io_close_cb - helper callback to close a connection.
511  * @conn: the connection.
512  *
513  * This schedules a connection to be closed; designed to be used as
514  * a callback function.
515  *
516  * Example:
517  *      #define close_on_timeout io_close_cb
518  */
519 struct io_plan *io_close_cb(struct io_conn *, void *unused);
520
521 /**
522  * io_loop - process fds until all closed on io_break.
523  *
524  * This is the core loop; it exits with the io_break() arg, or NULL if
525  * all connections and listeners are closed.
526  *
527  * Example:
528  *      io_loop();
529  */
530 void *io_loop(void);
531
532 /**
533  * io_conn_fd - get the fd from a connection.
534  * @conn: the connection.
535  *
536  * Sometimes useful, eg for getsockname().
537  */
538 int io_conn_fd(const struct io_conn *conn);
539 #endif /* CCAN_IO_H */