src/eloop.h

   1 /*
   2  * Event Loop
   3  *
   4  * Copyright (c) 2011-2012 David Herrmann <dh.herrmann@googlemail.com>
   5  * Copyright (c) 2011 University of Tuebingen
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining
   8  * a copy of this software and associated documentation files
   9  * (the "Software"), to deal in the Software without restriction, including
  10  * without limitation the rights to use, copy, modify, merge, publish,
  11  * distribute, sublicense, and/or sell copies of the Software, and to
  12  * permit persons to whom the Software is furnished to do so, subject to
  13  * the following conditions:
  14  *
  15  * The above copyright notice and this permission notice shall be included
  16  * in all copies or substantial portions of the Software.
  17  *
  18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  19  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  20  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  21  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  22  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  23  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  24  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  25  */
  26
  27 /*
  28  * Event Loop
  29  * This provides a basic event loop similar to those provided by glib etc.
  30  * It uses linux specific features like signalfd so it may not be easy to port
  31  * it to other platforms.
  32  */
  33
  34 #ifndef EV_ELOOP_H
  35 #define EV_ELOOP_H
  36
  37 #include <inttypes.h>
  38 #include <stdarg.h>
  39 #include <stdbool.h>
  40 #include <stdlib.h>
  41 #include <sys/signalfd.h>
  42 #include <sys/types.h>
  43 #include <time.h>
  44
  45 struct ev_eloop;
  46 struct ev_fd;
  47 struct ev_timer;
  48 struct ev_counter;
  49
  50 /**
  51  * ev_log_t:
  52  * @file: Source code file where the log message originated or NULL
  53  * @line: Line number in source code or 0
  54  * @func: C function name or NULL
  55  * @subs: Subsystem where the message came from or NULL
  56  * @sev: Kernel-style severity between 0=FATAL and 7=DEBUG
  57  * @format: printf-formatted message
  58  * @args: arguments for printf-style @format
  59  *
  60  * This is the type of a logging callback function. You can always pass NULL
  61  * instead of such a function to disable logging.
  62  */
  63 typedef void (*ev_log_t) (const char *file,
  64                           int line,
  65                           const char *func,
  66                           const char *subs,
  67                           unsigned int sev,
  68                           const char *format,
  69                           va_list args);
  70
  71 /**
  72  * ev_fd_cb:
  73  * @fd: File descriptor event source
  74  * @mask: Mask of @EV_READABLE, @EV_WRITEABLE, etc.
  75  * @data: user-supplied data
  76  *
  77  * This is the callback-type for file-descriptor event sources.
  78  */
  79 typedef void (*ev_fd_cb) (struct ev_fd *fd, int mask, void *data);
  80
  81 /**
  82  * ev_timer_cb:
  83  * @timer: Timer source
  84  * @num: Number of times the timer fired since last wakeup
  85  * @data: user-supplied data
  86  *
  87  * This is the callback-type for timer event sources. If the process was too
  88  * busy to be woken up as fast as possible, then @num may be bigger than 1.
  89  */
  90 typedef void (*ev_timer_cb)
  91                         (struct ev_timer *timer, uint64_t num, void *data);
  92
  93 /**
  94  * ev_counter_cb:
  95  * @cnt: Counter source
  96  * @num: Current counter state
  97  * @data: user-supplied data
  98  *
  99  * This is the callback-type for counter event sources. @num is at least 1 but
 100  * may be bigger if the timer was increased multiple times or by bigger values.
 101  * The counter is reset to 0 before this callback is called.
 102  */
 103 typedef void (*ev_counter_cb)
 104                         (struct ev_counter *cnt, uint64_t num, void *data);
 105
 106 /**
 107  * ev_signal_shared_cb:
 108  * @eloop: event loop object
 109  * @info: signalfd info for this event, see "man signalfd"
 110  * @data: user-supplied data
 111  *
 112  * This is the callback-type for shared signal events.
 113  */
 114 typedef void (*ev_signal_shared_cb)
 115         (struct ev_eloop *eloop, struct signalfd_siginfo *info, void *data);
 116
 117 /**
 118  * ev_child_data:
 119  * @pid: pid of child
 120  * @status: status of child
 121  *
 122  * This contains the payload for @ev_child_cb events. The data is simply copied
 123  * from the waitpid() system-call.
 124  */
 125 struct ev_child_data {
 126         pid_t pid;
 127         int status;
 128 };
 129
 130 /**
 131  * ev_child_cb:
 132  * @eloop: event loop object
 133  * @chld: chld pid/status payload
 134  * @data: user-supplied data
 135  *
 136  * This is the callback-type for child-reaper events.
 137  */
 138 typedef void (*ev_child_cb)
 139         (struct ev_eloop *eloop, struct ev_child_data *chld, void *data);
 140
 141 /**
 142  * ev_idle_cb:
 143  * @eloop: event loop object
 144  * @unused: Unused parameter which is required internally
 145  * @data: user-supplied data
 146  *
 147  * This is the callback-type for idle-source events.
 148  */
 149 typedef void (*ev_idle_cb) (struct ev_eloop *eloop, void *unused, void *data);
 150
 151 /**
 152  * ev_eloop_flags:
 153  * @EV_READABLE: file-descriptor is readable
 154  * @EV_WRITEABLE: file-desciprotr is writeable
 155  * @EV_HUP: Hang-up on file-descriptor
 156  * @EV_ERR: I/O error on file-descriptor
 157  * @EV_ET: Edge-triggered mode
 158  *
 159  * These flags are used for events on file-descriptors. You can combine them
 160  * with binary-operators like @EV_READABLE | @EV_WRITEABLE.
 161  * @EV_HUP and @EV_ERR are always raised for file-descriptors, even if not
 162  * requested explicitly.
 163  * @EV_ET enables edge-triggered mode for the operation
 164  */
 165 enum ev_eloop_flags {
 166         EV_READABLE = 0x01,
 167         EV_WRITEABLE = 0x02,
 168         EV_HUP = 0x04,
 169         EV_ERR = 0x08,
 170         EV_ET = 0x10,
 171 };
 172
 173 int ev_eloop_new(struct ev_eloop **out, ev_log_t log);
 174 void ev_eloop_ref(struct ev_eloop *loop);
 175 void ev_eloop_unref(struct ev_eloop *loop);
 176
 177 void ev_eloop_flush_fd(struct ev_eloop *loop, struct ev_fd *fd);
 178 int ev_eloop_dispatch(struct ev_eloop *loop, int timeout);
 179 int ev_eloop_run(struct ev_eloop *loop, int timeout);
 180 void ev_eloop_exit(struct ev_eloop *loop);
 181 int ev_eloop_get_fd(struct ev_eloop *loop);
 182
 183 /* eloop sources */
 184
 185 int ev_eloop_new_eloop(struct ev_eloop *loop, struct ev_eloop **out);
 186 int ev_eloop_add_eloop(struct ev_eloop *loop, struct ev_eloop *add);
 187 void ev_eloop_rm_eloop(struct ev_eloop *rm);
 188
 189 /* fd sources */
 190
 191 int ev_fd_new(struct ev_fd **out, int fd, int mask, ev_fd_cb cb, void *data,
 192               ev_log_t log);
 193 void ev_fd_ref(struct ev_fd *fd);
 194 void ev_fd_unref(struct ev_fd *fd);
 195
 196 int ev_fd_enable(struct ev_fd *fd);
 197 void ev_fd_disable(struct ev_fd *fd);
 198 bool ev_fd_is_enabled(struct ev_fd *fd);
 199 bool ev_fd_is_bound(struct ev_fd *fd);
 200 void ev_fd_set_cb_data(struct ev_fd *fd, ev_fd_cb cb, void *data);
 201 int ev_fd_update(struct ev_fd *fd, int mask);
 202
 203 int ev_eloop_new_fd(struct ev_eloop *loop, struct ev_fd **out, int rfd,
 204                         int mask, ev_fd_cb cb, void *data);
 205 int ev_eloop_add_fd(struct ev_eloop *loop, struct ev_fd *fd);
 206 void ev_eloop_rm_fd(struct ev_fd *fd);
 207
 208 /* timer sources */
 209
 210 int ev_timer_new(struct ev_timer **out, const struct itimerspec *spec,
 211                  ev_timer_cb cb, void *data, ev_log_t log);
 212 void ev_timer_ref(struct ev_timer *timer);
 213 void ev_timer_unref(struct ev_timer *timer);
 214
 215 int ev_timer_enable(struct ev_timer *timer);
 216 void ev_timer_disable(struct ev_timer *timer);
 217 bool ev_timer_is_enabled(struct ev_timer *timer);
 218 bool ev_timer_is_bound(struct ev_timer *timer);
 219 void ev_timer_set_cb_data(struct ev_timer *timer, ev_timer_cb cb, void *data);
 220 int ev_timer_update(struct ev_timer *timer, const struct itimerspec *spec);
 221 int ev_timer_drain(struct ev_timer *timer, uint64_t *expirations);
 222
 223 int ev_eloop_new_timer(struct ev_eloop *loop, struct ev_timer **out,
 224                         const struct itimerspec *spec, ev_timer_cb cb,
 225                         void *data);
 226 int ev_eloop_add_timer(struct ev_eloop *loop, struct ev_timer *timer);
 227 void ev_eloop_rm_timer(struct ev_timer *timer);
 228
 229 /* counter sources */
 230
 231 int ev_counter_new(struct ev_counter **out, ev_counter_cb, void *data,
 232                    ev_log_t log);
 233 void ev_counter_ref(struct ev_counter *cnt);
 234 void ev_counter_unref(struct ev_counter *cnt);
 235
 236 int ev_counter_enable(struct ev_counter *cnt);
 237 void ev_counter_disable(struct ev_counter *cnt);
 238 bool ev_counter_is_enabled(struct ev_counter *cnt);
 239 bool ev_counter_is_bound(struct ev_counter *cnt);
 240 void ev_counter_set_cb_data(struct ev_counter *cnt, ev_counter_cb cb,
 241                             void *data);
 242 int ev_counter_inc(struct ev_counter *cnt, uint64_t val);
 243
 244 int ev_eloop_new_counter(struct ev_eloop *eloop, struct ev_counter **out,
 245                          ev_counter_cb cb, void *data);
 246 int ev_eloop_add_counter(struct ev_eloop *eloop, struct ev_counter *cnt);
 247 void ev_eloop_rm_counter(struct ev_counter *cnt);
 248
 249 /* signal sources */
 250
 251 int ev_eloop_register_signal_cb(struct ev_eloop *loop, int signum,
 252                                 ev_signal_shared_cb cb, void *data);
 253 void ev_eloop_unregister_signal_cb(struct ev_eloop *loop, int signum,
 254                                         ev_signal_shared_cb cb, void *data);
 255
 256 /* child reaper sources */
 257
 258 int ev_eloop_register_child_cb(struct ev_eloop *loop, ev_child_cb cb,
 259                                void *data);
 260 void ev_eloop_unregister_child_cb(struct ev_eloop *loop, ev_child_cb cb,
 261                                   void *data);
 262
 263 /* idle sources */
 264
 265 enum ev_idle_flags {
 266         EV_NORMAL       = 0x00,
 267         EV_ONESHOT      = 0x01,
 268         EV_SINGLE       = 0x02,
 269         EV_IDLE_ALL     = EV_ONESHOT | EV_SINGLE,
 270 };
 271
 272 int ev_eloop_register_idle_cb(struct ev_eloop *eloop, ev_idle_cb cb,
 273                               void *data, unsigned int flags);
 274 void ev_eloop_unregister_idle_cb(struct ev_eloop *eloop, ev_idle_cb cb,
 275                                  void *data, unsigned int flags);
 276
 277 /* pre dispatch callbacks */
 278
 279 int ev_eloop_register_pre_cb(struct ev_eloop *eloop, ev_idle_cb cb,
 280                              void *data);
 281 void ev_eloop_unregister_pre_cb(struct ev_eloop *eloop, ev_idle_cb cb,
 282                                 void *data);
 283
 284 /* post dispatch callbacks */
 285
 286 int ev_eloop_register_post_cb(struct ev_eloop *eloop, ev_idle_cb cb,
 287                               void *data);
 288 void ev_eloop_unregister_post_cb(struct ev_eloop *eloop, ev_idle_cb cb,
 289                                  void *data);
 290
 291 #endif /* EV_ELOOP_H */