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