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