Move typedef and constant to the top.

[software/libev.git] / ev.pod

diff --git a/ev.pod b/ev.pod
index 6d1b57cc591e06cdc919132abd7b10d75b2b342d..9ef6da23f19aa8e8a1b5d474d3a199a24fc7aa7a 100644 (file)
--- 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.
 
 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>).
 
 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.
 
 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
 =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
 =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:
 
 
 The most typical usage is like this:
 


@@ -475,14 +485,16 @@ earlier call to C<ev_loop_new>.
 
 =item ev_default_fork ()
 
 
 =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
 
 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);
 
 
     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
 =item ev_loop_fork (loop)
 
 Like C<ev_default_fork>, but acts on an event loop created by


@@ -592,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.
 
 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)
 =item ev_ref (loop)
 
 =item ev_unref (loop)


@@ -605,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
 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.
 
 Example: Create a signal watcher, but keep it from keeping C<ev_loop>
 running when nothing else is active.


@@ -2551,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
 =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
 
 
 =item EV_CONFIG_H
 


@@ -2563,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
 =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
 
 
 =item EV_PROTOTYPES