From: Nick Mathewson Date: Sat, 17 Nov 2007 22:21:33 +0000 (+0000) Subject: r14930@tombo: nickm | 2007-11-17 17:01:14 -0500 X-Git-Tag: release-2.0.1-alpha~497 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=70248ca8ad0dd426798d1e11328970b1f537e505;p=libevent 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 2fdb0788..7429c476 100644 --- 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 328f632a..d5717f22 100644 --- 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 7a73cd10..4685e936 100644 --- 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.