From: Nick Mathewson Date: Thu, 18 Oct 2007 17:49:52 +0000 (+0000) Subject: r15922@catbus: nickm | 2007-10-18 13:48:46 -0400 X-Git-Tag: release-2.0.1-alpha~545 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=ccdc59905b36686d3331607362197e08f1c8b0ae;p=libevent r15922@catbus: nickm | 2007-10-18 13:48:46 -0400 Patch to event.3 from Christopher Lane. svn:r463 --- diff --git a/event.3 b/event.3 index 565aaa9e..cff472bd 100644 --- a/event.3 +++ b/event.3 @@ -208,51 +208,6 @@ In order to process events, an application needs to call This function only returns on error, and should replace the event core of the application program. .Pp -In order to avoid races in signal handlers, the -.Nm event -API provides two variables: -.Va event_sigcb -and -.Va event_gotsig . -A signal handler -sets -.Va event_gotsig -to indicate that a signal has been received. -The application sets -.Va event_sigcb -to a callback function. -After the signal handler sets -.Va event_gotsig , -.Nm event_dispatch -will execute the callback function to process received signals. -The callback returns 1 when no events are registered any more. -It can return \-1 to indicate an error to the -.Nm event -library, causing -.Fn event_dispatch -to terminate with -.Va errno -set to -.Er EINTR . -.Pp -The -.Nm event_loop -function provides an interface for single pass execution of pending -events. -The flags -.Va EVLOOP_ONCE -and -.Va EVLOOP_NONBLOCK -are recognized. -The -.Nm event_loopexit -function allows the loop to be terminated after some amount of time -has passed. -The parameter indicates the time after which the loop should terminate. -.Pp -It is the responsibility of the caller to provide these functions with -pre-allocated event structures. -.Pp The function .Fn event_set prepares the event structure @@ -291,6 +246,11 @@ the type of event which will be either .Va EV_READ , or .Va EV_WRITE . +Additionally, an event which has registered interest in more than one of the +preceeding events, via bitwise-OR to +.Fn event_set , +can provide its callback function with a bitwise-OR of more than one triggered +event. The additional flag .Va EV_PERSIST makes an @@ -356,6 +316,59 @@ will cancel the event in the argument If the event has already executed or has never been added the call will have no effect. .Pp +The functions +.Fn evtimer_set , +.Fn evtimer_add , +.Fn evtimer_del , +.Fn evtimer_initialized , +and +.Fn evtimer_pending +are abbreviations for common situations where only a timeout is required. +The file descriptor passed will be \-1, and the event type will be +.Va EV_TIMEOUT . +.Pp +The functions +.Fn signal_set , +.Fn signal_add , +.Fn signal_del , +.Fn signal_initialized , +and +.Fn signal_pending +are abbreviations. +The event type will be a persistent +.Va EV_SIGNAL . +That means +.Fn signal_set +adds +.Va EV_PERSIST . +.Pp +In order to avoid races in signal handlers, the +.Nm event +API provides two variables: +.Va event_sigcb +and +.Va event_gotsig . +A signal handler +sets +.Va event_gotsig +to indicate that a signal has been received. +The application sets +.Va event_sigcb +to a callback function. +After the signal handler sets +.Va event_gotsig , +.Nm event_dispatch +will execute the callback function to process received signals. +The callback returns 1 when no events are registered any more. +It can return \-1 to indicate an error to the +.Nm event +library, causing +.Fn event_dispatch +to terminate with +.Va errno +set to +.Er EINTR . +.Pp The function .Fn event_once is similar to @@ -388,45 +401,24 @@ The .Fn event_initialized macro can be used to check if an event has been initialized. .Pp -The functions -.Fn evtimer_set , -.Fn evtimer_add , -.Fn evtimer_del , -.Fn evtimer_initialized , +The +.Nm event_loop +function provides an interface for single pass execution of pending +events. +The flags +.Va EVLOOP_ONCE and -.Fn evtimer_pending -are abbreviations for common situations where only a timeout is required. -The file descriptor passed will be \-1, and the event type will be -.Va EV_TIMEOUT . +.Va EVLOOP_NONBLOCK +are recognized. +The +.Nm event_loopexit +function allows the loop to be terminated after some amount of time +has passed. +The parameter indicates the time after which the loop should terminate. .Pp -The functions -.Fn signal_set , -.Fn signal_add , -.Fn signal_del , -.Fn signal_initialized , -and -.Fn signal_pending -are abbreviations. -The event type will be a persistent -.Va EV_SIGNAL . -That means -.Fn signal_set -adds -.Va EV_PERSIST . +It is the responsibility of the caller to provide these functions with +pre-allocated event structures. .Pp -It is possible to disable support for -.Va epoll , kqueue , devpoll , poll -or -.Va select -by setting the environment variable -.Va EVENT_NOEPOLL , EVENT_NOKQUEUE , EVENT_NODEVPOLL , EVENT_NOPOLL -or -.Va EVENT_NOSELECT , -respectively. -By setting the environment variable -.Va EVENT_SHOW_METHOD , -.Nm libevent -displays the kernel notification method that it uses. .Sh EVENT PRIORITIES By default .Nm libevent @@ -562,6 +554,20 @@ This section does not document all the possible function calls; please check .Va event.h for the public interfaces. +.Sh ADDITIONAL NOTES +It is possible to disable support for +.Va epoll , kqueue , devpoll , poll +or +.Va select +by setting the environment variable +.Va EVENT_NOEPOLL , EVENT_NOKQUEUE , EVENT_NODEVPOLL , EVENT_NOPOLL +or +.Va EVENT_NOSELECT , +respectively. +By setting the environment variable +.Va EVENT_SHOW_METHOD , +.Nm libevent +displays the kernel notification method that it uses. .Sh RETURN VALUES Upon successful completion .Fn event_add