diff options
Diffstat (limited to 'ev.pod')
| -rw-r--r-- | ev.pod | 58 |
1 files changed, 54 insertions, 4 deletions
@@ -301,6 +301,19 @@ Example: This is basically the same thing that libev does internally, too. ... ev_set_syserr_cb (fatal_error); +=item ev_feed_signal (int signum) + +This function can be used to "simulate" a signal receive. It is completely +safe to call this function at any time, from any context, including signal +handlers or random threads. + +It's main use is to customise signal handling in your process, especially +in the presence of threads. For example, you could block signals +by default in all threads (and specifying C<EVFLAG_NOSIGMASK> when +creating any loops), and in one thread, use C<sigwait> or any other +mechanism to wait for signals, then "deliver" them to libev by calling +C<ev_feed_signal>. + =back =head1 FUNCTIONS CONTROLLING EVENT LOOPS @@ -421,6 +434,18 @@ 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<EVFLAG_NOSIGMASK> + +When this flag is specified, then libev will avoid to modify the signal +mask. Specifically, this means you ahve to make sure signals are unblocked +when you want to receive them. + +This behaviour is useful when you want to do your own signal handling, or +want to handle signals only in specific threads and want to avoid libev +unblocking the signals. + +This flag's behaviour will become the default in future versions of libev. + =item C<EVBACKEND_SELECT> (value 1, portable select backend) This is your standard select(2) backend. Not I<completely> standard, as @@ -582,7 +607,15 @@ Try all backends (even potentially broken ones that wouldn't be tried with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>. -It is definitely not recommended to use this flag. +It is definitely not recommended to use this flag, use whatever +C<ev_recommended_backends ()> returns, or simply do not specify a backend +at all. + +=item C<EVBACKEND_MASK> + +Not a backend at all, but a mask to select all backend bits from a +C<flags> value, in case you want to mask out any backends from a flags +value (e.g. when modifying the C<LIBEV_FLAGS> environment variable). =back @@ -2322,6 +2355,20 @@ 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 The special problem of threads signal handling + +POSIX threads has problematic signal handling semantics, specifically, +a lot of functionality (sigfd, sigwait etc.) only really works if all +threads in a process block signals, which is hard to achieve. + +When you want to use sigwait (or mix libev signal handling with your own +for the same signals), you can tackle this problem by globally blocking +all signals before creating any threads (or creating them with a fully set +sigprocmask) and also specifying the C<EVFLAG_NOSIGMASK> when creating +loops. Then designate one thread as "signal receiver thread" which handles +these signals. You can pass on any signals that libev might be interested +in by calling C<ev_feed_signal>. + =head3 Watcher-Specific Functions and Data Members =over 4 @@ -3177,7 +3224,10 @@ it by calling C<ev_async_send>, which is thread- and signal safe. This functionality is very similar to C<ev_signal> watchers, as signals, too, are asynchronous in nature, and signals, too, will be compressed (i.e. the number of callback invocations may be less than the number of -C<ev_async_sent> calls). +C<ev_async_sent> calls). In fact, you could use signal watchers as a kind +of "global async watchers" by using a watcher on an otherwise unused +signal, and C<ev_feed_signal> to signal this watcher from another thread, +even without knowing which loop owns the signal. Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not just the default loop. @@ -3363,8 +3413,8 @@ the given events it. =item ev_feed_signal_event (loop, int signum) -Feed an event as if the given signal occurred (C<loop> must be the default -loop!). +Feed an event as if the given signal occurred. See also C<ev_feed_signal>, +which is async-safe. =back |