2 * This file is part of DisOrder.
3 * Copyright (C) 2004, 2007 Richard Kettlewell
5 * This program is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation, either version 3 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
19 * @brief DisOrder event loop
24 #include <sys/socket.h>
26 typedef struct ev_source ev_source
;
31 ev_source
*ev_new(void);
32 /* create a new event loop */
34 int ev_run(ev_source
*ev
);
35 /* run an event loop. If any callback returns nonzero then that value
36 * is returned. If an error occurs then -1 is returned and @error@ is
39 /* file descriptors ***********************************************************/
49 typedef int ev_fd_callback(ev_source
*ev
, int fd
, void *u
);
50 /* signature for fd callback functions */
52 int ev_fd(ev_source
*ev
,
55 ev_fd_callback
*callback
,
58 /* register a callback on a file descriptor */
60 int ev_fd_cancel(ev_source
*ev
,
63 /* cancel a callback on a file descriptor */
65 int ev_fd_disable(ev_source
*ev
,
68 /* temporarily disable callbacks on a file descriptor */
70 int ev_fd_enable(ev_source
*ev
,
73 /* re-enable callbacks on a file descriptor */
75 void ev_report(ev_source
*ev
);
77 /* timeouts *******************************************************************/
79 typedef int ev_timeout_callback(ev_source
*ev
,
80 const struct timeval
*now
,
82 /* signature for timeout callback functions */
84 typedef void *ev_timeout_handle
;
86 int ev_timeout(ev_source
*ev
,
87 ev_timeout_handle
*handlep
,
88 const struct timeval
*when
,
89 ev_timeout_callback
*callback
,
91 /* register a timeout callback. If @handlep@ is not a null pointer then a
92 * handle suitable for ev_timeout_cancel() below is returned through it. */
94 int ev_timeout_cancel(ev_source
*ev
,
95 ev_timeout_handle handle
);
96 /* cancel a timeout callback */
98 /* signals ********************************************************************/
100 typedef int ev_signal_callback(ev_source
*ev
,
103 /* signature for signal callback functions */
105 int ev_signal(ev_source
*ev
,
107 ev_signal_callback
*callback
,
109 /* register a signal callback */
111 int ev_signal_cancel(ev_source
*ev
,
113 /* cancel a signal callback */
115 void ev_signal_atfork(ev_source
*ev
);
116 /* unhandle and unblock handled signals - call after calling fork and
117 * then setting @exitfn@ */
119 /* child processes ************************************************************/
121 typedef int ev_child_callback(ev_source
*ev
,
124 const struct rusage
*rusage
,
126 /* signature for child wait callbacks */
128 int ev_child_setup(ev_source
*ev
);
129 /* must be called exactly once before @ev_child@ */
131 int ev_child(ev_source
*ev
,
134 ev_child_callback
*callback
,
136 /* register a child callback. @options@ must be 0 or WUNTRACED. */
138 int ev_child_cancel(ev_source
*ev
,
140 /* cancel a child callback. */
142 void ev_child_killall(ev_source
*ev
);
144 /* socket listeners ***********************************************************/
146 typedef int ev_listen_callback(ev_source
*ev
,
148 const struct sockaddr
*remote
,
151 /* callback when a connection arrives. */
153 int ev_listen(ev_source
*ev
,
155 ev_listen_callback
*callback
,
158 /* register a socket listener callback. @bind@ and @listen@ should
159 * already have been called. */
161 int ev_listen_cancel(ev_source
*ev
,
163 /* cancel a socket listener callback */
165 /* buffered writer ************************************************************/
167 typedef struct ev_writer ev_writer
;
169 /** @brief Error callback for @ref ev_reader and @ref ev_writer
170 * @param ev Event loop
171 * @param errno_value Errno value (might be 0)
172 * @param u As passed to ev_writer_new() or ev_reader_new()
173 * @return 0 on success, non-0 on error
175 * This is called for a writer in the following situations:
176 * - on error, with @p errno_value != 0
177 * - when all buffered data has been written, with @p errno_value = 0
178 * - after called ev_writer_cancel(), with @p errno_value = 0
180 * It is called for a reader only on error, with @p errno_value != 0.
182 typedef int ev_error_callback(ev_source
*ev
,
186 ev_writer
*ev_writer_new(ev_source
*ev
,
188 ev_error_callback
*callback
,
191 /* create a new buffered writer, writing to @fd@. Calls @error@ if an
194 int ev_writer_time_bound(ev_writer
*ev
,
196 int ev_writer_space_bound(ev_writer
*ev
,
197 int new_space_bound
);
199 int ev_writer_close(ev_writer
*w
);
200 /* close a writer (i.e. promise not to write to it any more) */
202 int ev_writer_cancel(ev_writer
*w
);
203 /* cancel a writer */
205 int ev_writer_flush(ev_writer
*w
);
206 /* attempt to flush the buffer */
208 struct sink
*ev_writer_sink(ev_writer
*w
) attribute((const));
209 /* return a sink for the writer - use this to actually write to it */
211 /* buffered reader ************************************************************/
213 typedef struct ev_reader ev_reader
;
215 /** @brief Called when data is available to read
216 * @param ev Event loop
217 * @param reader Reader
218 * @param fd File descriptor we read from
219 * @param ptr Pointer to first byte
220 * @param bytes Number of bytes available
221 * @param eof True if EOF has been detected
222 * @param u As passed to ev_reader_new()
223 * @return 0 on succes, non-0 on error
225 * This callback should call ev_reader_consume() to indicate how many bytes you
226 * actually used. If you do not call it then it is assumed no bytes were
229 * If having consumed some number of bytes it is not possible to do any further
230 * processing until more data is available then the callback can just return.
231 * Note that this is not allowed if @p eof was set.
233 * If on the other hand it would be possible to do more processing immediately
234 * with the bytes available, but this is undesirable for some other reason,
235 * then ev_reader_incomplete() should be called. This will arrange a further
236 * callback in the very near future even if no more bytes are read.
238 typedef int ev_reader_callback(ev_source
*ev
,
245 ev_reader
*ev_reader_new(ev_source
*ev
,
247 ev_reader_callback
*callback
,
248 ev_error_callback
*error_callback
,
251 /* register a new reader. @callback@ will be called whenever data is
254 void ev_reader_buffer(ev_reader
*r
, size_t nbytes
);
255 /* specify a buffer size */
257 void ev_reader_consume(ev_reader
*r
259 /* consume @nbytes@ bytes. */
261 int ev_reader_cancel(ev_reader
*r
);
262 /* cancel a reader */
264 int ev_reader_disable(ev_reader
*r
);
265 /* disable reading */
267 int ev_reader_incomplete(ev_reader
*r
);
268 /* callback didn't fully process buffer, but would like another
269 * callback (used where processing more would block too long) */
271 int ev_reader_enable(ev_reader
*r
);
272 /* enable reading. If there is unconsumed data then you get a
273 * callback next time round the event loop even if nothing new has
276 * The idea is in your read callback you come across a line (or
277 * whatever) that can't be processed immediately. So you set up
278 * processing and disable reading. Later when you finish processing
279 * you re-enable. You'll automatically get another callback pretty
280 * much direct from the event loop (not from inside ev_reader_enable)
281 * so you can handle the next line (or whatever) if the whole thing
282 * has in fact already arrived.
285 int ev_tie(ev_reader
*r
, ev_writer
*w
);