[ViewVC] Diff of: cvs/libev/ev.3

Comparing libev/ev.3 (file contents):
Revision 1.79 by root, Fri Jul 17 14:43:38 2009 UTC vs.
Revision 1.80 by root, Sun Aug 9 12:34:46 2009 UTC

 .\}
 .rm #[ #] #H #V #F C
 .\" ========================================================================
 .\"
 .IX Title "LIBEV 3"
-.TH LIBEV 3 "2009-07-15" "libev-3.7" "libev - high performance full featured event loop"
+.TH LIBEV 3 "2009-07-27" "libev-3.8" "libev - high performance full featured event loop"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
 .nh
 .SH "NAME"
 .SS "\s-1FEATURES\s0"
 .IX Subsection "FEATURES"
 Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the
 BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms
 for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface
-(for \f(CW\*(C`ev_stat\*(C'\fR), relative timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers
+(for \f(CW\*(C`ev_stat\*(C'\fR), Linux eventfd/signalfd (for faster and cleaner
-with customised rescheduling (\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals
+inter-thread wakeup (\f(CW\*(C`ev_async\*(C'\fR)/signal handling (\f(CW\*(C`ev_signal\*(C'\fR)) relative
-(\f(CW\*(C`ev_signal\*(C'\fR), process status change events (\f(CW\*(C`ev_child\*(C'\fR), and event
+timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers with customised rescheduling
-watchers dealing with the event loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR,
+(\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals (\f(CW\*(C`ev_signal\*(C'\fR), process status
-\&\f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and \f(CW\*(C`ev_check\*(C'\fR watchers) as well as
+change events (\f(CW\*(C`ev_child\*(C'\fR), and event watchers dealing with the event
-file watchers (\f(CW\*(C`ev_stat\*(C'\fR) and even limited support for fork events
+loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and
-(\f(CW\*(C`ev_fork\*(C'\fR).
+\&\f(CW\*(C`ev_check\*(C'\fR watchers) as well as file watchers (\f(CW\*(C`ev_stat\*(C'\fR) and even
+limited support for fork events (\f(CW\*(C`ev_fork\*(C'\fR).
 .PP
 It also is quite fast (see this
 <benchmark> comparing it to libevent
 for example).
 .SS "\s-1CONVENTIONS\s0"
 forget about forgetting to tell libev about forking) when you use this
 flag.
 .Sp
 This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR
 environment variable.
+.ie n .IP """EVFLAG_NOINOTIFY""" 4
+.el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4
+.IX Item "EVFLAG_NOINOTIFY"
+When this flag is specified, then libev will not attempt to use the
+\&\fIinotify\fR \s-1API\s0 for it's \f(CW\*(C`ev_stat\*(C'\fR watchers. Apart from debugging and
+testing, this flag can be useful to conserve inotify file descriptors, as
+otherwise each loop using \f(CW\*(C`ev_stat\*(C'\fR watchers consumes one inotify handle.
+.ie n .IP """EVFLAG_NOSIGNALFD""" 4
+.el .IP "\f(CWEVFLAG_NOSIGNALFD\fR" 4
+.IX Item "EVFLAG_NOSIGNALFD"
+When this flag is specified, then libev will not attempt to use the
+\&\fIsignalfd\fR \s-1API\s0 for it's \f(CW\*(C`ev_signal\*(C'\fR (and \f(CW\*(C`ev_child\*(C'\fR) watchers. This is
+probably only useful to work around any bugs in libev. Consequently, this
+flag might go away once the signalfd functionality is considered stable,
+so it's useful mostly in environment variables and not in program code.
 .ie n .IP """EVBACKEND_SELECT""  (value 1, portable select backend)" 4
 .el .IP "\f(CWEVBACKEND_SELECT\fR  (value 1, portable select backend)" 4
 .IX Item "EVBACKEND_SELECT  (value 1, portable select backend)"
 This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as
 libev tries to roll its own fd_set with no limits on the number of fds,
 .Sp
 It is definitely not recommended to use this flag.
 .RE
 .RS 4
 .Sp
-If one or more of these are or'ed into the flags value, then only these
+If one or more of the backend flags are or'ed into the flags value,
-backends will be tried (in the reverse order as listed here). If none are
+then only these backends will be tried (in the reverse order as listed
-specified, all backends in \f(CW\*(C`ev_recommended_backends ()\*(C'\fR will be tried.
+here). If none are specified, all backends in \f(CW\*(C`ev_recommended_backends
+()\*(C'\fR will be tried.
 .Sp
 Example: This is the most typical usage.
 .Sp
 .Vb 2
 \&   if (!ev_default_loop (0))
 Signal watchers will trigger an event when the process receives a specific
 signal one or more times. Even though signals are very asynchronous, libev
 will try it's best to deliver signals synchronously, i.e. as part of the
 normal event processing, like any other event.
 .PP
-If you want signals asynchronously, just use \f(CW\*(C`sigaction\*(C'\fR as you would
+If you want signals to be delivered truly asynchronously, just use
-do without libev and forget about sharing the signal. You can even use
+\&\f(CW\*(C`sigaction\*(C'\fR as you would do without libev and forget about sharing
-\&\f(CW\*(C`ev_async\*(C'\fR from a signal handler to synchronously wake up an event loop.
+the signal. You can even use \f(CW\*(C`ev_async\*(C'\fR from a signal handler to
+synchronously wake up an event loop.
 .PP
-You can configure as many watchers as you like per signal. Only when the
+You can configure as many watchers as you like for the same signal, but
+only within the same loop, i.e. you can watch for \f(CW\*(C`SIGINT\*(C'\fR in your
+default loop and for \f(CW\*(C`SIGIO\*(C'\fR in another loop, but you cannot watch for
+\&\f(CW\*(C`SIGINT\*(C'\fR in both the default loop and another loop at the same time. At
+the moment, \f(CW\*(C`SIGCHLD\*(C'\fR is permanently tied to the default loop.
+.PP
-first watcher gets started will libev actually register a signal handler
+When the first watcher gets started will libev actually register something
 with the kernel (thus it coexists with your own signal handlers as long as
-you don't register any with libev for the same signal). Similarly, when
+you don't register any with libev for the same signal).
-the last signal watcher for a signal is stopped, libev will reset the
+.PP
-signal handler to \s-1SIG_DFL\s0 (regardless of what it was set to before).
+Both the signal mask state (\f(CW\*(C`sigprocmask\*(C'\fR) and the signal handler state
+(\f(CW\*(C`sigaction\*(C'\fR) are unspecified after starting a signal watcher (and after
+sotpping it again), that is, libev might or might not block the signal,
+and might or might not set or restore the installed signal handler.
 .PP
 If possible and supported, libev will install its handlers with
-\&\f(CW\*(C`SA_RESTART\*(C'\fR behaviour enabled, so system calls should not be unduly
+\&\f(CW\*(C`SA_RESTART\*(C'\fR (or equivalent) behaviour enabled, so system calls should
-interrupted. If you have a problem with system calls getting interrupted by
+not be unduly interrupted. If you have a problem with system calls getting
-signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher and unblock
+interrupted by signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher
-them in an \f(CW\*(C`ev_prepare\*(C'\fR watcher.
+and unblock them in an \f(CW\*(C`ev_prepare\*(C'\fR watcher.
 .PP
 \fIWatcher-Specific Functions and Data Members\fR
 .IX Subsection "Watcher-Specific Functions and Data Members"
 .IP "ev_signal_init (ev_signal *, callback, int signum)" 4
 .IX Item "ev_signal_init (ev_signal *, callback, int signum)"
 .PP
 \fIProcess Interaction\fR
 .IX Subsection "Process Interaction"
 .PP
 Libev grabs \f(CW\*(C`SIGCHLD\*(C'\fR as soon as the default event loop is
-initialised. This is necessary to guarantee proper behaviour even if
+initialised. This is necessary to guarantee proper behaviour even if the
-the first child watcher is started after the child exits. The occurrence
+first child watcher is started after the child exits. The occurrence
 of \f(CW\*(C`SIGCHLD\*(C'\fR is recorded asynchronously, but child reaping is done
 synchronously as part of the event loop processing. Libev always reaps all
 children, even ones not watched.
 .PP
 \fIOverriding the Built-In Processing\fR
 .IX Subsection "Stopping the Child Watcher"
 .PP
 Currently, the child watcher never gets stopped, even when the
 child terminates, so normally one needs to stop the watcher in the
 callback. Future versions of libev might stop the watcher automatically
-when a child exit is detected.
+when a child exit is detected (calling \f(CW\*(C`ev_child_stop\*(C'\fR twice is not a
+problem).
 .PP
 \fIWatcher-Specific Functions and Data Members\fR
 .IX Subsection "Watcher-Specific Functions and Data Members"
 .IP "ev_child_init (ev_child *, callback, int pid, int trace)" 4
 .IX Item "ev_child_init (ev_child *, callback, int pid, int trace)"
 be found at <http://proj.llucax.com.ar/wiki/evd>.
 .IP "Ocaml" 4
 .IX Item "Ocaml"
 Erkki Seppala has written Ocaml bindings for libev, to be found at
 <http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>.
+.IP "Lua" 4
+.IX Item "Lua"
+Brian Maher has written a partial interface to libev
+for lua (only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at
+<http://github.com/brimworks/lua\-ev>.
 .SH "MACRO MAGIC"
 .IX Header "MACRO MAGIC"
 Libev can be compiled with a variety of options, the most fundamental
 of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most)
 functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument.
 keeps libev from including \fIconfig.h\fR, and it also defines dummy
 implementations for some libevent functions (such as logging, which is not
 supported). It will also not define any of the structs usually found in
 \&\fIevent.h\fR that are not directly supported by the libev core alone.
 .Sp
-In stanbdalone mode, libev will still try to automatically deduce the
+In standalone mode, libev will still try to automatically deduce the
 configuration, but has to be more conservative.
 .IP "\s-1EV_USE_MONOTONIC\s0" 4
 .IX Item "EV_USE_MONOTONIC"
 If defined to be \f(CW1\fR, libev will try to detect the availability of the
 monotonic clock option at both compile time and runtime. Otherwise no
 .Sp
 Defining \f(CW\*(C`EV_MINIMAL\*(C'\fR to \f(CW2\fR will additionally reduce the core \s-1API\s0 to
 provide a bare-bones event library. See \f(CW\*(C`ev.h\*(C'\fR for details on what parts
 of the \s-1API\s0 are still available, and do not complain if this subset changes
 over time.
+.IP "\s-1EV_NSIG\s0" 4
+.IX Item "EV_NSIG"
+The highest supported signal number, +1 (or, the number of
+signals): Normally, libev tries to deduce the maximum number of signals
+automatically, but sometimes this fails, in which case it can be
+specified. Also, using a lower number than detected (\f(CW32\fR should be
+good for about any system in existance) can save some memory, as libev
+statically allocates some 12\-24 bytes per signal number.
 .IP "\s-1EV_PID_HASHSIZE\s0" 4
 .IX Item "EV_PID_HASHSIZE"
 \&\f(CW\*(C`ev_child\*(C'\fR watchers use a small hash table to distribute workload by
 pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more
 than enough. If you need to manage thousands of children you might want to

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing libev/ev.3 (file contents): Revision 1.79 by root, Fri Jul 17 14:43:38 2009 UTC vs. Revision 1.80 by root, Sun Aug 9 12:34:46 2009 UTC

Diff Legend

Comparing libev/ev.3 (file contents):
Revision 1.79 by root, Fri Jul 17 14:43:38 2009 UTC vs.
Revision 1.80 by root, Sun Aug 9 12:34:46 2009 UTC