lib/poll-loop.h

   1 /*
   2  * Copyright (c) 2008, 2009, 2010, 2011, 2013 Nicira, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at:
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /* High-level wrapper around the "poll" system call.
  18  *
  19  * The intended usage is for each thread'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  *
  28  * Thread-safety
  29  * =============
  30  *
  31  * The poll set is per-thread, so all functions in this module are thread-safe.
  32  */
  33 #ifndef POLL_LOOP_H
  34 #define POLL_LOOP_H 1
  35
  36 #include <poll.h>
  37 #include "util.h"
  38
  39 #ifdef  __cplusplus
  40 extern "C" {
  41 #endif
  42
  43
  44 /* Schedule events to wake up the following poll_block().
  45  *
  46  * The poll_loop logs the 'where' argument to each function at "debug" level
  47  * when an event causes a wakeup.  Each of these ways to schedule an event has
  48  * a function and a macro wrapper.  The macro version automatically supplies
  49  * the source code location of the caller.  The function version allows the
  50  * caller to supply a location explicitly, which is useful if the caller's own
  51  * caller would be more useful in log output.  See timer_wait_at() for an
  52  * example. */
  53 void poll_fd_wait_at(int fd, short int events, const char *where);
  54 #define poll_fd_wait(fd, events) poll_fd_wait_at(fd, events, SOURCE_LOCATOR)
  55
  56 #ifdef _WIN32
  57 #define poll_wevent_wait(wevent) poll_wevent_wait_at(wevent, SOURCE_LOCATOR)
  58 #endif /* _WIN32 */
  59
  60 void poll_timer_wait_at(long long int msec, const char *where);
  61 #define poll_timer_wait(msec) poll_timer_wait_at(msec, SOURCE_LOCATOR)
  62
  63 void poll_timer_wait_until_at(long long int msec, const char *where);
  64 #define poll_timer_wait_until(msec)             \
  65     poll_timer_wait_until_at(msec, SOURCE_LOCATOR)
  66
  67 void poll_immediate_wake_at(const char *where);
  68 #define poll_immediate_wake() poll_immediate_wake_at(SOURCE_LOCATOR)
  69
  70 /* Wait until an event occurs. */
  71 void poll_block(void);
  72
  73 #ifdef  __cplusplus
  74 }
  75 #endif
  76
  77 #endif /* poll-loop.h */