chiark - git - mdw - disorder/blob - lib/event.h

   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
  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 /* register a callback on a file descriptor */
  56
  57 int ev_fd_cancel(ev_source *ev,
  58                  ev_fdmode mode,
  59                  int fd);
  60 /* cancel a callback on a file descriptor */
  61
  62 int ev_fd_disable(ev_source *ev,
  63                   ev_fdmode mode,
  64                   int fd);
  65 /* temporarily disable callbacks on a file descriptor */
  66
  67 int 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
  74 typedef int ev_timeout_callback(ev_source *ev,
  75                                 const struct timeval *now,
  76                                 void *u);
  77 /* signature for timeout callback functions */
  78
  79 typedef void *ev_timeout_handle;
  80
  81 int 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
  89 int ev_timeout_cancel(ev_source *ev,
  90                       ev_timeout_handle handle);
  91 /* cancel a timeout callback */
  92
  93 /* signals ********************************************************************/
  94
  95 typedef int ev_signal_callback(ev_source *ev,
  96                                int sig,
  97                                void *u);
  98 /* signature for signal callback functions */
  99
 100 int ev_signal(ev_source *ev,
 101               int sig,
 102               ev_signal_callback *callback,
 103               void *u);
 104 /* register a signal callback */
 105
 106 int ev_signal_cancel(ev_source *ev,
 107                      int sig);
 108 /* cancel a signal callback */
 109
 110 void 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
 116 typedef 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
 123 int ev_child_setup(ev_source *ev);
 124 /* must be called exactly once before @ev_child@ */
 125
 126 int 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
 133 int ev_child_cancel(ev_source *ev,
 134                     pid_t pid);
 135 /* cancel a child callback. */
 136
 137 /* socket listeners ***********************************************************/
 138
 139 typedef 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
 146 int 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
 153 int ev_listen_cancel(ev_source *ev,
 154                      int fd);
 155 /* cancel a socket listener callback */
 156
 157 /* buffered writer ************************************************************/
 158
 159 typedef struct ev_writer ev_writer;
 160
 161 typedef 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
 168 ev_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
 175 int ev_writer_close(ev_writer *w);
 176 /* close a writer (i.e. promise not to write to it any more) */
 177
 178 int ev_writer_cancel(ev_writer *w);
 179 /* cancel a writer */
 180
 181 int ev_writer_flush(ev_writer *w);
 182 /* attempt to flush the buffer */
 183
 184 struct 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
 189 typedef struct ev_reader ev_reader;
 190
 191 typedef 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
 201 ev_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
 209 void ev_reader_buffer(ev_reader *r, size_t nbytes);
 210 /* specify a buffer size *case */
 211
 212 void ev_reader_consume(ev_reader *r, size_t nbytes);
 213 /* consume @nbytes@ bytes. */
 214
 215 int ev_reader_cancel(ev_reader *r);
 216 /* cancel a reader */
 217
 218 int ev_reader_disable(ev_reader *r);
 219 /* disable reading */
 220
 221 int 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
 225 int 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 /*
 242 Local Variables:
 243 c-basic-offset:2
 244 comment-column:40
 245 fill-column:79
 246 End:
 247 */