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/typesafe_cb/typesafe_cb.h>
   5 #include <ccan/time/time.h>
   6 #include <stdbool.h>
   7 #include <unistd.h>
   8 #include "io_plan.h"
   9
  10 /**
  11  * io_new_conn - create a new connection.
  12  * @fd: the file descriptor.
  13  * @plan: the first I/O to perform.
  14  *
  15  * This creates a connection which owns @fd.  @plan will be called on the
  16  * next io_loop().
  17  *
  18  * Returns NULL on error (and sets errno).
  19  */
  20 #define io_new_conn(fd, plan)                           \
  21         (io_plan_no_debug(), io_new_conn_((fd), (plan)))
  22 struct io_conn *io_new_conn_(int fd, struct io_plan plan);
  23
  24 /**
  25  * io_set_finish - set finish function on a connection.
  26  * @conn: the connection.
  27  * @finish: the function to call when it's closed or fails.
  28  * @arg: the argument to @finish.
  29  *
  30  * @finish will be called when an I/O operation fails, or you call
  31  * io_close() on the connection.  errno will be set to the value
  32  * after the failed I/O, or at the call to io_close().
  33  */
  34 #define io_set_finish(conn, finish, arg)                                \
  35         io_set_finish_((conn),                                          \
  36                        typesafe_cb_preargs(void, void *,                \
  37                                            (finish), (arg),             \
  38                                            struct io_conn *),           \
  39                        (arg))
  40 void io_set_finish_(struct io_conn *conn,
  41                     void (*finish)(struct io_conn *, void *),
  42                     void *arg);
  43
  44 /**
  45  * io_new_listener - create a new accepting listener.
  46  * @fd: the file descriptor.
  47  * @init: the function to call for a new connection
  48  * @arg: the argument to @init.
  49  *
  50  * When @fd becomes readable, we accept() and pass that fd to init().
  51  *
  52  * Returns NULL on error (and sets errno).
  53  */
  54 #define io_new_listener(fd, init, arg)                                  \
  55         io_new_listener_((fd),                                          \
  56                          typesafe_cb_preargs(void, void *,              \
  57                                              (init), (arg),             \
  58                                              int fd),                   \
  59                          (arg))
  60 struct io_listener *io_new_listener_(int fd,
  61                                      void (*init)(int fd, void *arg),
  62                                      void *arg);
  63
  64 /**
  65  * io_close_listener - delete a listener.
  66  * @listener: the listener returned from io_new_listener.
  67  *
  68  * This closes the fd and frees @listener.
  69  */
  70 void io_close_listener(struct io_listener *listener);
  71
  72 /**
  73  * io_write - plan to write data.
  74  * @data: the data buffer.
  75  * @len: the length to write.
  76  * @cb: function to call once it's done.
  77  * @arg: @cb argument
  78  *
  79  * This creates a plan write out a data buffer.  Once it's all
  80  * written, the @cb function will be called: on an error, the finish
  81  * function is called instead.
  82  *
  83  * Note that the I/O may actually be done immediately.
  84  */
  85 #define io_write(data, len, cb, arg)                                    \
  86         io_debug(io_write_((data), (len),                               \
  87                            typesafe_cb_preargs(struct io_plan, void *,  \
  88                                                (cb), (arg), struct io_conn *), \
  89                            (arg)))
  90 struct io_plan io_write_(const void *data, size_t len,
  91                          struct io_plan (*cb)(struct io_conn *, void *),
  92                          void *arg);
  93
  94 /**
  95  * io_read - plan to read data.
  96  * @data: the data buffer.
  97  * @len: the length to read.
  98  * @cb: function to call once it's done.
  99  * @arg: @cb argument
 100  *
 101  * This creates a plan to read data into a buffer.  Once it's all
 102  * read, the @cb function will be called: on an error, the finish
 103  * function is called instead.
 104  *
 105  * Note that the I/O may actually be done immediately.
 106  */
 107 #define io_read(data, len, cb, arg)                                     \
 108         io_debug(io_read_((data), (len),                                \
 109                           typesafe_cb_preargs(struct io_plan, void *,   \
 110                                               (cb), (arg), struct io_conn *), \
 111                           (arg)))
 112 struct io_plan io_read_(void *data, size_t len,
 113                         struct io_plan (*cb)(struct io_conn *, void *),
 114                         void *arg);
 115
 116
 117 /**
 118  * io_read_partial - plan to read some data.
 119  * @data: the data buffer.
 120  * @len: the maximum length to read, set to the length actually read.
 121  * @cb: function to call once it's done.
 122  * @arg: @cb argument
 123  *
 124  * This creates a plan to read data into a buffer.  Once any data is
 125  * read, @len is updated and the @cb function will be called: on an
 126  * error, the finish function is called instead.
 127  *
 128  * Note that the I/O may actually be done immediately.
 129  */
 130 #define io_read_partial(data, len, cb, arg)                             \
 131         io_debug(io_read_partial_((data), (len),                        \
 132                                   typesafe_cb_preargs(struct io_plan, void *, \
 133                                                       (cb), (arg),      \
 134                                                       struct io_conn *), \
 135                                   (arg)))
 136 struct io_plan io_read_partial_(void *data, size_t *len,
 137                                 struct io_plan (*cb)(struct io_conn *, void *),
 138                                 void *arg);
 139
 140 /**
 141  * io_write_partial - plan to write some data.
 142  * @data: the data buffer.
 143  * @len: the maximum length to write, set to the length actually written.
 144  * @cb: function to call once it's done.
 145  * @arg: @cb argument
 146  *
 147  * This creates a plan to write data from a buffer.   Once any data is
 148  * written, @len is updated and the @cb function will be called: on an
 149  * error, the finish function is called instead.
 150  *
 151  * Note that the I/O may actually be done immediately.
 152  */
 153 #define io_write_partial(data, len, cb, arg)                            \
 154         io_debug(io_write_partial_((data), (len),                       \
 155                                    typesafe_cb_preargs(struct io_plan, void *, \
 156                                                        (cb), (arg),     \
 157                                                        struct io_conn *), \
 158                                    (arg)))
 159 struct io_plan io_write_partial_(const void *data, size_t *len,
 160                                  struct io_plan (*cb)(struct io_conn *, void*),
 161                                  void *arg);
 162
 163 /**
 164  * io_connect - plan to connect to a listening socket.
 165  * @fd: file descriptor.
 166  * @addr: where to connect.
 167  * @cb: function to call once it's done.
 168  * @arg: @cb argument
 169  *
 170  * This initiates a connection, and creates a plan for
 171  * (asynchronously).  completing it.  Once complete, @len is updated
 172  * and the @cb function will be called: on an error, the finish
 173  * function is called instead.
 174  *
 175  * Note that the connect may actually be done immediately.
 176  */
 177 struct addrinfo;
 178 #define io_connect(fd, addr, cb, arg)                                   \
 179         io_debug(io_connect_((fd), (addr),                              \
 180                              typesafe_cb_preargs(struct io_plan, void *, \
 181                                                  (cb), (arg),           \
 182                                                  struct io_conn *),     \
 183                              (arg)))
 184 struct io_plan io_connect_(int fd, const struct addrinfo *addr,
 185                            struct io_plan (*cb)(struct io_conn *, void*),
 186                            void *arg);
 187
 188 /**
 189  * io_idle - plan to do nothing.
 190  *
 191  * This indicates the connection is idle: io_wake() will be called later do
 192  * give the connection a new plan.
 193  */
 194 #define io_idle() io_debug(io_idle_())
 195 struct io_plan io_idle_(void);
 196
 197 /**
 198  * io_timeout - set timeout function if the callback doesn't complete.
 199  * @conn: the current connection.
 200  * @ts: how long until the timeout should be called.
 201  * @cb: callback to call.
 202  * @arg: argument to @cb.
 203  *
 204  * If the usual next callback is not called for this connection before @ts,
 205  * this function will be called.  If next callback is called, the timeout
 206  * is automatically removed.
 207  *
 208  * Returns false on allocation failure.  A connection can only have one
 209  * timeout.
 210  */
 211 #define io_timeout(conn, ts, fn, arg)                                   \
 212         io_timeout_((conn), (ts),                                       \
 213                     typesafe_cb_preargs(struct io_plan, void *,         \
 214                                         (fn), (arg),                    \
 215                                         struct io_conn *),              \
 216                     (arg))
 217 bool io_timeout_(struct io_conn *conn, struct timespec ts,
 218                  struct io_plan (*fn)(struct io_conn *, void *), void *arg);
 219
 220 /**
 221  * io_duplex - split an fd into two connections.
 222  * @conn: a connection.
 223  * @plan: the first I/O function to call.
 224  *
 225  * Sometimes you want to be able to simultaneously read and write on a
 226  * single fd, but io forces a linear call sequence.  The solution is
 227  * to have two connections for the same fd, and use one for read
 228  * operations and one for write.
 229  *
 230  * You must io_close() both of them to close the fd.
 231  */
 232 #define io_duplex(conn, plan)                           \
 233         (io_plan_no_debug(), io_duplex_((conn), (plan)))
 234 struct io_conn *io_duplex_(struct io_conn *conn, struct io_plan plan);
 235
 236 /**
 237  * io_wake - wake up an idle connection.
 238  * @conn: an idle connection.
 239  * @plan: the next I/O plan for @conn.
 240  *
 241  * This makes @conn ready to do I/O the next time around the io_loop().
 242  */
 243 #define io_wake(conn, plan) (io_plan_no_debug(), io_wake_((conn), (plan)))
 244 void io_wake_(struct io_conn *conn, struct io_plan plan);
 245
 246 /**
 247  * io_break - return from io_loop()
 248  * @ret: non-NULL value to return from io_loop().
 249  * @plan: I/O to perform on return (if any)
 250  *
 251  * This breaks out of the io_loop.  As soon as the current @next
 252  * function returns, any io_closed()'d connections will have their
 253  * finish callbacks called, then io_loop() with return with @ret.
 254  *
 255  * If io_loop() is called again, then @plan will be carried out.
 256  */
 257 #define io_break(ret, plan) (io_plan_no_debug(), io_break_((ret), (plan)))
 258 struct io_plan io_break_(void *ret, struct io_plan plan);
 259
 260 /* FIXME: io_recvfrom/io_sendto */
 261
 262 /**
 263  * io_close - plan to close a connection.
 264  *
 265  * On return to io_loop, the connection will be closed.
 266  */
 267 #define io_close() io_debug(io_close_())
 268 struct io_plan io_close_(void);
 269
 270 /**
 271  * io_close_cb - helper callback to close a connection.
 272  * @conn: the connection.
 273  *
 274  * This schedules a connection to be closed; designed to be used as
 275  * a callback function.
 276  */
 277 struct io_plan io_close_cb(struct io_conn *, void *unused);
 278
 279 /**
 280  * io_loop - process fds until all closed on io_break.
 281  *
 282  * This is the core loop; it exits with the io_break() arg, or NULL if
 283  * all connections and listeners are closed.
 284  */
 285 void *io_loop(void);
 286 #endif /* CCAN_IO_H */