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>).
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
=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:
=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
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
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.
- 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
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)
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.
=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_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
projects / software / libev.git / blobdiff