git.ozlabs.org Git - ccan/blob - 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 */