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 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * 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, write to the Free Software
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
24 typedef struct ev_source ev_source;
29 ev_source *ev_new(void);
30 /* create a new event loop */
32 int ev_run(ev_source *ev);
33 /* run an event loop. If any callback returns nonzero then that value
34 * is returned. If an error occurs then -1 is returned and @error@ is
37 /* file descriptors ***********************************************************/
47 typedef int ev_fd_callback(ev_source *ev, int fd, void *u);
48 /* signature for fd callback functions */
50 int ev_fd(ev_source *ev,
53 ev_fd_callback *callback,
56 /* register a callback on a file descriptor */
58 int ev_fd_cancel(ev_source *ev,
61 /* cancel a callback on a file descriptor */
63 int ev_fd_disable(ev_source *ev,
66 /* temporarily disable callbacks on a file descriptor */
68 int ev_fd_enable(ev_source *ev,
71 /* re-enable callbacks on a file descriptor */
73 void ev_report(ev_source *ev);
75 /* timeouts *******************************************************************/
77 typedef int ev_timeout_callback(ev_source *ev,
78 const struct timeval *now,
80 /* signature for timeout callback functions */
82 typedef void *ev_timeout_handle;
84 int ev_timeout(ev_source *ev,
85 ev_timeout_handle *handlep,
86 const struct timeval *when,
87 ev_timeout_callback *callback,
89 /* register a timeout callback. If @handlep@ is not a null pointer then a
90 * handle suitable for ev_timeout_cancel() below is returned through it. */
92 int ev_timeout_cancel(ev_source *ev,
93 ev_timeout_handle handle);
94 /* cancel a timeout callback */
96 /* signals ********************************************************************/
98 typedef int ev_signal_callback(ev_source *ev,
101 /* signature for signal callback functions */
103 int ev_signal(ev_source *ev,
105 ev_signal_callback *callback,
107 /* register a signal callback */
109 int ev_signal_cancel(ev_source *ev,
111 /* cancel a signal callback */
113 void ev_signal_atfork(ev_source *ev);
114 /* unhandle and unblock handled signals - call after calling fork and
115 * then setting @exitfn@ */
117 /* child processes ************************************************************/
119 typedef int ev_child_callback(ev_source *ev,
122 const struct rusage *rusage,
124 /* signature for child wait callbacks */
126 int ev_child_setup(ev_source *ev);
127 /* must be called exactly once before @ev_child@ */
129 int ev_child(ev_source *ev,
132 ev_child_callback *callback,
134 /* register a child callback. @options@ must be 0 or WUNTRACED. */
136 int ev_child_cancel(ev_source *ev,
138 /* cancel a child callback. */
140 /* socket listeners ***********************************************************/
142 typedef int ev_listen_callback(ev_source *ev,
144 const struct sockaddr *remote,
147 /* callback when a connection arrives. */
149 int ev_listen(ev_source *ev,
151 ev_listen_callback *callback,
154 /* register a socket listener callback. @bind@ and @listen@ should
155 * already have been called. */
157 int ev_listen_cancel(ev_source *ev,
159 /* cancel a socket listener callback */
161 /* buffered writer ************************************************************/
163 typedef struct ev_writer ev_writer;
165 /** @brief Error callback for @ref ev_reader and @ref ev_writer
166 * @param ev Event loop
167 * @param errno_value Errno value (might be 0)
168 * @param u As passed to ev_writer_new() or ev_reader_new()
169 * @return 0 on success, non-0 on error
171 * This is called for a writer in the following situations:
172 * - on error, with @p errno_value != 0
173 * - when all buffered data has been written, with @p errno_value = 0
174 * - after called ev_writer_cancel(), with @p errno_value = 0
176 * It is called for a reader only on error, with @p errno_value != 0.
178 typedef int ev_error_callback(ev_source *ev,
182 ev_writer *ev_writer_new(ev_source *ev,
184 ev_error_callback *callback,
187 /* create a new buffered writer, writing to @fd@. Calls @error@ if an
190 int ev_writer_time_bound(ev_writer *ev,
192 int ev_writer_space_bound(ev_writer *ev,
193 int new_space_bound);
195 int ev_writer_close(ev_writer *w);
196 /* close a writer (i.e. promise not to write to it any more) */
198 int ev_writer_cancel(ev_writer *w);
199 /* cancel a writer */
201 int ev_writer_flush(ev_writer *w);
202 /* attempt to flush the buffer */
204 struct sink *ev_writer_sink(ev_writer *w) attribute((const));
205 /* return a sink for the writer - use this to actually write to it */
207 /* buffered reader ************************************************************/
209 typedef struct ev_reader ev_reader;
211 /** @brief Called when data is available to read
212 * @param ev Event loop
213 * @param reader Reader
214 * @param fd File descriptor we read from
215 * @param ptr Pointer to first byte
216 * @param bytes Number of bytes available
217 * @param eof True if EOF has been detected
218 * @param u As passed to ev_reader_new()
219 * @return 0 on succes, non-0 on error
221 * This callback should call ev_reader_consume() to indicate how many bytes you
222 * actually used. If you do not call it then it is assumed no bytes were
225 * If having consumed some number of bytes it is not possible to do any further
226 * processing until more data is available then the callback can just return.
227 * Note that this is not allowed if @p eof was set.
229 * If on the other hand it would be possible to do more processing immediately
230 * with the bytes available, but this is undesirable for some other reason,
231 * then ev_reader_incomplete() should be called. This will arrange a further
232 * callback in the very near future even if no more bytes are read.
234 typedef int ev_reader_callback(ev_source *ev,
241 ev_reader *ev_reader_new(ev_source *ev,
243 ev_reader_callback *callback,
244 ev_error_callback *error_callback,
247 /* register a new reader. @callback@ will be called whenever data is
250 void ev_reader_buffer(ev_reader *r, size_t nbytes);
251 /* specify a buffer size */
253 void ev_reader_consume(ev_reader *r
255 /* consume @nbytes@ bytes. */
257 int ev_reader_cancel(ev_reader *r);
258 /* cancel a reader */
260 int ev_reader_disable(ev_reader *r);
261 /* disable reading */
263 int ev_reader_incomplete(ev_reader *r);
264 /* callback didn't fully process buffer, but would like another
265 * callback (used where processing more would block too long) */
267 int ev_reader_enable(ev_reader *r);
268 /* enable reading. If there is unconsumed data then you get a
269 * callback next time round the event loop even if nothing new has
272 * The idea is in your read callback you come across a line (or
273 * whatever) that can't be processed immediately. So you set up
274 * processing and disable reading. Later when you finish processing
275 * you re-enable. You'll automatically get another callback pretty
276 * much direct from the event loop (not from inside ev_reader_enable)
277 * so you can handle the next line (or whatever) if the whole thing
278 * has in fact already arrived.
281 int ev_tie(ev_reader *r, ev_writer *w);