r14930@tombo: nickm | 2007-11-17 17:01:14 -0500

 documentation fix on loopexit and elsewhere from Scott Lamb.

svn:r534

diff --git a/ChangeLog b/ChangeLog
index 2fdb07881b96ee9ab1edbbb8deabf37f828ef647..7429c476aa80b0f66ac4c1bac25e0425efb1e3ec 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -3,6 +3,7 @@ Changes in current version:
  o debug cleanups in signal.c; from Christopher Layne
  o provide event_base_new() that does not set the current_base global  
  o bufferevent_write now uses a const source argument; report from Charles Kerr
+ o improve documentation on event_base_loopexit; patch from Scott Lamb
 
 Changes in 1.4.0:
  o allow \r or \n individually to separate HTTP headers instead of the standard "\r\n"; from Charles Kerr.

diff --git a/event.3 b/event.3
index 328f632a005246b5791017f1c71ee24f473253e2..d5717f22519e02a6463a8a1bd96928be4a5e55d6 100644 (file)
--- a/event.3
+++ b/event.3
@@ -412,8 +412,13 @@ and
 are recognized.
 The
 .Nm event_loopexit
-function allows the loop to be terminated after some amount of time
-has passed.
+function exits from the event loop. The next
+.Fn event_loop
+iteration after the
+given timer expires will complete normally (handling all queued events) then
+exit without blocking for events again. Subsequent invocations of
+.Fn event_loop
+will proceed normally.
 The parameter indicates the time after which the loop should terminate.
 .Pp
 It is the responsibility of the caller to provide these functions with

diff --git a/event.h b/event.h
index 7a73cd103413397ff989c5865e4e05242af01a5f..4685e936ae33b4b0823370f3af51c4c82fc9d069 100644 (file)
--- a/event.h
+++ b/event.h
@@ -344,17 +344,18 @@ void event_set_log_callback(event_log_cb cb);
  */
 int event_base_set(struct event_base *, struct event *);
 
-/** A flag for event_loop() to indicate ... (FIXME) */
-#define EVLOOP_ONCE    0x01
-
-/** A flag for event_loop() to indicate ... (FIXME) */
-#define EVLOOP_NONBLOCK        0x02
+/**
+ event_loop() flags
+ */
+/*@{*/
+#define EVLOOP_ONCE    0x01    /**< Block at most once. */
+#define EVLOOP_NONBLOCK        0x02    /**< Do not block. */
+/*@}*/
 
 /**
-  Execute a single event.
+  Handle events.
 
-  The event_loop() function provides an interface for single pass execution of
-  pending events.
+  This is a more flexible version of event_dispatch().
 
   @param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK
   @return 0 if successful, or -1 if an error occurred
@@ -363,10 +364,9 @@ int event_base_set(struct event_base *, struct event *);
 int event_loop(int);
 
 /**
-  Execute a single event (threadsafe variant).
+  Handle events (threadsafe version).
 
-  The event_base_loop() function provides an interface for single pass
-  execution of pending events.
+  This is a more flexible version of event_base_dispatch().
 
   @param eb the event_base structure returned by event_init()
   @param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK
@@ -376,10 +376,13 @@ int event_loop(int);
 int event_base_loop(struct event_base *, int);
 
 /**
-  Execute a single event, with a timeout.
+  Exit the event loop after the specified time.
 
-  The event_loopexit() function is similar to event_loop(), but allows the
-  loop to be terminated after some amount of time has passed.
+  The next event_loop() iteration after the given timer expires will
+  complete normally (handling all queued events) then exit without
+  blocking for events again.
+
+  Subsequent invocations of event_loop() will proceed normally.
 
   @param tv the amount of time after which the loop should terminate.
   @return 0 if successful, or -1 if an error occurred
@@ -389,7 +392,13 @@ int event_loopexit(struct timeval *);
 
 
 /**
-  Execute a single event, with a timeout (threadsafe variant).
+  Exit the event loop after the specified time (threadsafe variant).
+
+  The next event_base_loop() iteration after the given timer expires will
+  complete normally (handling all queued events) then exit without
+  blocking for events again.
+
+  Subsequent invocations of event_base_loop() will proceed normally.
 
   @param eb the event_base structure returned by event_init()
   @param tv the amount of time after which the loop should terminate.