*** empty log message ***

1 files changed, 54 insertions, 4 deletions

diff --git a/ev.pod b/ev.pod
index c2652cc..b682667 100644
--- a/ev.pod
+++ b/ev.pod
@@ -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