Break passive vconns out into separate pvconn routines and data structures.

[sliver-openvswitch.git] / include / poll-loop.h

diff --git a/include/poll-loop.h b/include/poll-loop.h
index 6ef5d9b..c56bc06 100644 (file)
--- a/include/poll-loop.h
+++ b/include/poll-loop.h
@@ -31,20 +31,42 @@
  * derivatives without specific, written prior permission.
  */
 
+/* High-level wrapper around the "poll" system call.
+ *
+ * Intended usage is for the program's main loop to go about its business
+ * servicing whatever events it needs to.  Then, when it runs out of immediate
+ * tasks, it calls each subordinate module's "wait" function, which in turn
+ * calls one (or more) of the functions poll_fd_wait(), poll_immediate_wake(),
+ * and poll_timer_wait() to register to be awakened when the appropriate event
+ * occurs.  Then the main loop calls poll_block(), which blocks until one of
+ * the registered events happens.
+ *
+ * There is also some support for autonomous subroutines that are executed by
+ * poll_block() when a file descriptor becomes ready.  To prevent these
+ * routines from starving if events are continously ready, the application
+ * should bound the amount of work it does between poll_block() calls. */
+
 #ifndef POLL_LOOP_H
 #define POLL_LOOP_H 1
 
 #include <poll.h>
 
-typedef void poll_fd_func(int fd, short int revents, void *aux);
+struct poll_waiter;
+
+/* Schedule events to wake up the following poll_block(). */
+struct poll_waiter *poll_fd_wait(int fd, short int events);
+void poll_timer_wait(int msec);
+void poll_immediate_wake(void);
+
+/* Wait until an event occurs. */
+void poll_block(void);
 
+/* Autonomous function callbacks. */
+typedef void poll_fd_func(int fd, short int revents, void *aux);
 struct poll_waiter *poll_fd_callback(int fd, short int events,
                                      poll_fd_func *, void *aux);
-struct poll_waiter *poll_fd_wait(int fd, short int events, short int *revents);
-void poll_cancel(struct poll_waiter *);
 
-void poll_immediate_wake(void);
-void poll_timer_wait(int msec);
-void poll_block(void);
+/* Cancel a file descriptor callback or event. */
+void poll_cancel(struct poll_waiter *);
 
 #endif /* poll-loop.h */