io: io_time_override to insert fake times.
[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 struct timers;
10 struct timer;
11 struct list_head;
12
13 /**
14  * struct io_plan - a plan for input or output.
15  *
16  * Each io_conn has zero to two of these active at any time.
17  */
18 struct io_plan;
19
20 /**
21  * struct io_conn - a connection associated with an fd.
22  */
23 struct io_conn;
24
25 /**
26  * io_new_conn - create a new connection.
27  * @ctx: the context to tal from (or NULL)
28  * @fd: the file descriptor.
29  * @init: the function to call for a new connection
30  * @arg: the argument to @init.
31  *
32  * This creates a connection which owns @fd, it then calls
33  * @init to initialize the connection, which sets up an io_plan.
34  *
35  * Returns NULL on error (and sets errno).
36  *
37  * Example:
38  * // Dumb init function to print string and tell conn to close.
39  * static struct io_plan *conn_init(struct io_conn *conn, const char *msg)
40  * {
41  *      printf("Created conn %p: %s", conn, msg);
42  *      return io_close(conn);
43  * }
44  *
45  * static void create_self_closing_pipe(void)
46  * {
47  *      int fd[2];
48  *      struct io_conn *conn;
49  *
50  *      pipe(fd);
51  *      conn = io_new_conn(NULL, fd[0], conn_init, (const char *)"hi!");
52  *      if (!conn)
53  *              exit(1);
54  * }
55  */
56 #define io_new_conn(ctx, fd, init, arg)                                 \
57         io_new_conn_((ctx), (fd),                                       \
58                      typesafe_cb_preargs(struct io_plan *, void *,      \
59                                          (init), (arg),                 \
60                                          struct io_conn *conn),         \
61                      (void *)(arg))
62
63 struct io_conn *io_new_conn_(const tal_t *ctx, int fd,
64                              struct io_plan *(*init)(struct io_conn *, void *),
65                              void *arg);
66
67 /**
68  * io_set_finish - set finish function on a connection.
69  * @conn: the connection.
70  * @finish: the function to call when it's closed or fails.
71  * @arg: the argument to @finish.
72  *
73  * @finish will be called when an I/O operation fails, or you call
74  * io_close() on the connection.  errno will be set to the value
75  * after the failed I/O, or at the call to io_close().  The fd
76  * will be closed before @finish is called.
77  *
78  * Example:
79  * static void finish(struct io_conn *conn, const char *msg)
80  * {
81  *      // errno is not 0 after success, so this is a bit useless.
82  *      printf("Conn %p closed with errno %i (%s)\n", conn, errno, msg);
83  * }
84  *
85  * // Dumb init function to print string and tell conn to close.
86  * static struct io_plan *conn_init(struct io_conn *conn, const char *msg)
87  * {
88  *      io_set_finish(conn, finish, msg);
89  *      return io_close(conn);
90  * }
91  */
92 #define io_set_finish(conn, finish, arg)                                \
93         io_set_finish_((conn),                                          \
94                        typesafe_cb_preargs(void, void *,                \
95                                            (finish), (arg),             \
96                                            struct io_conn *),           \
97                        (void *)(arg))
98 void io_set_finish_(struct io_conn *conn,
99                     void (*finish)(struct io_conn *, void *),
100                     void *arg);
101
102
103 /**
104  * io_new_listener - create a new accepting listener.
105  * @ctx: the context to tal from (or NULL)
106  * @fd: the file descriptor.
107  * @init: the function to call for a new connection
108  * @arg: the argument to @init.
109  *
110  * When @fd becomes readable, we accept(), create a new connection,
111  * (tal'ocated off @ctx) and pass that to init().
112  *
113  * Returns NULL on error (and sets errno).
114  *
115  * Example:
116  * #include <sys/types.h>
117  * #include <sys/socket.h>
118  * #include <netdb.h>
119  *
120  * ...
121  *
122  * // Set up a listening socket, return it.
123  * static struct io_listener *do_listen(const char *port)
124  * {
125  *      struct addrinfo *addrinfo, hints;
126  *      int fd, on = 1;
127  *
128  *      memset(&hints, 0, sizeof(hints));
129  *      hints.ai_family = AF_UNSPEC;
130  *      hints.ai_socktype = SOCK_STREAM;
131  *      hints.ai_flags = AI_PASSIVE;
132  *      hints.ai_protocol = 0;
133  *
134  *      if (getaddrinfo(NULL, port, &hints, &addrinfo) != 0)
135  *              return NULL;
136  *
137  *      fd = socket(addrinfo->ai_family, addrinfo->ai_socktype,
138  *                  addrinfo->ai_protocol);
139  *      if (fd < 0)
140  *              return NULL;
141  *
142  *      freeaddrinfo(addrinfo);
143  *      setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &on, sizeof(on));
144  *      if (bind(fd, addrinfo->ai_addr, addrinfo->ai_addrlen) != 0) {
145  *              close(fd);
146  *              return NULL;
147  *      }
148  *      if (listen(fd, 1) != 0) {
149  *              close(fd);
150  *              return NULL;
151  *      }
152  *      return io_new_listener(NULL, fd, conn_init, (const char *)"listened!");
153  * }
154  */
155 #define io_new_listener(ctx, fd, init, arg)                             \
156         io_new_listener_((ctx), (fd),                                   \
157                          typesafe_cb_preargs(struct io_plan *, void *,  \
158                                              (init), (arg),             \
159                                              struct io_conn *conn),     \
160                          (void *)(arg))
161 struct io_listener *io_new_listener_(const tal_t *ctx, int fd,
162                                      struct io_plan *(*init)(struct io_conn *,
163                                                              void *),
164                                      void *arg);
165
166 /**
167  * io_close_listener - delete a listener.
168  * @listener: the listener returned from io_new_listener.
169  *
170  * This closes the fd and frees @listener.
171  *
172  * Example:
173  * ...
174  *      struct io_listener *l = do_listen("8111");
175  *      if (l) {
176  *              io_loop(NULL, NULL);
177  *              io_close_listener(l);
178  *      }
179  */
180 void io_close_listener(struct io_listener *listener);
181
182 /**
183  * io_write - output plan to write data.
184  * @conn: the connection that plan is for.
185  * @data: the data buffer.
186  * @len: the length to write.
187  * @next: function to call output is done.
188  * @arg: @next argument
189  *
190  * This updates the output plan, to write out a data buffer.  Once it's all
191  * written, the @next function will be called: on an error, the finish
192  * function is called instead.
193  *
194  * Note that the I/O may actually be done immediately.
195  *
196  * Example:
197  * static struct io_plan *write_to_conn(struct io_conn *conn, const char *msg)
198  * {
199  *      // Write message, then close.
200  *      return io_write(conn, msg, strlen(msg), io_close_cb, NULL);
201  * }
202  */
203 #define io_write(conn, data, len, next, arg)                            \
204         io_write_((conn), (data), (len),                                \
205                   typesafe_cb_preargs(struct io_plan *, void *,         \
206                                       (next), (arg), struct io_conn *), \
207                   (arg))
208 struct io_plan *io_write_(struct io_conn *conn,
209                           const void *data, size_t len,
210                           struct io_plan *(*next)(struct io_conn *, void *),
211                           void *arg);
212
213 /**
214  * io_read - input plan to read data.
215  * @conn: the connection that plan is for.
216  * @data: the data buffer.
217  * @len: the length to read.
218  * @next: function to call once input is done.
219  * @arg: @next argument
220  *
221  * This creates a plan to read data into a buffer.  Once it's all
222  * read, the @next function will be called: on an error, the finish
223  * function is called instead.
224  *
225  * Note that the I/O may actually be done immediately.
226  *
227  * Example:
228  * static struct io_plan *read_from_conn(struct io_conn *conn, char *buf)
229  * {
230  *      // Read message, then close.
231  *      return io_read(conn, buf, 12, io_close_cb, NULL);
232  * }
233  */
234 #define io_read(conn, data, len, next, arg)                             \
235         io_read_((conn), (data), (len),                                 \
236                  typesafe_cb_preargs(struct io_plan *, void *,          \
237                                      (next), (arg), struct io_conn *),  \
238                  (arg))
239 struct io_plan *io_read_(struct io_conn *conn,
240                          void *data, size_t len,
241                          struct io_plan *(*next)(struct io_conn *, void *),
242                          void *arg);
243
244
245 /**
246  * io_read_partial - input plan to read some data.
247  * @conn: the connection that plan is for.
248  * @data: the data buffer.
249  * @maxlen: the maximum length to read
250  * @lenp: set to the length actually read.
251  * @next: function to call once input is done.
252  * @arg: @next argument
253  *
254  * This creates a plan to read data into a buffer.  Once any data is
255  * read, @len is updated and the @next function will be called: on an
256  * error, the finish function is called instead.
257  *
258  * Note that the I/O may actually be done immediately.
259  *
260  * Example:
261  * struct buf {
262  *      size_t len;
263  *      char buf[12];
264  * };
265  *
266  * static struct io_plan *dump(struct io_conn *conn, struct buf *b)
267  * {
268  *      printf("Partial read: '%*s'\n", (int)b->len, b->buf);
269  *      free(b);
270  *      return io_close(conn);
271  * }
272  *
273  * static struct io_plan *read_part(struct io_conn *conn, struct buf *b)
274  * {
275  *      // Read message, then dump and close.
276  *      return io_read_partial(conn, b->buf, sizeof(b->buf), &b->len, dump, b);
277  * }
278  */
279 #define io_read_partial(conn, data, maxlen, lenp, next, arg)            \
280         io_read_partial_((conn), (data), (maxlen), (lenp),              \
281                          typesafe_cb_preargs(struct io_plan *, void *,  \
282                                              (next), (arg),             \
283                                              struct io_conn *),         \
284                          (arg))
285 struct io_plan *io_read_partial_(struct io_conn *conn,
286                                  void *data, size_t maxlen, size_t *lenp,
287                                  struct io_plan *(*next)(struct io_conn *,
288                                                          void *),
289                                  void *arg);
290
291 /**
292  * io_write_partial - output plan to write some data.
293  * @conn: the connection that plan is for.
294  * @data: the data buffer.
295  * @maxlen: the maximum length to write
296  * @lenp: set to the length actually written.
297  * @next: function to call once output is done.
298  * @arg: @next argument
299  *
300  * This creates a plan to write data from a buffer.   Once any data is
301  * written, @len is updated and the @next function will be called: on an
302  * error, the finish function is called instead.
303  *
304  * Note that the I/O may actually be done immediately.
305  *
306  * Example:
307  * struct buf {
308  *      size_t len;
309  *      char buf[12];
310  * };
311  *
312  * static struct io_plan *show_partial(struct io_conn *conn, struct buf *b)
313  * {
314  *      printf("Only wrote: '%*s'\n", (int)b->len, b->buf);
315  *      free(b);
316  *      return io_close(conn);
317  * }
318  *
319  * static struct io_plan *write_part(struct io_conn *conn, struct buf *b)
320  * {
321  *      // Write message, then dump and close.
322  *      strcpy(b->buf, "Hello world");
323  *      return io_write_partial(conn, b->buf, strlen(b->buf),
324  *                              &b->len, show_partial, b);
325  * }
326  */
327 #define io_write_partial(conn, data, maxlen, lenp, next, arg)           \
328         io_write_partial_((conn), (data), (maxlen), (lenp),             \
329                           typesafe_cb_preargs(struct io_plan *, void *, \
330                                               (next), (arg),            \
331                                               struct io_conn *),        \
332                           (arg))
333 struct io_plan *io_write_partial_(struct io_conn *conn,
334                                   const void *data, size_t maxlen, size_t *lenp,
335                                   struct io_plan *(*next)(struct io_conn *,
336                                                           void*),
337                                   void *arg);
338
339 /**
340  * io_always - plan to immediately call next callback
341  * @conn: the connection that plan is for.
342  * @next: function to call.
343  * @arg: @next argument
344  *
345  * Sometimes it's neater to plan a callback rather than call it directly;
346  * for example, if you only need to read data for one path and not another.
347  *
348  * Example:
349  * static struct io_plan *init_conn_with_nothing(struct io_conn *conn,
350  *                                               void *unused)
351  * {
352  *      // Silly example: close on next time around loop.
353  *      return io_always(conn, io_close_cb, NULL);
354  * }
355  */
356 #define io_always(conn, next, arg)                                      \
357         io_always_((conn), typesafe_cb_preargs(struct io_plan *, void *, \
358                                                (next), (arg),           \
359                                                struct io_conn *),       \
360                    (arg))
361
362 struct io_plan *io_always_(struct io_conn *conn,
363                            struct io_plan *(*next)(struct io_conn *, void *),
364                            void *arg);
365
366 /**
367  * io_out_always - output plan to immediately call next callback
368  * @conn: the connection that plan is for.
369  * @next: function to call.
370  * @arg: @next argument
371  *
372  * This is a variant of io_always() which uses the output plan; it only
373  * matters if you are using io_duplex, and thus have two plans running at
374  * once.
375  */
376 #define io_out_always(conn, next, arg)                                  \
377         io_out_always_((conn), typesafe_cb_preargs(struct io_plan *, void *, \
378                                                    (next), (arg),       \
379                                                    struct io_conn *),   \
380                        (arg))
381
382 struct io_plan *io_out_always_(struct io_conn *conn,
383                                struct io_plan *(*next)(struct io_conn *,
384                                                        void *),
385                                void *arg);
386
387 /**
388  * io_connect - create an asynchronous connection to a listening socket.
389  * @conn: the connection that plan is for.
390  * @addr: where to connect.
391  * @init: function to call once it's connected
392  * @arg: @init argument
393  *
394  * This initiates a connection, and creates a plan for
395  * (asynchronously) completing it.  Once complete, the @init function
396  * will be called.
397  *
398  * Example:
399  * #include <sys/types.h>
400  * #include <sys/socket.h>
401  * #include <netdb.h>
402  *
403  * // Write, then close socket.
404  * static struct io_plan *init_connect(struct io_conn *conn,
405  *                                     struct addrinfo *addrinfo)
406  * {
407  *      return io_connect(conn, addrinfo, io_close_cb, NULL);
408  * }
409  *
410  * ...
411  *
412  *      int fd;
413  *      struct addrinfo *addrinfo;
414  *
415  *      fd = socket(AF_INET, SOCK_STREAM, 0);
416  *      getaddrinfo("localhost", "8111", NULL, &addrinfo);
417  *      io_new_conn(NULL, fd, init_connect, addrinfo);
418  */
419 struct addrinfo;
420 #define io_connect(conn, addr, next, arg)                               \
421         io_connect_((conn), (addr),                                     \
422                     typesafe_cb_preargs(struct io_plan *, void *,       \
423                                         (next), (arg),                  \
424                                         struct io_conn *),              \
425                     (arg))
426
427 struct io_plan *io_connect_(struct io_conn *conn, const struct addrinfo *addr,
428                             struct io_plan *(*next)(struct io_conn *, void *),
429                             void *arg);
430
431 /**
432  * io_duplex - set plans for both input and output.
433  * @conn: the connection that plan is for.
434  * @in: the input plan
435  * @out: the output plan
436  *
437  * Most plans are either for input or output; io_duplex creates a plan
438  * which does both.  This is often used in the init function to create
439  * two independent streams, though it can be used once on any connection.
440  *
441  * Note that if either plan closes the connection, it will be closed.
442  *
443  * Example:
444  * struct buf {
445  *      char in[100];
446  *      char out[100];
447  * };
448  *
449  * static struct io_plan *read_and_write(struct io_conn *conn, struct buf *b)
450  * {
451  *      return io_duplex(conn,
452  *                       io_read(conn, b->in, sizeof(b->in), io_close_cb, b),
453  *                       io_write(conn, b->out, sizeof(b->out), io_close_cb,b));
454  * }
455  */
456 #define io_duplex(conn, in_plan, out_plan) \
457         (io_duplex_prepare(conn), io_duplex_(in_plan, out_plan))
458
459 struct io_plan *io_duplex_(struct io_plan *in_plan, struct io_plan *out_plan);
460 void io_duplex_prepare(struct io_conn *conn);
461
462 /**
463  * io_halfclose - close half of an io_duplex connection.
464  * @conn: the connection that plan is for.
465  *
466  * It's common to want to close a duplex connection after both input and
467  * output plans have completed.  If either calls io_close() the connection
468  * closes immediately.  Instead, io_halfclose() needs to be called twice.
469  *
470  * Example:
471  * struct buf {
472  *      char in[100];
473  *      char out[100];
474  * };
475  *
476  * static struct io_plan *finish(struct io_conn *conn, struct buf *b)
477  * {
478  *      return io_halfclose(conn);
479  * }
480  *
481  * static struct io_plan *read_and_write(struct io_conn *conn, struct buf *b)
482  * {
483  *      return io_duplex(conn,
484  *                       io_read(conn, b->in, sizeof(b->in), finish, b),
485  *                       io_write(conn, b->out, sizeof(b->out), finish, b));
486  * }
487  */
488 struct io_plan *io_halfclose(struct io_conn *conn);
489
490 /**
491  * io_wait - leave a plan idle until something wakes us.
492  * @conn: the connection that plan is for.
493  * @waitaddr: the address to wait on.
494  * @next: function to call after waiting.
495  * @arg: @next argument
496  *
497  * This leaves the input or output idle: io_wake(@waitaddr) will be
498  * called later to restart the connection.
499  *
500  * Example:
501  * // Silly example to wait then close.
502  * static struct io_plan *wait(struct io_conn *conn, void *b)
503  * {
504  *      return io_wait(conn, b, io_close_cb, NULL);
505  * }
506  */
507 #define io_wait(conn, waitaddr, next, arg)                              \
508         io_wait_((conn), (waitaddr),                                    \
509                  typesafe_cb_preargs(struct io_plan *, void *,          \
510                                      (next), (arg),                     \
511                                      struct io_conn *),                 \
512                  (arg))
513
514 struct io_plan *io_wait_(struct io_conn *conn,
515                          const void *wait,
516                          struct io_plan *(*next)(struct io_conn *, void *),
517                          void *arg);
518
519
520 /**
521  * io_out_wait - leave the output plan idle until something wakes us.
522  * @conn: the connection that plan is for.
523  * @waitaddr: the address to wait on.
524  * @next: function to call after waiting.
525  * @arg: @next argument
526  *
527  * io_wait() makes the input plan idle: if you're not using io_duplex it
528  * doesn't matter which plan is waiting.  Otherwise, you may need to use
529  * io_out_wait() instead, to specify explicitly that the output plan is
530  * waiting.
531  */
532 #define io_out_wait(conn, waitaddr, next, arg)                          \
533         io_out_wait_((conn), (waitaddr),                                \
534                      typesafe_cb_preargs(struct io_plan *, void *,      \
535                                          (next), (arg),                 \
536                                          struct io_conn *),             \
537                      (arg))
538
539 struct io_plan *io_out_wait_(struct io_conn *conn,
540                              const void *wait,
541                              struct io_plan *(*next)(struct io_conn *, void *),
542                              void *arg);
543
544 /**
545  * io_wake - wake up any connections waiting on @wait
546  * @waitaddr: the address to trigger.
547  *
548  * All io_conns who have returned io_wait() on @waitaddr will move on
549  * to their next callback.
550  *
551  * Example:
552  * static struct io_plan *wake_it(struct io_conn *conn, void *b)
553  * {
554  *      io_wake(b);
555  *      return io_close(conn);
556  * }
557  */
558 void io_wake(const void *wait);
559
560 /**
561  * io_break - return from io_loop()
562  * @ret: non-NULL value to return from io_loop().
563  *
564  * This breaks out of the io_loop.  As soon as the current function
565  * returns, any io_close()'d connections will have their finish
566  * callbacks called, then io_loop() with return with @ret.
567  *
568  * If io_loop() is called again, then @plan will be carried out.
569  *
570  * Example:
571  *      static struct io_plan *fail_on_timeout(struct io_conn *conn, char *msg)
572  *      {
573  *              io_break(msg);
574  *              return io_close(conn);
575  *      }
576  */
577 void io_break(const void *ret);
578
579 /**
580  * io_never - assert if callback is called.
581  * @conn: the connection that plan is for.
582  * @unused: an unused parameter to make this suitable for use as a callback.
583  *
584  * Sometimes you want to make it clear that a callback should never happen
585  * (eg. for io_break).  This will assert() if called.
586  *
587  * Example:
588  * static struct io_plan *break_out(struct io_conn *conn, void *unused)
589  * {
590  *      io_break(conn);
591  *      // We won't ever return from io_break
592  *      return io_never(conn, NULL);
593  * }
594  */
595 struct io_plan *io_never(struct io_conn *conn, void *unused);
596
597 /* FIXME: io_recvfrom/io_sendto */
598
599 /**
600  * io_close - plan to close a connection.
601  * @conn: the connection to close.
602  *
603  * On return to io_loop, the connection will be closed.  It doesn't have
604  * to be the current connection and it doesn't need to be idle.  No more
605  * IO or callbacks will occur.
606  *
607  * You can close a connection twice without harmful effects.
608  *
609  * Example:
610  * static struct io_plan *close_on_timeout(struct io_conn *conn, const char *msg)
611  * {
612  *      printf("closing: %s\n", msg);
613  *      return io_close(conn);
614  * }
615  */
616 struct io_plan *io_close(struct io_conn *conn);
617
618 /**
619  * io_close_cb - helper callback to close a connection.
620  * @conn: the connection.
621  *
622  * This schedules a connection to be closed; designed to be used as
623  * a callback function.
624  *
625  * Example:
626  *      #define close_on_timeout io_close_cb
627  */
628 struct io_plan *io_close_cb(struct io_conn *, void *unused);
629
630 /**
631  * io_loop - process fds until all closed on io_break.
632  * @timers - timers which are waiting to go off (or NULL for none)
633  * @expired - an expired timer (can be NULL if @timers is)
634  *
635  * This is the core loop; it exits with the io_break() arg, or NULL if
636  * all connections and listeners are closed, or with @expired set to an
637  * expired timer (if @timers isn't NULL).
638  *
639  * Example:
640  *      io_loop(NULL, NULL);
641  */
642 void *io_loop(struct timers *timers, struct timer **expired);
643
644 /**
645  * io_conn_fd - get the fd from a connection.
646  * @conn: the connection.
647  *
648  * Sometimes useful, eg for getsockname().
649  */
650 int io_conn_fd(const struct io_conn *conn);
651
652 /**
653  * io_time_override - override the normal call for time.
654  * @nowfn: the function to call.
655  *
656  * io usually uses time_now() internally, but this forces it
657  * to use your function (eg. for debugging).  Returns the old
658  * one.
659  */
660 struct timeabs (*io_time_override(struct timeabs (*now)(void)))(void);
661
662 /**
663  * io_set_debug - set synchronous mode on a connection.
664  * @conn: the connection.
665  * @debug: whether to enable or disable debug.
666  *
667  * Once @debug is true on a connection, all I/O is done synchronously
668  * as soon as it is set, until it is unset or @conn is closed.  This
669  * makes it easy to debug what's happening with a connection, but note
670  * that other connections are starved while this is being done.
671  *
672  * See also: io_debug_complete()
673  *
674  * Example:
675  * // Dumb init function to set debug and tell conn to close.
676  * static struct io_plan *conn_init(struct io_conn *conn, const char *msg)
677  * {
678  *      io_set_debug(conn, true);
679  *      return io_close(conn);
680  * }
681  */
682 void io_set_debug(struct io_conn *conn, bool debug);
683
684 /**
685  * io_debug_complete - empty function called when conn is closing/waiting.
686  * @conn: the connection.
687  *
688  * This is for putting a breakpoint onto, when debugging.  It is called
689  * when a conn with io_set_debug() true can no longer be synchronous:
690  * 1) It is io_close()'d
691  * 2) It enters io_wait() (sychronous debug will resume after io_wake())
692  * 3) io_break() is called (sychronous debug will resume after io_loop())
693  */
694 void io_debug_complete(struct io_conn *conn);
695 #endif /* CCAN_IO_H */