X-Git-Url: https://git.llucax.com/software/libev.git/blobdiff_plain/b7ecda387a714c9e3d208b453360d15bd4cad664..refs/heads/master:/ev.pod

diff --git a/ev.pod b/ev.pod
index c424200..9ef6da2 100644
--- a/ev.pod
+++ b/ev.pod
@@ -262,6 +262,13 @@ flags. If that is troubling you, check C<ev_backend ()> afterwards).
 If you don't know what event loop to use, use the one returned from this
 function.
 
+The default loop is the only loop that can handle C<ev_signal> and
+C<ev_child> watchers, and to do this, it always registers a handler
+for C<SIGCHLD>. If this is a problem for your app you can either
+create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
+can simply overwrite the C<SIGCHLD> signal handler I<after> calling
+C<ev_default_init>.
+
 The flags argument can be used to specify special behaviour or specific
 backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
 
@@ -405,6 +412,10 @@ file descriptor per loop iteration. For small and medium numbers of file
 descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
 might perform better.
 
+On the positive side, ignoring the spurious readyness notifications, this
+backend actually performed to specification in all tests and is fully
+embeddable, which is a rare feat among the OS-specific backends.
+
 =item C<EVBACKEND_ALL>
 
 Try all backends (even potentially broken ones that wouldn't be tried
@@ -416,9 +427,8 @@ It is definitely not recommended to use this flag.
 =back
 
 If one or more of these are ored into the flags value, then only these
-backends will be tried (in the reverse order as given here). If none are
-specified, most compiled-in backend will be tried, usually in reverse
-order of their flag values :)
+backends will be tried (in the reverse order as listed here). If none are
+specified, all backends in C<ev_recommended_backends ()> will be tried.
 
 The most typical usage is like this:
 
@@ -475,14 +485,16 @@ earlier call to C<ev_loop_new>.
 
 =item ev_default_fork ()
 
-This function reinitialises the kernel state for backends that have
-one. Despite the name, you can call it anytime, but it makes most sense
-after forking, in either the parent or child process (or both, but that
-again makes little sense).
+This function sets a flag that causes subsequent C<ev_loop> iterations
+to reinitialise the kernel state for backends that have one. Despite the
+name, you can call it anytime, but it makes most sense after forking, in
+the child process (or both child and parent, but that again makes little
+sense). You I<must> call it in the child before using any of the libev
+functions, and it will only take effect at the next C<ev_loop> iteration.
 
-You I<must> call this function in the child process after forking if and
-only if you want to use the event library in both processes. If you just
-fork+exec, you don't have to call it.
+On the other hand, you only need to call this function in the child
+process if and only if you want to use the event library in the child. If
+you just fork+exec, you don't have to call it at all.
 
 The function itself is quite fast and it's usually not a problem to call
 it just in case after a fork. To make this easy, the function will fit in
@@ -490,10 +502,6 @@ quite nicely into a call to C<pthread_atfork>:
 
     pthread_atfork (0, 0, ev_default_fork);
 
-At the moment, C<EVBACKEND_SELECT> and C<EVBACKEND_POLL> are safe to use
-without calling this function, so if you force one of those backends you
-do not need to care.
-
 =item ev_loop_fork (loop)
 
 Like C<ev_default_fork>, but acts on an event loop created by
@@ -553,12 +561,16 @@ usually a better approach for this kind of thing.
 Here are the gory details of what C<ev_loop> does:
 
    - Before the first iteration, call any pending watchers.
-   * If there are no active watchers (reference count is zero), return.
-   - Queue all prepare watchers and then call all outstanding watchers.
+   * If EVFLAG_FORKCHECK was used, check for a fork.
+   - If a fork was detected, queue and call all fork watchers.
+   - Queue and call all prepare watchers.
    - If we have been forked, recreate the kernel state.
    - Update the kernel state with all outstanding changes.
    - Update the "event loop time".
-   - Calculate for how long to block.
+   - Calculate for how long to sleep or block, if at all
+     (active idle watchers, EVLOOP_NONBLOCK or not having
+     any active watchers at all will result in not sleeping).
+   - Sleep if the I/O and timer collect interval say so.
    - Block the process, waiting for any events.
    - Queue all outstanding I/O (fd) events.
    - Update the "event loop time" and do time jump handling.
@@ -569,10 +581,11 @@ Here are the gory details of what C<ev_loop> does:
    - Call all queued watchers in reverse order (i.e. check watchers first).
      Signals and child watchers are implemented as I/O watchers, and will
      be handled here by queueing them when their watcher gets executed.
-   - If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
-     were used, return, otherwise continue with step *.
+   - If ev_unloop has been called, or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
+     were used, or there are no active watchers, return, otherwise
+     continue with step *.
 
-Example: Queue some jobs and then loop until no events are outsanding
+Example: Queue some jobs and then loop until no events are outstanding
 anymore.
 
    ... queue jobs here, make sure they register event watchers as long
@@ -587,6 +600,8 @@ has processed all outstanding events). The C<how> argument must be either
 C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
 C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
 
+This "unloop state" will be cleared when entering C<ev_loop> again.
+
 =item ev_ref (loop)
 
 =item ev_unref (loop)
@@ -600,7 +615,9 @@ example, libev itself uses this for its internal signal pipe: It is not
 visible to the libev user and should not keep C<ev_loop> from exiting if
 no event watchers registered by it are active. It is also an excellent
 way to do this for generic recurring timers or from within third-party
-libraries. Just remember to I<unref after start> and I<ref before stop>.
+libraries. Just remember to I<unref after start> and I<ref before stop>
+(but only if the watcher wasn't active before, or was active before,
+respectively).
 
 Example: Create a signal watcher, but keep it from keeping C<ev_loop>
 running when nothing else is active.
@@ -2546,8 +2563,8 @@ be detected at runtime.
 =item EV_H
 
 The name of the F<ev.h> header file used to include it. The default if
-undefined is C<"ev.h"> in F<event.h> and F<ev.c>. This can be used to
-virtually rename the F<ev.h> header file in case of conflicts.
+undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
+used to virtually rename the F<ev.h> header file in case of conflicts.
 
 =item EV_CONFIG_H
 
@@ -2558,7 +2575,7 @@ C<EV_H>, above.
 =item EV_EVENT_H
 
 Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
-of how the F<event.h> header can be found, the dfeault is C<"event.h">.
+of how the F<event.h> header can be found, the default is C<"event.h">.
 
 =item EV_PROTOTYPES