| … | |
… | |
| 370 | When this flag is specified, then libev will not attempt to use the |
370 | When this flag is specified, then libev will not attempt to use the |
| 371 | I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and |
371 | I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and |
| 372 | testing, this flag can be useful to conserve inotify file descriptors, as |
372 | testing, this flag can be useful to conserve inotify file descriptors, as |
| 373 | otherwise each loop using C<ev_stat> watchers consumes one inotify handle. |
373 | otherwise 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 | |
| 377 | When this flag is specified, then libev will not attempt to use the |
377 | When this flag is specified, then libev will attempt to use the |
| 378 | I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This is |
378 | I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API |
| 379 | probably only useful to work around any bugs in libev. Consequently, this |
379 | delivers signals synchronously, which makes is both faster and might make |
| 380 | flag might go away once the signalfd functionality is considered stable, |
380 | it possible to get the queued signal data. |
| 381 | so it's useful mostly in environment variables and not in program code. |
381 | |
|
|
382 | Signalfd will not be used by default as this changes your signal mask, and |
|
|
383 | there are a lot of shoddy libraries and programs (glib's threadpool for |
|
|
384 | example) that can't properly initialise their signal masks. |
| 382 | |
385 | |
| 383 | =item C<EVBACKEND_SELECT> (value 1, portable select backend) |
386 | =item C<EVBACKEND_SELECT> (value 1, portable select backend) |
| 384 | |
387 | |
| 385 | This is your standard select(2) backend. Not I<completely> standard, as |
388 | This is your standard select(2) backend. Not I<completely> standard, as |
| 386 | libev tries to roll its own fd_set with no limits on the number of fds, |
389 | libev tries to roll its own fd_set with no limits on the number of fds, |
| … | |
… | |
| 792 | |
795 | |
| 793 | Ref/unref can be used to add or remove a reference count on the event |
796 | Ref/unref can be used to add or remove a reference count on the event |
| 794 | loop: Every watcher keeps one reference, and as long as the reference |
797 | loop: Every watcher keeps one reference, and as long as the reference |
| 795 | count is nonzero, C<ev_loop> will not return on its own. |
798 | count is nonzero, C<ev_loop> will not return on its own. |
| 796 | |
799 | |
| 797 | If you have a watcher you never unregister that should not keep C<ev_loop> |
800 | This is useful when you have a watcher that you never intend to |
| 798 | from returning, call ev_unref() after starting, and ev_ref() before |
801 | unregister, but that nevertheless should not keep C<ev_loop> from |
|
|
802 | returning. In such a case, call C<ev_unref> after starting, and C<ev_ref> |
| 799 | stopping it. |
803 | before stopping it. |
| 800 | |
804 | |
| 801 | As an example, libev itself uses this for its internal signal pipe: It |
805 | As an example, libev itself uses this for its internal signal pipe: It |
| 802 | is not visible to the libev user and should not keep C<ev_loop> from |
806 | is not visible to the libev user and should not keep C<ev_loop> from |
| 803 | exiting if no event watchers registered by it are active. It is also an |
807 | exiting if no event watchers registered by it are active. It is also an |
| 804 | excellent way to do this for generic recurring timers or from within |
808 | excellent way to do this for generic recurring timers or from within |
| … | |
… | |
| 2131 | C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should |
2135 | C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should |
| 2132 | not be unduly interrupted. If you have a problem with system calls getting |
2136 | not be unduly interrupted. If you have a problem with system calls getting |
| 2133 | interrupted by signals you can block all signals in an C<ev_check> watcher |
2137 | interrupted by signals you can block all signals in an C<ev_check> watcher |
| 2134 | and unblock them in an C<ev_prepare> watcher. |
2138 | and unblock them in an C<ev_prepare> watcher. |
| 2135 | |
2139 | |
| 2136 | =head3 The special problem of inheritance over execve |
2140 | =head3 The special problem of inheritance over fork/execve/pthread_create |
| 2137 | |
2141 | |
| 2138 | Both the signal mask (C<sigprocmask>) and the signal disposition |
2142 | Both the signal mask (C<sigprocmask>) and the signal disposition |
| 2139 | (C<sigaction>) are unspecified after starting a signal watcher (and after |
2143 | (C<sigaction>) are unspecified after starting a signal watcher (and after |
| 2140 | stopping it again), that is, libev might or might not block the signal, |
2144 | stopping it again), that is, libev might or might not block the signal, |
| 2141 | and might or might not set or restore the installed signal handler. |
2145 | and might or might not set or restore the installed signal handler. |
| … | |
… | |
| 2151 | |
2155 | |
| 2152 | The simplest way to ensure that the signal mask is reset in the child is |
2156 | The simplest way to ensure that the signal mask is reset in the child is |
| 2153 | to install a fork handler with C<pthread_atfork> that resets it. That will |
2157 | to install a fork handler with C<pthread_atfork> that resets it. That will |
| 2154 | catch fork calls done by libraries (such as the libc) as well. |
2158 | catch fork calls done by libraries (such as the libc) as well. |
| 2155 | |
2159 | |
| 2156 | In current versions of libev, you can also ensure that the signal mask is |
2160 | In current versions of libev, the signal will not be blocked indefinitely |
| 2157 | not blocking any signals (except temporarily, so thread users watch out) |
2161 | unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces |
| 2158 | by specifying the C<EVFLAG_NOSIGFD> when creating the event loop. This |
2162 | the window of opportunity for problems, it will not go away, as libev |
| 2159 | is not guaranteed for future versions, however. |
2163 | I<has> to modify the signal mask, at least temporarily. |
|
|
2164 | |
|
|
2165 | So I can't stress this enough I<if you do not reset your signal mask |
|
|
2166 | when you expect it to be empty, you have a race condition in your |
|
|
2167 | program>. This is not a libev-specific thing, this is true for most event |
|
|
2168 | libraries. |
| 2160 | |
2169 | |
| 2161 | =head3 Watcher-Specific Functions and Data Members |
2170 | =head3 Watcher-Specific Functions and Data Members |
| 2162 | |
2171 | |
| 2163 | =over 4 |
2172 | =over 4 |
| 2164 | |
2173 | |
