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