lib/poll-loop.h

   1 /*
   2  * Copyright (c) 2008 Nicira Networks.
   3  *
   4  * Permission to use, copy, modify, and/or distribute this software for any
   5  * purpose with or without fee is hereby granted, provided that the above
   6  * copyright notice and this permission notice appear in all copies.
   7  *
   8  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15  */
  16
  17 /* High-level wrapper around the "poll" system call.
  18  *
  19  * Intended usage is for the program's main loop to go about its business
  20  * servicing whatever events it needs to.  Then, when it runs out of immediate
  21  * tasks, it calls each subordinate module's "wait" function, which in turn
  22  * calls one (or more) of the functions poll_fd_wait(), poll_immediate_wake(),
  23  * and poll_timer_wait() to register to be awakened when the appropriate event
  24  * occurs.  Then the main loop calls poll_block(), which blocks until one of
  25  * the registered events happens.
  26  *
  27  * There is also some support for autonomous subroutines that are executed by
  28  * poll_block() when a file descriptor becomes ready.  To prevent these
  29  * routines from starving if events are continuously ready, the application
  30  * should bound the amount of work it does between poll_block() calls. */
  31
  32 #ifndef POLL_LOOP_H
  33 #define POLL_LOOP_H 1
  34
  35 #include <poll.h>
  36
  37 struct poll_waiter;
  38
  39 /* Schedule events to wake up the following poll_block(). */
  40 struct poll_waiter *poll_fd_wait(int fd, short int events);
  41 void poll_timer_wait(int msec);
  42 void poll_immediate_wake(void);
  43
  44 /* Wait until an event occurs. */
  45 void poll_block(void);
  46
  47 /* Autonomous function callbacks. */
  48 typedef void poll_fd_func(int fd, short int revents, void *aux);
  49 struct poll_waiter *poll_fd_callback(int fd, short int events,
  50                                      poll_fd_func *, void *aux);
  51
  52 /* Cancel a file descriptor callback or event. */
  53 void poll_cancel(struct poll_waiter *);
  54
  55 #endif /* poll-loop.h */