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

Comparing libev/ev.pod (file contents):
Revision 1.275 by root, Sat Dec 26 09:21:54 2009 UTC vs.
Revision 1.281 by root, Tue Mar 9 08:46:17 2010 UTC

 When this flag is specified, then libev will not attempt to use the
 I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
 testing, this flag can be useful to conserve inotify file descriptors, as
 otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
-=item C<EVFLAG_NOSIGFD>
+=item C<EVFLAG_SIGNALFD>
-When this flag is specified, then libev will not attempt to use the
+When this flag is specified, then libev will attempt to use the
-I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This is
+I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
-probably only useful to work around any bugs in libev. Consequently, this
+delivers signals synchronously, which makes it both faster and might make
-flag might go away once the signalfd functionality is considered stable,
+it possible to get the queued signal data. It can also simplify signal
-so it's useful mostly in environment variables and not in program code.
+handling with threads, as long as you properly block signals in your
+threads that are not interested in handling them.
+Signalfd will not be used by default as this changes your signal mask, and
+there are a lot of shoddy libraries and programs (glib's threadpool for
+example) that can't properly initialise their signal masks.
 =item C<EVBACKEND_SELECT>  (value 1, portable select backend)
 This is your standard select(2) backend. Not I<completely> standard, as
 libev tries to roll its own fd_set with no limits on the number of fds,
 Ref/unref can be used to add or remove a reference count on the event
 loop: Every watcher keeps one reference, and as long as the reference
 count is nonzero, C<ev_loop> will not return on its own.
-If you have a watcher you never unregister that should not keep C<ev_loop>
+This is useful when you have a watcher that you never intend to
-from returning, call ev_unref() after starting, and ev_ref() before
+unregister, but that nevertheless should not keep C<ev_loop> from
+returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
-stopping it.
+before stopping it.
 As an example, libev itself uses this for its internal signal pipe: It
 is not visible to the libev user and should not keep C<ev_loop> from
 exiting if no event watchers registered by it are active. It is also an
 excellent way to do this for generic recurring timers or from within
 Returns the remaining time until a timer fires. If the timer is active,
 then this time is relative to the current event loop time, otherwise it's
 the timeout value currently configured.
 That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
-C<5>. When the timer is started and one second passes, C<ev_timer_remain>
+C<5>. When the timer is started and one second passes, C<ev_timer_remaining>
 will return C<4>. When the timer expires and is restarted, it will return
 roughly C<7> (likely slightly less as callback invocation takes some time,
 too), and so on.
 =item ev_tstamp repeat [read-write]
 C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
 not be unduly interrupted. If you have a problem with system calls getting
 interrupted by signals you can block all signals in an C<ev_check> watcher
 and unblock them in an C<ev_prepare> watcher.
-=head3 The special problem of inheritance over execve
+=head3 The special problem of inheritance over fork/execve/pthread_create
 Both the signal mask (C<sigprocmask>) and the signal disposition
 (C<sigaction>) are unspecified after starting a signal watcher (and after
 stopping it again), that is, libev might or might not block the signal,
 and might or might not set or restore the installed signal handler.
 The simplest way to ensure that the signal mask is reset in the child is
 to install a fork handler with C<pthread_atfork> that resets it. That will
 catch fork calls done by libraries (such as the libc) as well.
-In current versions of libev, you can also ensure that the signal mask is
+In current versions of libev, the signal will not be blocked indefinitely
-not blocking any signals (except temporarily, so thread users watch out)
+unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
-by specifying the C<EVFLAG_NOSIGFD> when creating the event loop. This
+the window of opportunity for problems, it will not go away, as libev
-is not guaranteed for future versions, however.
+I<has> to modify the signal mask, at least temporarily.
+So I can't stress this enough: I<If you do not reset your signal mask when
+you expect it to be empty, you have a race condition in your code>. This
+is not a libev-specific thing, this is true for most event libraries.
 =head3 Watcher-Specific Functions and Data Members
 =over 4
 Erkki Seppala has written Ocaml bindings for libev, to be found at
 L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
 =item Lua
-Brian Maher has written a partial interface to libev
+Brian Maher has written a partial interface to libev for lua (at the
-for lua (only C<ev_io> and C<ev_timer>), to be found at
+time of this writing, only C<ev_io> and C<ev_timer>), to be found at
 L<http://github.com/brimworks/lua-ev>.
 =back
    libev.m4
 =head2 PREPROCESSOR SYMBOLS/MACROS
 Libev can be configured via a variety of preprocessor symbols you have to
-define before including any of its files. The default in the absence of
+define before including (or compiling) any of its files. The default in
-autoconf is documented for every option.
+the absence of autoconf is documented for every option.
+Symbols marked with "(h)" do not change the ABI, and can have different
+values when compiling libev vs. including F<ev.h>, so it is permissible
+to redefine them before including F<ev.h> without breakign compatibility
+to a compiled library. All other symbols change the ABI, which means all
+users of libev and the libev code itself must be compiled with compatible
+settings.
 =over 4
-=item EV_STANDALONE
+=item EV_STANDALONE (h)
 Must always be C<1> if you do not use autoconf configuration, which
 keeps libev from including F<config.h>, 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
 as well as for signal and thread safety in C<ev_async> watchers.
 In the absence of this define, libev will use C<sig_atomic_t volatile>
 (from F<signal.h>), which is usually good enough on most platforms.
-=item EV_H
+=item EV_H (h)
 The name of the F<ev.h> header file used to include it. The default if
 undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
 used to virtually rename the F<ev.h> header file in case of conflicts.
-=item EV_CONFIG_H
+=item EV_CONFIG_H (h)
 If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
 F<ev.c>'s idea of where to find the F<config.h> file, similarly to
 C<EV_H>, above.
-=item EV_EVENT_H
+=item EV_EVENT_H (h)
 Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
 of how the F<event.h> header can be found, the default is C<"event.h">.
-=item EV_PROTOTYPES
+=item EV_PROTOTYPES (h)
 If defined to be C<0>, then F<ev.h> will not define any function
 prototypes, but still define all the structs and other symbols. This is
 occasionally useful if you want to provide your own wrapper functions
 around libev functions.
 Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to
 provide a bare-bones event library. See C<ev.h> for details on what parts
 of the API are still available, and do not complain if this subset changes
 over time.
+=item EV_AVOID_STDIO
+If this is set to C<1> at compiletime, then libev will avoid using stdio
+functions (printf, scanf, perror etc.). This will increase the codesize
+somewhat, but if your program doesn't otherwise depend on stdio and your
+libc allows it, this avoids linking in the stdio library which is quite
+big.
+Note that error messages might become less precise when this option is
+enabled.
 =item EV_NSIG
 The highest supported signal number, +1 (or, the number of
 signals): Normally, libev tries to deduce the maximum number of signals

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.275 by root, Sat Dec 26 09:21:54 2009 UTC vs. Revision 1.281 by root, Tue Mar 9 08:46:17 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.275 by root, Sat Dec 26 09:21:54 2009 UTC vs.
Revision 1.281 by root, Tue Mar 9 08:46:17 2010 UTC