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

Comparing libev/ev.pod (file contents):
Revision 1.275 by root, Sat Dec 26 09:21:54 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,
… …
792 797
793Ref/unref can be used to add or remove a reference count on the event 798Ref/unref can be used to add or remove a reference count on the event
794loop: Every watcher keeps one reference, and as long as the reference 799loop: Every watcher keeps one reference, and as long as the reference
795count is nonzero, C<ev_loop> will not return on its own. 800count is nonzero, C<ev_loop> will not return on its own.
796 801
797If you have a watcher you never unregister that should not keep C<ev_loop> 802This is useful when you have a watcher that you never intend to
798from returning, call ev_unref() after starting, and ev_ref() before 803unregister, but that nevertheless should not keep C<ev_loop> from
804returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
799stopping it. 805before stopping it.
800 806
801As an example, libev itself uses this for its internal signal pipe: It 807As an example, libev itself uses this for its internal signal pipe: It
802is not visible to the libev user and should not keep C<ev_loop> from 808is not visible to the libev user and should not keep C<ev_loop> from
803exiting if no event watchers registered by it are active. It is also an 809exiting if no event watchers registered by it are active. It is also an
804excellent way to do this for generic recurring timers or from within 810excellent way to do this for generic recurring timers or from within
… …
2131C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should 2137C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2132not 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
2133interrupted 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
2134and unblock them in an C<ev_prepare> watcher. 2140and unblock them in an C<ev_prepare> watcher.
2135 2141
2136=head3 The special problem of inheritance over execve 2142=head3 The special problem of inheritance over fork/execve/pthread_create
2137 2143
2138Both the signal mask (C<sigprocmask>) and the signal disposition 2144Both the signal mask (C<sigprocmask>) and the signal disposition
2139(C<sigaction>) are unspecified after starting a signal watcher (and after 2145(C<sigaction>) are unspecified after starting a signal watcher (and after
2140stopping 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,
2141and might or might not set or restore the installed signal handler. 2147and might or might not set or restore the installed signal handler.
… …
2151 2157
2152The 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
2153to 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
2154catch fork calls done by libraries (such as the libc) as well. 2160catch fork calls done by libraries (such as the libc) as well.
2155 2161
2156In 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
2157not blocking any signals (except temporarily, so thread users watch out) 2163unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2158by specifying the C<EVFLAG_NOSIGFD> when creating the event loop. This 2164the window of opportunity for problems, it will not go away, as libev
2159is 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.
2160 2170
2161=head3 Watcher-Specific Functions and Data Members 2171=head3 Watcher-Specific Functions and Data Members
2162 2172
2163=over 4 2173=over 4
2164 2174

Diff Legend

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