chiark / gitweb /
further empeg support
[disorder] / lib / event.h
CommitLineData
460b9539 1/*
2 * This file is part of DisOrder.
3 * Copyright (C) 2004 Richard Kettlewell
4 *
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.
9 *
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.
14 *
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
18 * USA
19 */
20
21#ifndef EVENT_H
22#define EVENT_H
23
24typedef struct ev_source ev_source;
25
26struct rusage;
27struct sink;
28
29ev_source *ev_new(void);
30/* create a new event loop */
31
32int 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
35 * called. */
36
37/* file descriptors ***********************************************************/
38
39typedef enum {
40 ev_read,
41 ev_write,
42 ev_except,
43
44 ev_nmodes
45} ev_fdmode;
46
47typedef int ev_fd_callback(ev_source *ev, int fd, void *u);
48/* signature for fd callback functions */
49
50int ev_fd(ev_source *ev,
51 ev_fdmode mode,
52 int fd,
53 ev_fd_callback *callback,
54 void *u);
55/* register a callback on a file descriptor */
56
57int ev_fd_cancel(ev_source *ev,
58 ev_fdmode mode,
59 int fd);
60/* cancel a callback on a file descriptor */
61
62int ev_fd_disable(ev_source *ev,
63 ev_fdmode mode,
64 int fd);
65/* temporarily disable callbacks on a file descriptor */
66
67int ev_fd_enable(ev_source *ev,
68 ev_fdmode mode,
69 int fd);
70/* re-enable callbacks on a file descriptor */
71
72/* timeouts *******************************************************************/
73
74typedef int ev_timeout_callback(ev_source *ev,
75 const struct timeval *now,
76 void *u);
77/* signature for timeout callback functions */
78
79typedef void *ev_timeout_handle;
80
81int ev_timeout(ev_source *ev,
82 ev_timeout_handle *handlep,
83 const struct timeval *when,
84 ev_timeout_callback *callback,
85 void *u);
86/* register a timeout callback. If @handlep@ is not a null pointer then a
87 * handle suitable for ev_timeout_cancel() below is returned through it. */
88
89int ev_timeout_cancel(ev_source *ev,
90 ev_timeout_handle handle);
91/* cancel a timeout callback */
92
93/* signals ********************************************************************/
94
95typedef int ev_signal_callback(ev_source *ev,
96 int sig,
97 void *u);
98/* signature for signal callback functions */
99
100int ev_signal(ev_source *ev,
101 int sig,
102 ev_signal_callback *callback,
103 void *u);
104/* register a signal callback */
105
106int ev_signal_cancel(ev_source *ev,
107 int sig);
108/* cancel a signal callback */
109
110void ev_signal_atfork(ev_source *ev);
111/* unhandle and unblock handled signals - call after calling fork and
112 * then setting @exitfn@ */
113
114/* child processes ************************************************************/
115
116typedef int ev_child_callback(ev_source *ev,
117 pid_t pid,
118 int status,
119 const struct rusage *rusage,
120 void *u);
121/* signature for child wait callbacks */
122
123int ev_child_setup(ev_source *ev);
124/* must be called exactly once before @ev_child@ */
125
126int ev_child(ev_source *ev,
127 pid_t pid,
128 int options,
129 ev_child_callback *callback,
130 void *u);
131/* register a child callback. @options@ must be 0 or WUNTRACED. */
132
133int ev_child_cancel(ev_source *ev,
134 pid_t pid);
135/* cancel a child callback. */
136
137/* socket listeners ***********************************************************/
138
139typedef int ev_listen_callback(ev_source *ev,
140 int newfd,
141 const struct sockaddr *remote,
142 socklen_t rlen,
143 void *u);
144/* callback when a connection arrives. */
145
146int ev_listen(ev_source *ev,
147 int fd,
148 ev_listen_callback *callback,
149 void *u);
150/* register a socket listener callback. @bind@ and @listen@ should
151 * already have been called. */
152
153int ev_listen_cancel(ev_source *ev,
154 int fd);
155/* cancel a socket listener callback */
156
157/* buffered writer ************************************************************/
158
159typedef struct ev_writer ev_writer;
160
161typedef int ev_error_callback(ev_source *ev,
162 int fd,
163 int errno_value,
164 void *u);
165/* called when an error occurs on a writer. Called with @errno_value@
166 * of 0 when finished. */
167
168ev_writer *ev_writer_new(ev_source *ev,
169 int fd,
170 ev_error_callback *callback,
171 void *u);
172/* create a new buffered writer, writing to @fd@. Calls @error@ if an
173 * error occurs. */
174
175int ev_writer_close(ev_writer *w);
176/* close a writer (i.e. promise not to write to it any more) */
177
178int ev_writer_cancel(ev_writer *w);
179/* cancel a writer */
180
181int ev_writer_flush(ev_writer *w);
182/* attempt to flush the buffer */
183
184struct sink *ev_writer_sink(ev_writer *w) attribute((const));
185/* return a sink for the writer - use this to actually write to it */
186
187/* buffered reader ************************************************************/
188
189typedef struct ev_reader ev_reader;
190
191typedef int ev_reader_callback(ev_source *ev,
192 ev_reader *reader,
193 int fd,
194 void *ptr,
195 size_t bytes,
196 int eof,
197 void *u);
198/* Called when data is read or an error occurs. @ptr@ and @bytes@
199 * indicate the amount of data available. @eof@ will be 1 at eof. */
200
201ev_reader *ev_reader_new(ev_source *ev,
202 int fd,
203 ev_reader_callback *callback,
204 ev_error_callback *error_callback,
205 void *u);
206/* register a new reader. @callback@ will be called whenever data is
207 * available. */
208
209void ev_reader_buffer(ev_reader *r, size_t nbytes);
210/* specify a buffer size *case */
211
212void ev_reader_consume(ev_reader *r, size_t nbytes);
213/* consume @nbytes@ bytes. */
214
215int ev_reader_cancel(ev_reader *r);
216/* cancel a reader */
217
218int ev_reader_disable(ev_reader *r);
219/* disable reading */
220
221int ev_reader_incomplete(ev_reader *r);
222/* callback didn't fully process buffer, but would like another
223 * callback (used where processing more would block too long) */
224
225int ev_reader_enable(ev_reader *r);
226/* enable reading. If there is unconsumed data then you get a
227 * callback next time round the event loop even if nothing new has
228 * been read.
229 *
230 * The idea is in your read callback you come across a line (or
231 * whatever) that can't be processed immediately. So you set up
232 * processing and disable reading. Later when you finish processing
233 * you re-enable. You'll automatically get another callback pretty
234 * much direct from the event loop (not from inside ev_reader_enable)
235 * so you can handle the next line (or whatever) if the whole thing
236 * has in fact already arrived.
237 */
238
239#endif /* EVENT_H */
240
241/*
242Local Variables:
243c-basic-offset:2
244comment-column:40
245fill-column:79
246End:
247*/