ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.276 by root, Tue Dec 29 13:11:00 2009 UTC vs.
Revision 1.278 by root, Thu Dec 31 06:59:47 2009 UTC

… …
370When this flag is specified, then libev will not attempt to use the 370When this flag is specified, then libev will not attempt to use the
371I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and 371I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
372testing, this flag can be useful to conserve inotify file descriptors, as 372testing, this flag can be useful to conserve inotify file descriptors, as
373otherwise each loop using C<ev_stat> watchers consumes one inotify handle. 373otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
374 374
375=item C<EVFLAG_NOSIGFD> 375=item C<EVFLAG_SIGNALFD>
376 376
377When this flag is specified, then libev will not attempt to use the 377When this flag is specified, then libev will attempt to use the
378I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This is 378I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
379probably only useful to work around any bugs in libev. Consequently, this 379delivers signals synchronously, which makes it both faster and might make
380flag might go away once the signalfd functionality is considered stable, 380it possible to get the queued signal data. It can also simplify signal
381so it's useful mostly in environment variables and not in program code. 381handling with threads, as long as you properly block signals in your
382threads that are not interested in handling them.
383
384Signalfd will not be used by default as this changes your signal mask, and
385there are a lot of shoddy libraries and programs (glib's threadpool for
386example) that can't properly initialise their signal masks.
382 387
383=item C<EVBACKEND_SELECT> (value 1, portable select backend) 388=item C<EVBACKEND_SELECT> (value 1, portable select backend)
384 389
385This is your standard select(2) backend. Not I<completely> standard, as 390This is your standard select(2) backend. Not I<completely> standard, as
386libev tries to roll its own fd_set with no limits on the number of fds, 391libev tries to roll its own fd_set with no limits on the number of fds,
… …
2132C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should 2137C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2133not be unduly interrupted. If you have a problem with system calls getting 2138not be unduly interrupted. If you have a problem with system calls getting
2134interrupted by signals you can block all signals in an C<ev_check> watcher 2139interrupted by signals you can block all signals in an C<ev_check> watcher
2135and unblock them in an C<ev_prepare> watcher. 2140and unblock them in an C<ev_prepare> watcher.
2136 2141
2137=head3 The special problem of inheritance over execve 2142=head3 The special problem of inheritance over fork/execve/pthread_create
2138 2143
2139Both the signal mask (C<sigprocmask>) and the signal disposition 2144Both the signal mask (C<sigprocmask>) and the signal disposition
2140(C<sigaction>) are unspecified after starting a signal watcher (and after 2145(C<sigaction>) are unspecified after starting a signal watcher (and after
2141stopping it again), that is, libev might or might not block the signal, 2146stopping it again), that is, libev might or might not block the signal,
2142and might or might not set or restore the installed signal handler. 2147and might or might not set or restore the installed signal handler.
… …
2152 2157
2153The simplest way to ensure that the signal mask is reset in the child is 2158The simplest way to ensure that the signal mask is reset in the child is
2154to install a fork handler with C<pthread_atfork> that resets it. That will 2159to install a fork handler with C<pthread_atfork> that resets it. That will
2155catch fork calls done by libraries (such as the libc) as well. 2160catch fork calls done by libraries (such as the libc) as well.
2156 2161
2157In current versions of libev, you can also ensure that the signal mask is 2162In current versions of libev, the signal will not be blocked indefinitely
2158not blocking any signals (except temporarily, so thread users watch out) 2163unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2159by specifying the C<EVFLAG_NOSIGFD> when creating the event loop. This 2164the window of opportunity for problems, it will not go away, as libev
2160is not guaranteed for future versions, however. 2165I<has> to modify the signal mask, at least temporarily.
2166
2167So I can't stress this enough: I<If you do not reset your signal mask when
2168you expect it to be empty, you have a race condition in your code>. This
2169is not a libev-specific thing, this is true for most event libraries.
2161 2170
2162=head3 Watcher-Specific Functions and Data Members 2171=head3 Watcher-Specific Functions and Data Members
2163 2172
2164=over 4 2173=over 4
2165 2174

Diff Legend

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