chiark - git - mdw - disorder/blob - 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 3 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,
  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.
  14  *
  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/>.
  17  */
  18 /** @file lib/event.h
  19  * @brief DisOrder event loop
  20  */
  21 #ifndef EVENT_H
  22 #define EVENT_H
  23
  24 #include <sys/socket.h>
  25
  26 typedef struct ev_source ev_source;
  27
  28 struct rusage;
  29 struct sink;
  30
  31 ev_source *ev_new(void);
  32 /* create a new event loop */
  33
  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
  37  * called. */
  38
  39 /* file descriptors ***********************************************************/
  40
  41 typedef enum {
  42   ev_read,
  43   ev_write,
  44   ev_except,
  45
  46   ev_nmodes
  47 } ev_fdmode;
  48
  49 typedef int ev_fd_callback(ev_source *ev, int fd, void *u);
  50 /* signature for fd callback functions */
  51
  52 int ev_fd(ev_source *ev,
  53           ev_fdmode mode,
  54           int fd,
  55           ev_fd_callback *callback,
  56           void *u,
  57           const char *what);
  58 /* register a callback on a file descriptor */
  59
  60 int ev_fd_cancel(ev_source *ev,
  61                  ev_fdmode mode,
  62                  int fd);
  63 /* cancel a callback on a file descriptor */
  64
  65 int ev_fd_disable(ev_source *ev,
  66                   ev_fdmode mode,
  67                   int fd);
  68 /* temporarily disable callbacks on a file descriptor */
  69
  70 int ev_fd_enable(ev_source *ev,
  71                  ev_fdmode mode,
  72                  int fd);
  73 /* re-enable callbacks on a file descriptor */
  74
  75 void ev_report(ev_source *ev);
  76
  77 /* timeouts *******************************************************************/
  78
  79 typedef int ev_timeout_callback(ev_source *ev,
  80                                 const struct timeval *now,
  81                                 void *u);
  82 /* signature for timeout callback functions */
  83
  84 typedef void *ev_timeout_handle;
  85
  86 int ev_timeout(ev_source *ev,
  87                ev_timeout_handle *handlep,
  88                const struct timeval *when,
  89                ev_timeout_callback *callback,
  90                void *u);
  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. */
  93
  94 int ev_timeout_cancel(ev_source *ev,
  95                       ev_timeout_handle handle);
  96 /* cancel a timeout callback */
  97
  98 /* signals ********************************************************************/
  99
 100 typedef int ev_signal_callback(ev_source *ev,
 101                                int sig,
 102                                void *u);
 103 /* signature for signal callback functions */
 104
 105 int ev_signal(ev_source *ev,
 106               int sig,
 107               ev_signal_callback *callback,
 108               void *u);
 109 /* register a signal callback */
 110
 111 int ev_signal_cancel(ev_source *ev,
 112                      int sig);
 113 /* cancel a signal callback */
 114
 115 void ev_signal_atfork(ev_source *ev);
 116 /* unhandle and unblock handled signals - call after calling fork and
 117  * then setting @exitfn@ */
 118
 119 /* child processes ************************************************************/
 120
 121 typedef int ev_child_callback(ev_source *ev,
 122                               pid_t pid,
 123                               int status,
 124                               const struct rusage *rusage,
 125                               void *u);
 126 /* signature for child wait callbacks */
 127
 128 int ev_child_setup(ev_source *ev);
 129 /* must be called exactly once before @ev_child@ */
 130
 131 int ev_child(ev_source *ev,
 132              pid_t pid,
 133              int options,
 134              ev_child_callback *callback,
 135              void *u);
 136 /* register a child callback.  @options@ must be 0 or WUNTRACED. */
 137
 138 int ev_child_cancel(ev_source *ev,
 139                     pid_t pid);
 140 /* cancel a child callback. */
 141
 142 void ev_child_killall(ev_source *ev);
 143
 144 /* socket listeners ***********************************************************/
 145
 146 typedef int ev_listen_callback(ev_source *ev,
 147                                int newfd,
 148                                const struct sockaddr *remote,
 149                                socklen_t rlen,
 150                                void *u);
 151 /* callback when a connection arrives. */
 152
 153 int ev_listen(ev_source *ev,
 154               int fd,
 155               ev_listen_callback *callback,
 156               void *u,
 157               const char *what);
 158 /* register a socket listener callback.  @bind@ and @listen@ should
 159  * already have been called. */
 160
 161 int ev_listen_cancel(ev_source *ev,
 162                      int fd);
 163 /* cancel a socket listener callback */
 164
 165 /* buffered writer ************************************************************/
 166
 167 typedef struct ev_writer ev_writer;
 168
 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
 174  *
 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
 179  *
 180  * It is called for a reader only on error, with @p errno_value != 0.
 181  */
 182 typedef int ev_error_callback(ev_source *ev,
 183                               int errno_value,
 184                               void *u);
 185
 186 ev_writer *ev_writer_new(ev_source *ev,
 187                          int fd,
 188                          ev_error_callback *callback,
 189                          void *u,
 190                          const char *what);
 191 /* create a new buffered writer, writing to @fd@.  Calls @error@ if an
 192  * error occurs. */
 193
 194 int ev_writer_time_bound(ev_writer *ev,
 195                          int new_time_bound);
 196 int ev_writer_space_bound(ev_writer *ev,
 197                           int new_space_bound);
 198
 199 int ev_writer_close(ev_writer *w);
 200 /* close a writer (i.e. promise not to write to it any more) */
 201
 202 int ev_writer_cancel(ev_writer *w);
 203 /* cancel a writer */
 204
 205 int ev_writer_flush(ev_writer *w);
 206 /* attempt to flush the buffer */
 207
 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 */
 210
 211 /* buffered reader ************************************************************/
 212
 213 typedef struct ev_reader ev_reader;
 214
 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
 224  *
 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
 227  * consumed.
 228  *
 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.
 232  *
 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.
 237  */
 238 typedef int ev_reader_callback(ev_source *ev,
 239                                ev_reader *reader,
 240                                void *ptr,
 241                                size_t bytes,
 242                                int eof,
 243                                void *u);
 244
 245 ev_reader *ev_reader_new(ev_source *ev,
 246                          int fd,
 247                          ev_reader_callback *callback,
 248                          ev_error_callback *error_callback,
 249                          void *u,
 250                          const char *what);
 251 /* register a new reader.  @callback@ will be called whenever data is
 252  * available. */
 253
 254 void ev_reader_buffer(ev_reader *r, size_t nbytes);
 255 /* specify a buffer size */
 256
 257 void ev_reader_consume(ev_reader *r
 258                        , size_t nbytes);
 259 /* consume @nbytes@ bytes. */
 260
 261 int ev_reader_cancel(ev_reader *r);
 262 /* cancel a reader */
 263
 264 int ev_reader_disable(ev_reader *r);
 265 /* disable reading */
 266
 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) */
 270
 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
 274  * been read.
 275  *
 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.
 283  */
 284
 285 int ev_tie(ev_reader *r, ev_writer *w);
 286
 287 #endif /* EVENT_H */
 288
 289 /*
 290 Local Variables:
 291 c-basic-offset:2
 292 comment-column:40
 293 fill-column:79
 294 End:
 295 */