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_idle - plan to do nothing.
 165  *
 166  * This indicates the connection is idle: io_wake() will be called later do
 167  * give the connection a new plan.
 168  */
 169 #define io_idle() io_debug(io_idle_())
 170 struct io_plan io_idle_(void);
 171
 172 /**
 173  * io_timeout - set timeout function if the callback doesn't complete.
 174  * @conn: the current connection.
 175  * @ts: how long until the timeout should be called.
 176  * @cb: callback to call.
 177  * @arg: argument to @cb.
 178  *
 179  * If the usual next callback is not called for this connection before @ts,
 180  * this function will be called.  If next callback is called, the timeout
 181  * is automatically removed.
 182  *
 183  * Returns false on allocation failure.  A connection can only have one
 184  * timeout.
 185  */
 186 #define io_timeout(conn, ts, fn, arg)                                   \
 187         io_timeout_((conn), (ts),                                       \
 188                     typesafe_cb_preargs(struct io_plan, void *,         \
 189                                         (fn), (arg),                    \
 190                                         struct io_conn *),              \
 191                     (arg))
 192 bool io_timeout_(struct io_conn *conn, struct timespec ts,
 193                  struct io_plan (*fn)(struct io_conn *, void *), void *arg);
 194
 195 /**
 196  * io_duplex - split an fd into two connections.
 197  * @conn: a connection.
 198  * @plan: the first I/O function to call.
 199  *
 200  * Sometimes you want to be able to simultaneously read and write on a
 201  * single fd, but io forces a linear call sequence.  The solution is
 202  * to have two connections for the same fd, and use one for read
 203  * operations and one for write.
 204  *
 205  * You must io_close() both of them to close the fd.
 206  */
 207 #define io_duplex(conn, plan)                           \
 208         (io_plan_no_debug(), io_duplex_((conn), (plan)))
 209 struct io_conn *io_duplex_(struct io_conn *conn, struct io_plan plan);
 210
 211 /**
 212  * io_wake - wake up an idle connection.
 213  * @conn: an idle connection.
 214  * @plan: the next I/O plan for @conn.
 215  *
 216  * This makes @conn ready to do I/O the next time around the io_loop().
 217  */
 218 #define io_wake(conn, plan) (io_plan_no_debug(), io_wake_((conn), (plan)))
 219 void io_wake_(struct io_conn *conn, struct io_plan plan);
 220
 221 /**
 222  * io_break - return from io_loop()
 223  * @ret: non-NULL value to return from io_loop().
 224  * @plan: I/O to perform on return (if any)
 225  *
 226  * This breaks out of the io_loop.  As soon as the current @next
 227  * function returns, any io_closed()'d connections will have their
 228  * finish callbacks called, then io_loop() with return with @ret.
 229  *
 230  * If io_loop() is called again, then @plan will be carried out.
 231  */
 232 #define io_break(ret, plan) (io_plan_no_debug(), io_break_((ret), (plan)))
 233 struct io_plan io_break_(void *ret, struct io_plan plan);
 234
 235 /* FIXME: io_recvfrom/io_sendto */
 236
 237 /**
 238  * io_close - plan to close a connection.
 239  *
 240  * On return to io_loop, the connection will be closed.
 241  */
 242 #define io_close() io_debug(io_close_())
 243 struct io_plan io_close_(void);
 244
 245 /**
 246  * io_close_cb - helper callback to close a connection.
 247  * @conn: the connection.
 248  *
 249  * This schedules a connection to be closed; designed to be used as
 250  * a callback function.
 251  */
 252 struct io_plan io_close_cb(struct io_conn *, void *unused);
 253
 254 /**
 255  * io_loop - process fds until all closed on io_break.
 256  *
 257  * This is the core loop; it exits with the io_break() arg, or NULL if
 258  * all connections and listeners are closed.
 259  */
 260 void *io_loop(void);
 261 #endif /* CCAN_IO_H */