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_other(), 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_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_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_read_partial_((data), (len),                                 \
 132                          typesafe_cb_preargs(struct io_plan, void *,    \
 133                                              (cb), (arg), struct io_conn *), \
 134                          (arg))
 135 struct io_plan io_read_partial_(void *data, size_t *len,
 136                                 struct io_plan (*cb)(struct io_conn *, void *),
 137                                 void *arg);
 138
 139 /**
 140  * io_write_partial - plan to write some data.
 141  * @data: the data buffer.
 142  * @len: the maximum length to write, set to the length actually written.
 143  * @cb: function to call once it's done.
 144  * @arg: @cb argument
 145  *
 146  * This creates a plan to write data from a buffer.   Once any data is
 147  * written, @len is updated and the @cb function will be called: on an
 148  * error, the finish function is called instead.
 149  *
 150  * Note that the I/O may actually be done immediately.
 151  */
 152 #define io_write_partial(data, len, cb, arg)                            \
 153         io_write_partial_((data), (len),                                \
 154                           typesafe_cb_preargs(struct io_plan, void *,   \
 155                                               (cb), (arg), struct io_conn *), \
 156                           (arg))
 157 struct io_plan io_write_partial_(const void *data, size_t *len,
 158                                  struct io_plan (*cb)(struct io_conn *, void*),
 159                                  void *arg);
 160
 161 /**
 162  * io_idle - plan to do nothing.
 163  *
 164  * This indicates the connection is idle: io_wake() will be called later do
 165  * give the connection a new plan.
 166  */
 167 struct io_plan io_idle(void);
 168
 169 /**
 170  * io_timeout - set timeout function if the callback doesn't complete.
 171  * @conn: the current connection.
 172  * @ts: how long until the timeout should be called.
 173  * @cb: callback to call.
 174  * @arg: argument to @cb.
 175  *
 176  * If the usual next callback is not called for this connection before @ts,
 177  * this function will be called.  If next callback is called, the timeout
 178  * is automatically removed.
 179  *
 180  * Returns false on allocation failure.  A connection can only have one
 181  * timeout.
 182  */
 183 #define io_timeout(conn, ts, fn, arg)                                   \
 184         io_timeout_((conn), (ts),                                       \
 185                     typesafe_cb_preargs(struct io_plan, void *,         \
 186                                         (fn), (arg),                    \
 187                                         struct io_conn *),              \
 188                     (arg))
 189 bool io_timeout_(struct io_conn *conn, struct timespec ts,
 190                  struct io_plan (*fn)(struct io_conn *, void *), void *arg);
 191
 192 /**
 193  * io_duplex - split an fd into two connections.
 194  * @conn: a connection.
 195  * @plan: the first I/O function to call.
 196  *
 197  * Sometimes you want to be able to simultaneously read and write on a
 198  * single fd, but io forces a linear call sequence.  The solution is
 199  * to have two connections for the same fd, and use one for read
 200  * operations and one for write.
 201  *
 202  * You must io_close() both of them to close the fd.
 203  */
 204 #define io_duplex(conn, plan)                           \
 205         (io_plan_other(), io_duplex_((conn), (plan)))
 206 struct io_conn *io_duplex_(struct io_conn *conn, struct io_plan plan);
 207
 208 /**
 209  * io_wake - wake up an idle connection.
 210  * @conn: an idle connection.
 211  * @plan: the next I/O plan for @conn.
 212  *
 213  * This makes @conn ready to do I/O the next time around the io_loop().
 214  */
 215 #define io_wake(conn, plan) (io_plan_other(), io_wake_((conn), (plan)))
 216 void io_wake_(struct io_conn *conn, struct io_plan plan);
 217
 218 /**
 219  * io_break - return from io_loop()
 220  * @ret: non-NULL value to return from io_loop().
 221  * @plan: I/O to perform on return (if any)
 222  *
 223  * This breaks out of the io_loop.  As soon as the current @next
 224  * function returns, any io_closed()'d connections will have their
 225  * finish callbacks called, then io_loop() with return with @ret.
 226  *
 227  * If io_loop() is called again, then @plan will be carried out.
 228  */
 229 #define io_break(ret, plan) (io_plan_other(), io_break_((ret), (plan)))
 230 struct io_plan io_break_(void *ret, struct io_plan plan);
 231
 232 /* FIXME: io_recvfrom/io_sendto */
 233
 234 /**
 235  * io_close - plan to close a connection.
 236  *
 237  * On return to io_loop, the connection will be closed.
 238  */
 239 struct io_plan io_close(void);
 240
 241 /**
 242  * io_close_cb - helper callback to close a connection.
 243  * @conn: the connection.
 244  *
 245  * This schedules a connection to be closed; designed to be used as
 246  * a callback function.
 247  */
 248 struct io_plan io_close_cb(struct io_conn *, void *unused);
 249
 250 /**
 251  * io_loop - process fds until all closed on io_break.
 252  *
 253  * This is the core loop; it exits with the io_break() arg, or NULL if
 254  * all connections and listeners are closed.
 255  */
 256 void *io_loop(void);
 257 #endif /* CCAN_IO_H */