It's really difficult to have a diff explain manpage changes due to
the nature of ROFF markup, etc.
Positional changes:
Moved the opening paragraphs about signal specific issues to right
under the signal_add(), signal_set() section, since they're related.
Moved the opening paragraphs about event_loop(), etc. to the bottom of
the DESCRIPTION section since they're more ancillary than immediately
pertinent.
Moved the parts about manipulating underlying handlers (EVENT_METHOD,
etc.) to the bottom, right before "RETURN VALUES" w/ the new heading
"ADDITIONAL NOTES".
Wording changes:
Before:
The function fn will be called with the file descriptor that triggered
the event and the type of event which will be either EV_TIMEOUT,
EV_SIGNAL, EV_READ, or EV_WRITE. The additional flag EV_PERSIST makes
an event_add() persistent until event_del() has been called.
After:
The function fn will be called with the file descriptor that triggered
the event and the type of event which will be either EV_TIMEOUT,
EV_SIGNAL, EV_READ, or EV_WRITE. Additionally, an event which has
registered interest in more than one of the preceeding events, via
bitwise-OR to event_set(), can provide it's callback function with a
bitwise-OR of more than one triggered event. The additional flag
EV_PERSIST makes an event_add() persistent until event_del() has been
called.
Rationale for this additional wording is related to situations in which:
event_set(ev, fd, EVREAD | EV_WRITE, cb, cbd);
can result in cb() being called with event == 6 (0x2 | 0x4). A perfect
example of which is non-blocking connect() w/ pending error:
$ ./ev 127.0.0.1 7
connect: Operation now in progress
ev_cb: fd == 3, event == 4
connect: Success
$ ./ev 127.0.0.1 73
connect: Operation now in progress
ev_cb: fd == 3, event == 6
connect: Connection refused
Not really a huge deal, but documenting it as perfectly legal since the
original wording implied exclusivity among event types passed to the
callback when in reality it's a mask. This will bite people who use
one function for both and then try to switch/case it.
-cl
Index: libevent/event.3
===================================================================
--- libevent/event.3 (revision 454)
+++ libevent/event.3 (working copy)
@@ -208,51 +208,6 @@
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 @@
.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 it's callback function with a bitwise-OR of more than one triggered
+event.
The additional flag
.Va EV_PERSIST
makes an
@@ -356,6 +316,59 @@
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 @@
.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 @@
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
_______________________________________________
Libevent-users mailing list
Libevent-users@monkey.org
http://monkey.org/mailman/listinfo/libevent-users
