1 /* Licensed under LGPLv2.1+ - see LICENSE file for details */
4 #include <ccan/typesafe_cb/typesafe_cb.h>
5 #include <ccan/time/time.h>
10 * struct io_plan - pointer to return from a setup function.
12 * A plan of what IO to do, when.
17 * io_new_conn - create a new connection.
18 * @fd: the file descriptor.
19 * @start: the first function to call.
20 * @finish: the function to call when it's closed or fails.
21 * @arg: the argument to both @start and @finish.
23 * This creates a connection which owns @fd. @start will be called on the
24 * next return to io_loop(), and @finish will be called when an I/O operation
25 * fails, or you call io_close() on the connection.
27 * The @start function must call one of the io queueing functions
28 * (eg. io_read, io_write) and return the next function to call once
29 * that is done using io_next(). The alternative is to call io_close().
31 * Returns NULL on error (and sets errno).
33 #define io_new_conn(fd, start, finish, arg) \
35 typesafe_cb_preargs(struct io_plan *, void *, \
36 (start), (arg), struct io_conn *), \
37 typesafe_cb_preargs(void, void *, (finish), (arg), \
40 struct io_conn *io_new_conn_(int fd,
41 struct io_plan *(*start)(struct io_conn *, void *),
42 void (*finish)(struct io_conn *, void *),
46 * io_new_listener - create a new accepting listener.
47 * @fd: the file descriptor.
48 * @start: the first function to call on new connections.
49 * @finish: the function to call when the connection is closed or fails.
50 * @arg: the argument to both @start and @finish.
52 * When @fd becomes readable, we accept() and turn that fd into a new
55 * Returns NULL on error (and sets errno).
57 #define io_new_listener(fd, start, finish, arg) \
58 io_new_listener_((fd), \
59 typesafe_cb_preargs(struct io_plan *, void *, \
62 typesafe_cb_preargs(void, void *, (finish), \
63 (arg), struct io_conn *), \
65 struct io_listener *io_new_listener_(int fd,
66 struct io_plan *(*start)(struct io_conn *,
68 void (*finish)(struct io_conn *,
73 * io_close_listener - delete a listener.
74 * @listener: the listener returned from io_new_listener.
76 * This closes the fd and frees @listener.
78 void io_close_listener(struct io_listener *listener);
81 * io_write - queue data to be written.
82 * @conn: the current connection.
83 * @data: the data buffer.
84 * @len: the length to write.
85 * @cb: function to call once it's done.
88 * This will queue the data buffer for writing. Once it's all
89 * written, the @cb function will be called: on an error, the finish
90 * function is called instead.
92 * Note that the I/O may actually be done immediately.
94 #define io_write(conn, data, len, cb, arg) \
95 io_write_((conn), (data), (len), \
96 typesafe_cb_preargs(struct io_plan *, void *, \
97 (cb), (arg), struct io_conn *), \
99 struct io_plan *io_write_(struct io_conn *conn, const void *data, size_t len,
100 struct io_plan *(*cb)(struct io_conn *, void *),
104 * io_read - queue buffer to be read.
105 * @conn: the current connection.
106 * @data: the data buffer.
107 * @len: the length to read.
108 * @cb: function to call once it's done.
111 * This will queue the data buffer for reading. Once it's all read,
112 * the @cb function will be called: on an error, the finish function
115 * Note that the I/O may actually be done immediately.
117 #define io_read(conn, data, len, cb, arg) \
118 io_read_((conn), (data), (len), \
119 typesafe_cb_preargs(struct io_plan *, void *, \
120 (cb), (arg), struct io_conn *), \
122 struct io_plan *io_read_(struct io_conn *conn, void *data, size_t len,
123 struct io_plan *(*cb)(struct io_conn *, void *),
128 * io_read_partial - queue buffer to be read (partial OK).
129 * @conn: the current connection.
130 * @data: the data buffer.
131 * @len: the maximum length to read, set to the length actually read.
132 * @cb: function to call once it's done.
135 * This will queue the data buffer for reading. Once any data is
136 * read, @len is updated and the @cb function will be called: on an
137 * error, the finish function is called instead.
139 * Note that the I/O may actually be done immediately.
141 #define io_read_partial(conn, data, len, cb, arg) \
142 io_read_partial_((conn), (data), (len), \
143 typesafe_cb_preargs(struct io_plan *, void *, \
144 (cb), (arg), struct io_conn *), \
146 struct io_plan *io_read_partial_(struct io_conn *conn, void *data, size_t *len,
147 struct io_plan *(*cb)(struct io_conn *, void *),
151 * io_write_partial - queue data to be written (partial OK).
152 * @conn: the current connection.
153 * @data: the data buffer.
154 * @len: the maximum length to write, set to the length actually written.
155 * @cb: function to call once it's done.
158 * This will queue the data buffer for writing. Once any data is
159 * written, @len is updated and the @cb function will be called: on an
160 * error, the finish function is called instead.
162 * Note that the I/O may actually be done immediately.
164 #define io_write_partial(conn, data, len, cb, arg) \
165 io_write_partial_((conn), (data), (len), \
166 typesafe_cb_preargs(struct io_plan *, void *, \
167 (cb), (arg), struct io_conn *), \
169 struct io_plan *io_write_partial_(struct io_conn *conn,
170 const void *data, size_t *len,
171 struct io_plan *(*cb)(struct io_conn *, void*),
176 * io_idle - explicitly note that this connection will do nothing.
177 * @conn: the current connection.
179 * This indicates the connection is idle: some other function will
180 * later call io_read/io_write etc. (or io_close) on it, in which case
183 struct io_plan *io_idle(struct io_conn *conn);
186 * io_timeout - set timeout function if the callback doesn't fire.
187 * @conn: the current connection.
188 * @ts: how long until the timeout should be called.
190 * @arg: argument to @cb.
192 * If the usual next callback is not called for this connection before @ts,
193 * this function will be called. If next callback is called, the timeout
194 * is automatically removed.
196 * Returns false on allocation failure. A connection can only have one
199 #define io_timeout(conn, ts, fn, arg) \
200 io_timeout_((conn), (ts), \
201 typesafe_cb_preargs(struct io_plan *, void *, \
205 bool io_timeout_(struct io_conn *conn, struct timespec ts,
206 struct io_plan *(*fn)(struct io_conn *, void *), void *arg);
209 * io_duplex - split an fd into two connections.
210 * @conn: a connection.
211 * @start: the first function to call.
212 * @finish: the function to call when it's closed or fails.
213 * @arg: the argument to both @start and @finish.
215 * Sometimes you want to be able to simultaneously read and write on a
216 * single fd, but io forces a linear call sequence. The solition is
217 * to have two connections for the same fd, and use one for read
218 * operations and one for write.
220 * You must io_close() both of them to close the fd.
222 #define io_duplex(conn, start, finish, arg) \
224 typesafe_cb_preargs(struct io_plan *, void *, \
225 (start), (arg), struct io_conn *), \
226 typesafe_cb_preargs(void, void *, (finish), (arg), \
230 struct io_conn *io_duplex_(struct io_conn *conn,
231 struct io_plan *(*start)(struct io_conn *, void *),
232 void (*finish)(struct io_conn *, void *),
236 * io_wake - wake up and idle connection.
237 * @conn: an idle connection.
238 * @fn: the next function to call once queued IO is complete.
239 * @arg: the argument to @next.
241 * This makes @conn run its @next function the next time around the
244 #define io_wake(conn, fn, arg) \
246 typesafe_cb_preargs(struct io_plan *, void *, \
247 (fn), (arg), struct io_conn *), \
249 void io_wake_(struct io_conn *conn,
250 struct io_plan *(*fn)(struct io_conn *, void *), void *arg);
253 * io_break - return from io_loop()
254 * @conn: the current connection.
255 * @ret: non-NULL value to return from io_loop().
256 * @cb: function to call once on return
259 * This breaks out of the io_loop. As soon as the current @next
260 * function returns, any io_closed()'d connections will have their
261 * finish callbacks called, then io_loop() with return with @ret.
263 * If io_loop() is called again, then @cb will be called.
265 #define io_break(conn, ret, fn, arg) \
266 io_break_((conn), (ret), \
267 typesafe_cb_preargs(struct io_plan *, void *, \
268 (fn), (arg), struct io_conn *), \
270 struct io_plan *io_break_(struct io_conn *conn, void *ret,
271 struct io_plan *(*fn)(struct io_conn *, void *),
274 /* FIXME: io_recvfrom/io_sendto */
277 * io_close - terminate a connection.
278 * @conn: any connection.
280 * The schedules a connection to be closed. It can be done on any
281 * connection, whether it has I/O queued or not (though that I/O may
282 * be performed first).
284 * It's common to 'return io_close(...)' from a @next function, but
285 * io_close can also be used as an argument to io_next().
287 struct io_plan *io_close(struct io_conn *, void *unused);
290 * io_loop - process fds until all closed on io_break.
292 * This is the core loop; it exits with the io_break() arg, or NULL if
293 * all connections and listeners are closed.
296 #endif /* CCAN_IO_H */