evdispatch 0.1.0

data/ext/revdispatch/libevdispatch/libev/ev.pod

@@ -0,0 +1,3192 @@
+=head1 NAME
+
+libev - a high performance full-featured event loop written in C
+
+=head1 SYNOPSIS
+
+  #include <ev.h>
+
+=head2 EXAMPLE PROGRAM
+
+  // a single header file is required
+  #include <ev.h>
+
+  // every watcher type has its own typedef'd struct
+  // with the name ev_<type>
+  ev_io stdin_watcher;
+  ev_timer timeout_watcher;
+
+  // all watcher callbacks have a similar signature
+  // this callback is called when data is readable on stdin
+  static void
+  stdin_cb (EV_P_ struct ev_io *w, int revents)
+  {
+    puts ("stdin ready");
+    // for one-shot events, one must manually stop the watcher
+    // with its corresponding stop function.
+    ev_io_stop (EV_A_ w);
+
+    // this causes all nested ev_loop's to stop iterating
+    ev_unloop (EV_A_ EVUNLOOP_ALL);
+  }
+
+  // another callback, this time for a time-out
+  static void
+  timeout_cb (EV_P_ struct ev_timer *w, int revents)
+  {
+    puts ("timeout");
+    // this causes the innermost ev_loop to stop iterating
+    ev_unloop (EV_A_ EVUNLOOP_ONE);
+  }
+
+  int
+  main (void)
+  {
+    // use the default event loop unless you have special needs
+    struct ev_loop *loop = ev_default_loop (0);
+
+    // initialise an io watcher, then start it
+    // this one will watch for stdin to become readable
+    ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
+    ev_io_start (loop, &stdin_watcher);
+
+    // initialise a timer watcher, then start it
+    // simple non-repeating 5.5 second timeout
+    ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
+    ev_timer_start (loop, &timeout_watcher);
+
+    // now wait for events to arrive
+    ev_loop (loop, 0);
+
+    // unloop was called, so exit
+    return 0;
+  }
+
+=head1 DESCRIPTION
+
+The newest version of this document is also available as an html-formatted
+web page you might find easier to navigate when reading it for the first
+time: L<http://cvs.schmorp.de/libev/ev.html>.
+
+Libev is an event loop: you register interest in certain events (such as a
+file descriptor being readable or a timeout occurring), and it will manage
+these event sources and provide your program with events.
+
+To do this, it must take more or less complete control over your process
+(or thread) by executing the I<event loop> handler, and will then
+communicate events via a callback mechanism.
+
+You register interest in certain events by registering so-called I<event
+watchers>, which are relatively small C structures you initialise with the
+details of the event, and then hand it over to libev by I<starting> the
+watcher.
+
+=head2 FEATURES
+
+Libev supports C<select>, C<poll>, the Linux-specific C<epoll>, the
+BSD-specific C<kqueue> and the Solaris-specific event port mechanisms
+for file descriptor events (C<ev_io>), the Linux C<inotify> interface
+(for C<ev_stat>), relative timers (C<ev_timer>), absolute timers
+with customised rescheduling (C<ev_periodic>), synchronous signals
+(C<ev_signal>), process status change events (C<ev_child>), and event
+watchers dealing with the event loop mechanism itself (C<ev_idle>,
+C<ev_embed>, C<ev_prepare> and C<ev_check> watchers) as well as
+file watchers (C<ev_stat>) and even limited support for fork events
+(C<ev_fork>).
+
+It also is quite fast (see this
+L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
+for example).
+
+=head2 CONVENTIONS
+
+Libev is very configurable. In this manual the default (and most common)
+configuration will be described, which supports multiple event loops. For
+more info about various configuration options please have a look at
+B<EMBED> section in this manual. If libev was configured without support
+for multiple event loops, then all functions taking an initial argument of
+name C<loop> (which is always of type C<struct ev_loop *>) will not have
+this argument.
+
+=head2 TIME REPRESENTATION
+
+Libev represents time as a single floating point number, representing the
+(fractional) number of seconds since the (POSIX) epoch (somewhere near
+the beginning of 1970, details are complicated, don't ask). This type is
+called C<ev_tstamp>, which is what you should use too. It usually aliases
+to the C<double> type in C, and when you need to do any calculations on
+it, you should treat it as some floatingpoint value. Unlike the name
+component C<stamp> might indicate, it is also used for time differences
+throughout libev.
+
+=head1 GLOBAL FUNCTIONS
+
+These functions can be called anytime, even before initialising the
+library in any way.
+
+=over 4
+
+=item ev_tstamp ev_time ()
+
+Returns the current time as libev would use it. Please note that the
+C<ev_now> function is usually faster and also often returns the timestamp
+you actually want to know.
+
+=item ev_sleep (ev_tstamp interval)
+
+Sleep for the given interval: The current thread will be blocked until
+either it is interrupted or the given time interval has passed. Basically
+this is a subsecond-resolution C<sleep ()>.
+
+=item int ev_version_major ()
+
+=item int ev_version_minor ()
+
+You can find out the major and minor ABI version numbers of the library
+you linked against by calling the functions C<ev_version_major> and
+C<ev_version_minor>. If you want, you can compare against the global
+symbols C<EV_VERSION_MAJOR> and C<EV_VERSION_MINOR>, which specify the
+version of the library your program was compiled against.
+
+These version numbers refer to the ABI version of the library, not the
+release version.
+
+Usually, it's a good idea to terminate if the major versions mismatch,
+as this indicates an incompatible change. Minor versions are usually
+compatible to older versions, so a larger minor version alone is usually
+not a problem.
+
+Example: Make sure we haven't accidentally been linked against the wrong
+version.
+
+  assert (("libev version mismatch",
+           ev_version_major () == EV_VERSION_MAJOR
+           && ev_version_minor () >= EV_VERSION_MINOR));
+
+=item unsigned int ev_supported_backends ()
+
+Return the set of all backends (i.e. their corresponding C<EV_BACKEND_*>
+value) compiled into this binary of libev (independent of their
+availability on the system you are running on). See C<ev_default_loop> for
+a description of the set values.
+
+Example: make sure we have the epoll method, because yeah this is cool and
+a must have and can we have a torrent of it please!!!11
+
+  assert (("sorry, no epoll, no sex",
+           ev_supported_backends () & EVBACKEND_EPOLL));
+
+=item unsigned int ev_recommended_backends ()
+
+Return the set of all backends compiled into this binary of libev and also
+recommended for this platform. This set is often smaller than the one
+returned by C<ev_supported_backends>, as for example kqueue is broken on
+most BSDs and will not be autodetected unless you explicitly request it
+(assuming you know what you are doing). This is the set of backends that
+libev will probe for if you specify no backends explicitly.
+
+=item unsigned int ev_embeddable_backends ()
+
+Returns the set of backends that are embeddable in other event loops. This
+is the theoretical, all-platform, value. To find which backends
+might be supported on the current system, you would need to look at
+C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
+recommended ones.
+
+See the description of C<ev_embed> watchers for more info.
+
+=item ev_set_allocator (void *(*cb)(void *ptr, long size))
+
+Sets the allocation function to use (the prototype is similar - the
+semantics is identical - to the realloc C function). It is used to
+allocate and free memory (no surprises here). If it returns zero when
+memory needs to be allocated, the library might abort or take some
+potentially destructive action. The default is your system realloc
+function.
+
+You could override this function in high-availability programs to, say,
+free some memory if it cannot allocate memory, to use a special allocator,
+or even to sleep a while and retry until some memory is available.
+
+Example: Replace the libev allocator with one that waits a bit and then
+retries).
+
+   static void *
+   persistent_realloc (void *ptr, size_t size)
+   {
+     for (;;)
+       {
+         void *newptr = realloc (ptr, size);
+
+         if (newptr)
+           return newptr;
+
+         sleep (60);
+       }
+   }
+
+   ...
+   ev_set_allocator (persistent_realloc);
+
+=item ev_set_syserr_cb (void (*cb)(const char *msg));
+
+Set the callback function to call on a retryable syscall error (such
+as failed select, poll, epoll_wait). The message is a printable string
+indicating the system call or subsystem causing the problem. If this
+callback is set, then libev will expect it to remedy the sitution, no
+matter what, when it returns. That is, libev will generally retry the
+requested operation, or, if the condition doesn't go away, do bad stuff
+(such as abort).
+
+Example: This is basically the same thing that libev does internally, too.
+
+   static void
+   fatal_error (const char *msg)
+   {
+     perror (msg);
+     abort ();
+   }
+
+   ...
+   ev_set_syserr_cb (fatal_error);
+
+=back
+
+=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
+
+An event loop is described by a C<struct ev_loop *>. The library knows two
+types of such loops, the I<default> loop, which supports signals and child
+events, and dynamically created loops which do not.
+
+If you use threads, a common model is to run the default event loop
+in your main thread (or in a separate thread) and for each thread you
+create, you also create another event loop. Libev itself does no locking
+whatsoever, so if you mix calls to the same event loop in different
+threads, make sure you lock (this is usually a bad idea, though, even if
+done correctly, because it's hideous and inefficient).
+
+=over 4
+
+=item struct ev_loop *ev_default_loop (unsigned int flags)
+
+This will initialise the default event loop if it hasn't been initialised
+yet and return it. If the default loop could not be initialised, returns
+false. If it already was initialised it simply returns it (and ignores the
+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.
+
+Note that this function is I<not> thread-safe, so if you want to use it
+from multiple threads, you have to lock (note also that this is unlikely,
+as loops cannot bes hared easily between threads anyway).
+
+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 following flags are supported:
+
+=over 4
+
+=item C<EVFLAG_AUTO>
+
+The default flags value. Use this if you have no clue (it's the right
+thing, believe me).
+
+=item C<EVFLAG_NOENV>
+
+If this flag bit is ored into the flag value (or the program runs setuid
+or setgid) then libev will I<not> look at the environment variable
+C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
+override the flags completely if it is found in the environment. This is
+useful to try out specific backends to test their performance, or to work
+around bugs.
+
+=item C<EVFLAG_FORKCHECK>
+
+Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after
+a fork, you can also make libev check for a fork in each iteration by
+enabling this flag.
+
+This works by calling C<getpid ()> on every iteration of the loop,
+and thus this might slow down your event loop if you do a lot of loop
+iterations and little real work, but is usually not noticeable (on my
+GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
+without a syscall and thus I<very> fast, but my GNU/Linux system also has
+C<pthread_atfork> which is even faster).
+
+The big advantage of this flag is that you can forget about fork (and
+forget about forgetting to tell libev about forking) when you use this
+flag.
+
+This flag setting cannot be overriden or specified in the C<LIBEV_FLAGS>
+environment variable.
+
+=item C<EVBACKEND_SELECT>  (value 1, portable select backend)
+
+This is your standard select(2) backend. Not I<completely> standard, as
+libev tries to roll its own fd_set with no limits on the number of fds,
+but if that fails, expect a fairly low limit on the number of fds when
+using this backend. It doesn't scale too well (O(highest_fd)), but its
+usually the fastest backend for a low number of (low-numbered :) fds.
+
+To get good performance out of this backend you need a high amount of
+parallelity (most of the file descriptors should be busy). If you are
+writing a server, you should C<accept ()> in a loop to accept as many
+connections as possible during one iteration. You might also want to have
+a look at C<ev_set_io_collect_interval ()> to increase the amount of
+readyness notifications you get per iteration.
+
+=item C<EVBACKEND_POLL>    (value 2, poll backend, available everywhere except on windows)
+
+And this is your standard poll(2) backend. It's more complicated
+than select, but handles sparse fds better and has no artificial
+limit on the number of fds you can use (except it will slow down
+considerably with a lot of inactive fds). It scales similarly to select,
+i.e. O(total_fds). See the entry for C<EVBACKEND_SELECT>, above, for
+performance tips.
+
+=item C<EVBACKEND_EPOLL>   (value 4, Linux)
+
+For few fds, this backend is a bit little slower than poll and select,
+but it scales phenomenally better. While poll and select usually scale
+like O(total_fds) where n is the total number of fds (or the highest fd),
+epoll scales either O(1) or O(active_fds). The epoll design has a number
+of shortcomings, such as silently dropping events in some hard-to-detect
+cases and rewiring a syscall per fd change, no fork support and bad
+support for dup.
+
+While stopping, setting and starting an I/O watcher in the same iteration
+will result in some caching, there is still a syscall per such incident
+(because the fd could point to a different file description now), so its
+best to avoid that. Also, C<dup ()>'ed file descriptors might not work
+very well if you register events for both fds.
+
+Please note that epoll sometimes generates spurious notifications, so you
+need to use non-blocking I/O or other means to avoid blocking when no data
+(or space) is available.
+
+Best performance from this backend is achieved by not unregistering all
+watchers for a file descriptor until it has been closed, if possible, i.e.
+keep at least one watcher active per fd at all times.
+
+While nominally embeddeble in other event loops, this feature is broken in
+all kernel versions tested so far.
+
+=item C<EVBACKEND_KQUEUE>  (value 8, most BSD clones)
+
+Kqueue deserves special mention, as at the time of this writing, it
+was broken on all BSDs except NetBSD (usually it doesn't work reliably
+with anything but sockets and pipes, except on Darwin, where of course
+it's completely useless). For this reason it's not being "autodetected"
+unless you explicitly specify it explicitly in the flags (i.e. using
+C<EVBACKEND_KQUEUE>) or libev was compiled on a known-to-be-good (-enough)
+system like NetBSD.
+
+You still can embed kqueue into a normal poll or select backend and use it
+only for sockets (after having made sure that sockets work with kqueue on
+the target platform). See C<ev_embed> watchers for more info.
+
+It scales in the same way as the epoll backend, but the interface to the
+kernel is more efficient (which says nothing about its actual speed, of
+course). While stopping, setting and starting an I/O watcher does never
+cause an extra syscall as with C<EVBACKEND_EPOLL>, it still adds up to
+two event changes per incident, support for C<fork ()> is very bad and it
+drops fds silently in similarly hard-to-detect cases.
+
+This backend usually performs well under most conditions.
+
+While nominally embeddable in other event loops, this doesn't work
+everywhere, so you might need to test for this. And since it is broken
+almost everywhere, you should only use it when you have a lot of sockets
+(for which it usually works), by embedding it into another event loop
+(e.g. C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>) and using it only for
+sockets.
+
+=item C<EVBACKEND_DEVPOLL> (value 16, Solaris 8)
+
+This is not implemented yet (and might never be, unless you send me an
+implementation). According to reports, C</dev/poll> only supports sockets
+and is not embeddable, which would limit the usefulness of this backend
+immensely.
+
+=item C<EVBACKEND_PORT>    (value 32, Solaris 10)
+
+This uses the Solaris 10 event port mechanism. As with everything on Solaris,
+it's really slow, but it still scales very well (O(active_fds)).
+
+Please note that solaris event ports can deliver a lot of spurious
+notifications, so you need to use non-blocking I/O or other means to avoid
+blocking when no data (or space) is available.
+
+While this backend scales well, it requires one system call per active
+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
+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.
+
+=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 listed here). If none are
+specified, all backends in C<ev_recommended_backends ()> will be tried.
+
+The most typical usage is like this:
+
+  if (!ev_default_loop (0))
+    fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
+
+Restrict libev to the select and poll backends, and do not allow
+environment settings to be taken into account:
+
+  ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
+
+Use whatever libev has to offer, but make sure that kqueue is used if
+available (warning, breaks stuff, best use only with your own private
+event loop and only if you know the OS supports your types of fds):
+
+  ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
+
+=item struct ev_loop *ev_loop_new (unsigned int flags)
+
+Similar to C<ev_default_loop>, but always creates a new event loop that is
+always distinct from the default loop. Unlike the default loop, it cannot
+handle signal and child watchers, and attempts to do so will be greeted by
+undefined behaviour (or a failed assertion if assertions are enabled).
+
+Note that this function I<is> thread-safe, and the recommended way to use
+libev with threads is indeed to create one loop per thread, and using the
+default loop in the "main" or "initial" thread.
+
+Example: Try to create a event loop that uses epoll and nothing else.
+
+  struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
+  if (!epoller)
+    fatal ("no epoll found here, maybe it hides under your chair");
+
+=item ev_default_destroy ()
+
+Destroys the default loop again (frees all memory and kernel state
+etc.). None of the active event watchers will be stopped in the normal
+sense, so e.g. C<ev_is_active> might still return true. It is your
+responsibility to either stop all watchers cleanly yoursef I<before>
+calling this function, or cope with the fact afterwards (which is usually
+the easiest thing, you can just ignore the watchers and/or C<free ()> them
+for example).
+
+Note that certain global state, such as signal state, will not be freed by
+this function, and related watchers (such as signal and child watchers)
+would need to be stopped manually.
+
+In general it is not advisable to call this function except in the
+rare occasion where you really need to free e.g. the signal handling
+pipe fds. If you need dynamically allocated loops it is better to use
+C<ev_loop_new> and C<ev_loop_destroy>).
+
+=item ev_loop_destroy (loop)
+
+Like C<ev_default_destroy>, but destroys an event loop created by an
+earlier call to C<ev_loop_new>.
+
+=item ev_default_fork ()
+
+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.
+
+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
+quite nicely into a call to C<pthread_atfork>:
+
+    pthread_atfork (0, 0, ev_default_fork);
+
+=item ev_loop_fork (loop)
+
+Like C<ev_default_fork>, but acts on an event loop created by
+C<ev_loop_new>. Yes, you have to call this on every allocated event loop
+after fork, and how you do this is entirely your own problem.
+
+=item int ev_is_default_loop (loop)
+
+Returns true when the given loop actually is the default loop, false otherwise.
+
+=item unsigned int ev_loop_count (loop)
+
+Returns the count of loop iterations for the loop, which is identical to
+the number of times libev did poll for new events. It starts at C<0> and
+happily wraps around with enough iterations.
+
+This value can sometimes be useful as a generation counter of sorts (it
+"ticks" the number of loop iterations), as it roughly corresponds with
+C<ev_prepare> and C<ev_check> calls.
+
+=item unsigned int ev_backend (loop)
+
+Returns one of the C<EVBACKEND_*> flags indicating the event backend in
+use.
+
+=item ev_tstamp ev_now (loop)
+
+Returns the current "event loop time", which is the time the event loop
+received events and started processing them. This timestamp does not
+change as long as callbacks are being processed, and this is also the base
+time used for relative timers. You can treat it as the timestamp of the
+event occurring (or more correctly, libev finding out about it).
+
+=item ev_loop (loop, int flags)
+
+Finally, this is it, the event handler. This function usually is called
+after you initialised all your watchers and you want to start handling
+events.
+
+If the flags argument is specified as C<0>, it will not return until
+either no event watchers are active anymore or C<ev_unloop> was called.
+
+Please note that an explicit C<ev_unloop> is usually better than
+relying on all watchers to be stopped when deciding when a program has
+finished (especially in interactive programs), but having a program that
+automatically loops as long as it has to and no longer by virtue of
+relying on its watchers stopping correctly is a thing of beauty.
+
+A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
+those events and any outstanding ones, but will not block your process in
+case there are no events and will return after one iteration of the loop.
+
+A flags value of C<EVLOOP_ONESHOT> will look for new events (waiting if
+neccessary) and will handle those and any outstanding ones. It will block
+your process until at least one new event arrives, and will return after
+one iteration of the loop. This is useful if you are waiting for some
+external event in conjunction with something not expressible using other
+libev watchers. However, a pair of C<ev_prepare>/C<ev_check> watchers is
+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 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 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.
+   - Queue all outstanding timers.
+   - Queue all outstanding periodics.
+   - If no events are pending now, queue all idle watchers.
+   - Queue all check watchers.
+   - 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, or there are no active watchers, return, otherwise
+     continue with step *.
+
+Example: Queue some jobs and then loop until no events are outstanding
+anymore.
+
+   ... queue jobs here, make sure they register event watchers as long
+   ... as they still have work to do (even an idle watcher will do..)
+   ev_loop (my_loop, 0);
+   ... jobs done. yeah!
+
+=item ev_unloop (loop, how)
+
+Can be used to make a call to C<ev_loop> return early (but only after it
+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)
+
+Ref/unref can be used to add or remove a reference count on the event
+loop: Every watcher keeps one reference, and as long as the reference
+count is nonzero, C<ev_loop> will not return on its own. If you have
+a watcher you never unregister that should not keep C<ev_loop> from
+returning, ev_unref() after starting, and ev_ref() before stopping it. For
+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>
+(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.
+
+  struct ev_signal exitsig;
+  ev_signal_init (&exitsig, sig_cb, SIGINT);
+  ev_signal_start (loop, &exitsig);
+  evf_unref (loop);
+
+Example: For some weird reason, unregister the above signal handler again.
+
+  ev_ref (loop);
+  ev_signal_stop (loop, &exitsig);
+
+=item ev_set_io_collect_interval (loop, ev_tstamp interval)
+
+=item ev_set_timeout_collect_interval (loop, ev_tstamp interval)
+
+These advanced functions influence the time that libev will spend waiting
+for events. Both are by default C<0>, meaning that libev will try to
+invoke timer/periodic callbacks and I/O callbacks with minimum latency.
+
+Setting these to a higher value (the C<interval> I<must> be >= C<0>)
+allows libev to delay invocation of I/O and timer/periodic callbacks to
+increase efficiency of loop iterations.
+
+The background is that sometimes your program runs just fast enough to
+handle one (or very few) event(s) per loop iteration. While this makes
+the program responsive, it also wastes a lot of CPU time to poll for new
+events, especially with backends like C<select ()> which have a high
+overhead for the actual polling but can deliver many events at once.
+
+By setting a higher I<io collect interval> you allow libev to spend more
+time collecting I/O events, so you can handle more events per iteration,
+at the cost of increasing latency. Timeouts (both C<ev_periodic> and
+C<ev_timer>) will be not affected. Setting this to a non-null value will
+introduce an additional C<ev_sleep ()> call into most loop iterations.
+
+Likewise, by setting a higher I<timeout collect interval> you allow libev
+to spend more time collecting timeouts, at the expense of increased
+latency (the watcher callback will be called later). C<ev_io> watchers
+will not be affected. Setting this to a non-null value will not introduce
+any overhead in libev.
+
+Many (busy) programs can usually benefit by setting the io collect
+interval to a value near C<0.1> or so, which is often enough for
+interactive servers (of course not for games), likewise for timeouts. It
+usually doesn't make much sense to set it to a lower value than C<0.01>,
+as this approsaches the timing granularity of most systems.
+
+=back
+
+
+=head1 ANATOMY OF A WATCHER
+
+A watcher is a structure that you create and register to record your
+interest in some event. For instance, if you want to wait for STDIN to
+become readable, you would create an C<ev_io> watcher for that:
+
+  static void my_cb (struct ev_loop *loop, struct ev_io *w, int revents)
+  {
+    ev_io_stop (w);
+    ev_unloop (loop, EVUNLOOP_ALL);
+  }
+
+  struct ev_loop *loop = ev_default_loop (0);
+  struct ev_io stdin_watcher;
+  ev_init (&stdin_watcher, my_cb);
+  ev_io_set (&stdin_watcher, STDIN_FILENO, EV_READ);
+  ev_io_start (loop, &stdin_watcher);
+  ev_loop (loop, 0);
+
+As you can see, you are responsible for allocating the memory for your
+watcher structures (and it is usually a bad idea to do this on the stack,
+although this can sometimes be quite valid).
+
+Each watcher structure must be initialised by a call to C<ev_init
+(watcher *, callback)>, which expects a callback to be provided. This
+callback gets invoked each time the event occurs (or, in the case of io
+watchers, each time the event loop detects that the file descriptor given
+is readable and/or writable).
+
+Each watcher type has its own C<< ev_<type>_set (watcher *, ...) >> macro
+with arguments specific to this watcher type. There is also a macro
+to combine initialisation and setting in one call: C<< ev_<type>_init
+(watcher *, callback, ...) >>.
+
+To make the watcher actually watch out for events, you have to start it
+with a watcher-specific start function (C<< ev_<type>_start (loop, watcher
+*) >>), and you can stop watching for events at any time by calling the
+corresponding stop function (C<< ev_<type>_stop (loop, watcher *) >>.
+
+As long as your watcher is active (has been started but not stopped) you
+must not touch the values stored in it. Most specifically you must never
+reinitialise it or call its C<set> macro.
+
+Each and every callback receives the event loop pointer as first, the
+registered watcher structure as second, and a bitset of received events as
+third argument.
+
+The received events usually include a single bit per event type received
+(you can receive multiple events at the same time). The possible bit masks
+are:
+
+=over 4
+
+=item C<EV_READ>
+
+=item C<EV_WRITE>
+
+The file descriptor in the C<ev_io> watcher has become readable and/or
+writable.
+
+=item C<EV_TIMEOUT>
+
+The C<ev_timer> watcher has timed out.
+
+=item C<EV_PERIODIC>
+
+The C<ev_periodic> watcher has timed out.
+
+=item C<EV_SIGNAL>
+
+The signal specified in the C<ev_signal> watcher has been received by a thread.
+
+=item C<EV_CHILD>
+
+The pid specified in the C<ev_child> watcher has received a status change.
+
+=item C<EV_STAT>
+
+The path specified in the C<ev_stat> watcher changed its attributes somehow.
+
+=item C<EV_IDLE>
+
+The C<ev_idle> watcher has determined that you have nothing better to do.
+
+=item C<EV_PREPARE>
+
+=item C<EV_CHECK>
+
+All C<ev_prepare> watchers are invoked just I<before> C<ev_loop> starts
+to gather new events, and all C<ev_check> watchers are invoked just after
+C<ev_loop> has gathered them, but before it invokes any callbacks for any
+received events. Callbacks of both watcher types can start and stop as
+many watchers as they want, and all of them will be taken into account
+(for example, a C<ev_prepare> watcher might start an idle watcher to keep
+C<ev_loop> from blocking).
+
+=item C<EV_EMBED>
+
+The embedded event loop specified in the C<ev_embed> watcher needs attention.
+
+=item C<EV_FORK>
+
+The event loop has been resumed in the child process after fork (see
+C<ev_fork>).
+
+=item C<EV_ASYNC>
+
+The given async watcher has been asynchronously notified (see C<ev_async>).
+
+=item C<EV_ERROR>
+
+An unspecified error has occured, the watcher has been stopped. This might
+happen because the watcher could not be properly started because libev
+ran out of memory, a file descriptor was found to be closed or any other
+problem. You best act on it by reporting the problem and somehow coping
+with the watcher being stopped.
+
+Libev will usually signal a few "dummy" events together with an error,
+for example it might indicate that a fd is readable or writable, and if
+your callbacks is well-written it can just attempt the operation and cope
+with the error from read() or write(). This will not work in multithreaded
+programs, though, so beware.
+
+=back
+
+=head2 GENERIC WATCHER FUNCTIONS
+
+In the following description, C<TYPE> stands for the watcher type,
+e.g. C<timer> for C<ev_timer> watchers and C<io> for C<ev_io> watchers.
+
+=over 4
+
+=item C<ev_init> (ev_TYPE *watcher, callback)
+
+This macro initialises the generic portion of a watcher. The contents
+of the watcher object can be arbitrary (so C<malloc> will do). Only
+the generic parts of the watcher are initialised, you I<need> to call
+the type-specific C<ev_TYPE_set> macro afterwards to initialise the
+type-specific parts. For each type there is also a C<ev_TYPE_init> macro
+which rolls both calls into one.
+
+You can reinitialise a watcher at any time as long as it has been stopped
+(or never started) and there are no pending events outstanding.
+
+The callback is always of type C<void (*)(ev_loop *loop, ev_TYPE *watcher,
+int revents)>.
+
+=item C<ev_TYPE_set> (ev_TYPE *, [args])
+
+This macro initialises the type-specific parts of a watcher. You need to
+call C<ev_init> at least once before you call this macro, but you can
+call C<ev_TYPE_set> any number of times. You must not, however, call this
+macro on a watcher that is active (it can be pending, however, which is a
+difference to the C<ev_init> macro).
+
+Although some watcher types do not have type-specific arguments
+(e.g. C<ev_prepare>) you still need to call its C<set> macro.
+
+=item C<ev_TYPE_init> (ev_TYPE *watcher, callback, [args])
+
+This convinience macro rolls both C<ev_init> and C<ev_TYPE_set> macro
+calls into a single call. This is the most convinient method to initialise
+a watcher. The same limitations apply, of course.
+
+=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher)
+
+Starts (activates) the given watcher. Only active watchers will receive
+events. If the watcher is already active nothing will happen.
+
+=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher)
+
+Stops the given watcher again (if active) and clears the pending
+status. It is possible that stopped watchers are pending (for example,
+non-repeating timers are being stopped when they become pending), but
+C<ev_TYPE_stop> ensures that the watcher is neither active nor pending. If
+you want to free or reuse the memory used by the watcher it is therefore a
+good idea to always call its C<ev_TYPE_stop> function.
+
+=item bool ev_is_active (ev_TYPE *watcher)
+
+Returns a true value iff the watcher is active (i.e. it has been started
+and not yet been stopped). As long as a watcher is active you must not modify
+it.
+
+=item bool ev_is_pending (ev_TYPE *watcher)
+
+Returns a true value iff the watcher is pending, (i.e. it has outstanding
+events but its callback has not yet been invoked). As long as a watcher
+is pending (but not active) you must not call an init function on it (but
+C<ev_TYPE_set> is safe), you must not change its priority, and you must
+make sure the watcher is available to libev (e.g. you cannot C<free ()>
+it).
+
+=item callback ev_cb (ev_TYPE *watcher)
+
+Returns the callback currently set on the watcher.
+
+=item ev_cb_set (ev_TYPE *watcher, callback)
+
+Change the callback. You can change the callback at virtually any time
+(modulo threads).
+
+=item ev_set_priority (ev_TYPE *watcher, priority)
+
+=item int ev_priority (ev_TYPE *watcher)
+
+Set and query the priority of the watcher. The priority is a small
+integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
+(default: C<-2>). Pending watchers with higher priority will be invoked
+before watchers with lower priority, but priority will not keep watchers
+from being executed (except for C<ev_idle> watchers).
+
+This means that priorities are I<only> used for ordering callback
+invocation after new events have been received. This is useful, for
+example, to reduce latency after idling, or more often, to bind two
+watchers on the same event and make sure one is called first.
+
+If you need to suppress invocation when higher priority events are pending
+you need to look at C<ev_idle> watchers, which provide this functionality.
+
+You I<must not> change the priority of a watcher as long as it is active or
+pending.
+
+The default priority used by watchers when no priority has been set is
+always C<0>, which is supposed to not be too high and not be too low :).
+
+Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
+fine, as long as you do not mind that the priority value you query might
+or might not have been adjusted to be within valid range.
+
+=item ev_invoke (loop, ev_TYPE *watcher, int revents)
+
+Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
+C<loop> nor C<revents> need to be valid as long as the watcher callback
+can deal with that fact.
+
+=item int ev_clear_pending (loop, ev_TYPE *watcher)
+
+If the watcher is pending, this function returns clears its pending status
+and returns its C<revents> bitset (as if its callback was invoked). If the
+watcher isn't pending it does nothing and returns C<0>.
+
+=back
+
+
+=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
+
+Each watcher has, by default, a member C<void *data> that you can change
+and read at any time, libev will completely ignore it. This can be used
+to associate arbitrary data with your watcher. If you need more data and
+don't want to allocate memory and store a pointer to it in that data
+member, you can also "subclass" the watcher type and provide your own
+data:
+
+  struct my_io
+  {
+    struct ev_io io;
+    int otherfd;
+    void *somedata;
+    struct whatever *mostinteresting;
+  }
+
+And since your callback will be called with a pointer to the watcher, you
+can cast it back to your own type:
+
+  static void my_cb (struct ev_loop *loop, struct ev_io *w_, int revents)
+  {
+    struct my_io *w = (struct my_io *)w_;
+    ...
+  }
+
+More interesting and less C-conformant ways of casting your callback type
+instead have been omitted.
+
+Another common scenario is having some data structure with multiple
+watchers:
+
+  struct my_biggy
+  {
+    int some_data;
+    ev_timer t1;
+    ev_timer t2;
+  }
+
+In this case getting the pointer to C<my_biggy> is a bit more complicated,
+you need to use C<offsetof>:
+
+  #include <stddef.h>
+
+  static void
+  t1_cb (EV_P_ struct ev_timer *w, int revents)
+  {
+    struct my_biggy big = (struct my_biggy *
+      (((char *)w) - offsetof (struct my_biggy, t1));
+  }
+
+  static void
+  t2_cb (EV_P_ struct ev_timer *w, int revents)
+  {
+    struct my_biggy big = (struct my_biggy *
+      (((char *)w) - offsetof (struct my_biggy, t2));
+  }
+
+
+=head1 WATCHER TYPES
+
+This section describes each watcher in detail, but will not repeat
+information given in the last section. Any initialisation/set macros,
+functions and members specific to the watcher type are explained.
+
+Members are additionally marked with either I<[read-only]>, meaning that,
+while the watcher is active, you can look at the member and expect some
+sensible content, but you must not modify it (you can modify it while the
+watcher is stopped to your hearts content), or I<[read-write]>, which
+means you can expect it to have some sensible content while the watcher
+is active, but you can also modify it. Modifying it may not do something
+sensible or take immediate effect (or do anything at all), but libev will
+not crash or malfunction in any way.
+
+
+=head2 C<ev_io> - is this file descriptor readable or writable?
+
+I/O watchers check whether a file descriptor is readable or writable
+in each iteration of the event loop, or, more precisely, when reading
+would not block the process and writing would at least be able to write
+some data. This behaviour is called level-triggering because you keep
+receiving events as long as the condition persists. Remember you can stop
+the watcher if you don't want to act on the event and neither want to
+receive future events.
+
+In general you can register as many read and/or write event watchers per
+fd as you want (as long as you don't confuse yourself). Setting all file
+descriptors to non-blocking mode is also usually a good idea (but not
+required if you know what you are doing).
+
+If you must do this, then force the use of a known-to-be-good backend
+(at the time of this writing, this includes only C<EVBACKEND_SELECT> and
+C<EVBACKEND_POLL>).
+
+Another thing you have to watch out for is that it is quite easy to
+receive "spurious" readyness notifications, that is your callback might
+be called with C<EV_READ> but a subsequent C<read>(2) will actually block
+because there is no data. Not only are some backends known to create a
+lot of those (for example solaris ports), it is very easy to get into
+this situation even with a relatively standard program structure. Thus
+it is best to always use non-blocking I/O: An extra C<read>(2) returning
+C<EAGAIN> is far preferable to a program hanging until some data arrives.
+
+If you cannot run the fd in non-blocking mode (for example you should not
+play around with an Xlib connection), then you have to seperately re-test
+whether a file descriptor is really ready with a known-to-be good interface
+such as poll (fortunately in our Xlib example, Xlib already does this on
+its own, so its quite safe to use).
+
+=head3 The special problem of disappearing file descriptors
+
+Some backends (e.g. kqueue, epoll) need to be told about closing a file
+descriptor (either by calling C<close> explicitly or by any other means,
+such as C<dup>). The reason is that you register interest in some file
+descriptor, but when it goes away, the operating system will silently drop
+this interest. If another file descriptor with the same number then is
+registered with libev, there is no efficient way to see that this is, in
+fact, a different file descriptor.
+
+To avoid having to explicitly tell libev about such cases, libev follows
+the following policy:  Each time C<ev_io_set> is being called, libev
+will assume that this is potentially a new file descriptor, otherwise
+it is assumed that the file descriptor stays the same. That means that
+you I<have> to call C<ev_io_set> (or C<ev_io_init>) when you change the
+descriptor even if the file descriptor number itself did not change.
+
+This is how one would do it normally anyway, the important point is that
+the libev application should not optimise around libev but should leave
+optimisations to libev.
+
+=head3 The special problem of dup'ed file descriptors
+
+Some backends (e.g. epoll), cannot register events for file descriptors,
+but only events for the underlying file descriptions. That means when you
+have C<dup ()>'ed file descriptors or weirder constellations, and register
+events for them, only one file descriptor might actually receive events.
+
+There is no workaround possible except not registering events
+for potentially C<dup ()>'ed file descriptors, or to resort to
+C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
+
+=head3 The special problem of fork
+
+Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit
+useless behaviour. Libev fully supports fork, but needs to be told about
+it in the child.
+
+To support fork in your programs, you either have to call
+C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child,
+enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or
+C<EVBACKEND_POLL>.
+
+=head3 The special problem of SIGPIPE
+
+While not really specific to libev, it is easy to forget about SIGPIPE:
+when reading from a pipe whose other end has been closed, your program
+gets send a SIGPIPE, which, by default, aborts your program. For most
+programs this is sensible behaviour, for daemons, this is usually
+undesirable.
+
+So when you encounter spurious, unexplained daemon exits, make sure you
+ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
+somewhere, as that would have given you a big clue).
+
+
+=head3 Watcher-Specific Functions
+
+=over 4
+
+=item ev_io_init (ev_io *, callback, int fd, int events)
+
+=item ev_io_set (ev_io *, int fd, int events)
+
+Configures an C<ev_io> watcher. The C<fd> is the file descriptor to
+rceeive events for and events is either C<EV_READ>, C<EV_WRITE> or
+C<EV_READ | EV_WRITE> to receive the given events.
+
+=item int fd [read-only]
+
+The file descriptor being watched.
+
+=item int events [read-only]
+
+The events being watched.
+
+=back
+
+=head3 Examples
+
+Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well
+readable, but only once. Since it is likely line-buffered, you could
+attempt to read a whole line in the callback.
+
+  static void
+  stdin_readable_cb (struct ev_loop *loop, struct ev_io *w, int revents)
+  {
+     ev_io_stop (loop, w);
+    .. read from stdin here (or from w->fd) and haqndle any I/O errors
+  }
+
+  ...
+  struct ev_loop *loop = ev_default_init (0);
+  struct ev_io stdin_readable;
+  ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
+  ev_io_start (loop, &stdin_readable);
+  ev_loop (loop, 0);
+
+
+=head2 C<ev_timer> - relative and optionally repeating timeouts
+
+Timer watchers are simple relative timers that generate an event after a
+given time, and optionally repeating in regular intervals after that.
+
+The timers are based on real time, that is, if you register an event that
+times out after an hour and you reset your system clock to last years
+time, it will still time out after (roughly) and hour. "Roughly" because
+detecting time jumps is hard, and some inaccuracies are unavoidable (the
+monotonic clock option helps a lot here).
+
+The relative timeouts are calculated relative to the C<ev_now ()>
+time. This is usually the right thing as this timestamp refers to the time
+of the event triggering whatever timeout you are modifying/starting. If
+you suspect event processing to be delayed and you I<need> to base the timeout
+on the current time, use something like this to adjust for this:
+
+   ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
+
+The callback is guarenteed to be invoked only when its timeout has passed,
+but if multiple timers become ready during the same loop iteration then
+order of execution is undefined.
+
+=head3 Watcher-Specific Functions and Data Members
+
+=over 4
+
+=item ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)
+
+=item ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)
+
+Configure the timer to trigger after C<after> seconds. If C<repeat> is
+C<0.>, then it will automatically be stopped. If it is positive, then the
+timer will automatically be configured to trigger again C<repeat> seconds
+later, again, and again, until stopped manually.
+
+The timer itself will do a best-effort at avoiding drift, that is, if you
+configure a timer to trigger every 10 seconds, then it will trigger at
+exactly 10 second intervals. If, however, your program cannot keep up with
+the timer (because it takes longer than those 10 seconds to do stuff) the
+timer will not fire more than once per event loop iteration.
+
+=item ev_timer_again (loop, ev_timer *)
+
+This will act as if the timer timed out and restart it again if it is
+repeating. The exact semantics are:
+
+If the timer is pending, its pending status is cleared.
+
+If the timer is started but nonrepeating, stop it (as if it timed out).
+
+If the timer is repeating, either start it if necessary (with the
+C<repeat> value), or reset the running timer to the C<repeat> value.
+
+This sounds a bit complicated, but here is a useful and typical
+example: Imagine you have a tcp connection and you want a so-called idle
+timeout, that is, you want to be called when there have been, say, 60
+seconds of inactivity on the socket. The easiest way to do this is to
+configure an C<ev_timer> with a C<repeat> value of C<60> and then call
+C<ev_timer_again> each time you successfully read or write some data. If
+you go into an idle state where you do not expect data to travel on the
+socket, you can C<ev_timer_stop> the timer, and C<ev_timer_again> will
+automatically restart it if need be.
+
+That means you can ignore the C<after> value and C<ev_timer_start>
+altogether and only ever use the C<repeat> value and C<ev_timer_again>:
+
+   ev_timer_init (timer, callback, 0., 5.);
+   ev_timer_again (loop, timer);
+   ...
+   timer->again = 17.;
+   ev_timer_again (loop, timer);
+   ...
+   timer->again = 10.;
+   ev_timer_again (loop, timer);
+
+This is more slightly efficient then stopping/starting the timer each time
+you want to modify its timeout value.
+
+=item ev_tstamp repeat [read-write]
+
+The current C<repeat> value. Will be used each time the watcher times out
+or C<ev_timer_again> is called and determines the next timeout (if any),
+which is also when any modifications are taken into account.
+
+=back
+
+=head3 Examples
+
+Example: Create a timer that fires after 60 seconds.
+
+  static void
+  one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
+  {
+    .. one minute over, w is actually stopped right here
+  }
+
+  struct ev_timer mytimer;
+  ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
+  ev_timer_start (loop, &mytimer);
+
+Example: Create a timeout timer that times out after 10 seconds of
+inactivity.
+
+  static void
+  timeout_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
+  {
+    .. ten seconds without any activity
+  }
+
+  struct ev_timer mytimer;
+  ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
+  ev_timer_again (&mytimer); /* start timer */
+  ev_loop (loop, 0);
+
+  // and in some piece of code that gets executed on any "activity":
+  // reset the timeout to start ticking again at 10 seconds
+  ev_timer_again (&mytimer);
+
+
+=head2 C<ev_periodic> - to cron or not to cron?
+
+Periodic watchers are also timers of a kind, but they are very versatile
+(and unfortunately a bit complex).
+
+Unlike C<ev_timer>'s, they are not based on real time (or relative time)
+but on wallclock time (absolute time). You can tell a periodic watcher
+to trigger "at" some specific point in time. For example, if you tell a
+periodic watcher to trigger in 10 seconds (by specifiying e.g. C<ev_now ()
++ 10.>) and then reset your system clock to the last year, then it will
+take a year to trigger the event (unlike an C<ev_timer>, which would trigger
+roughly 10 seconds later).
+
+They can also be used to implement vastly more complex timers, such as
+triggering an event on each midnight, local time or other, complicated,
+rules.
+
+As with timers, the callback is guarenteed to be invoked only when the
+time (C<at>) has been passed, but if multiple periodic timers become ready
+during the same loop iteration then order of execution is undefined.
+
+=head3 Watcher-Specific Functions and Data Members
+
+=over 4
+
+=item ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)
+
+=item ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)
+
+Lots of arguments, lets sort it out... There are basically three modes of
+operation, and we will explain them from simplest to complex:
+
+=over 4
+
+=item * absolute timer (at = time, interval = reschedule_cb = 0)
+
+In this configuration the watcher triggers an event at the wallclock time
+C<at> and doesn't repeat. It will not adjust when a time jump occurs,
+that is, if it is to be run at January 1st 2011 then it will run when the
+system time reaches or surpasses this time.
+
+=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
+
+In this mode the watcher will always be scheduled to time out at the next
+C<at + N * interval> time (for some integer N, which can also be negative)
+and then repeat, regardless of any time jumps.
+
+This can be used to create timers that do not drift with respect to system
+time:
+
+   ev_periodic_set (&periodic, 0., 3600., 0);
+
+This doesn't mean there will always be 3600 seconds in between triggers,
+but only that the the callback will be called when the system time shows a
+full hour (UTC), or more correctly, when the system time is evenly divisible
+by 3600.
+
+Another way to think about it (for the mathematically inclined) is that
+C<ev_periodic> will try to run the callback in this mode at the next possible
+time where C<time = at (mod interval)>, regardless of any time jumps.
+
+For numerical stability it is preferable that the C<at> value is near
+C<ev_now ()> (the current time), but there is no range requirement for
+this value.
+
+=item * manual reschedule mode (at and interval ignored, reschedule_cb = callback)
+
+In this mode the values for C<interval> and C<at> are both being
+ignored. Instead, each time the periodic watcher gets scheduled, the
+reschedule callback will be called with the watcher as first, and the
+current time as second argument.
+
+NOTE: I<This callback MUST NOT stop or destroy any periodic watcher,
+ever, or make any event loop modifications>. If you need to stop it,
+return C<now + 1e30> (or so, fudge fudge) and stop it afterwards (e.g. by
+starting an C<ev_prepare> watcher, which is legal).
+
+Its prototype is C<ev_tstamp (*reschedule_cb)(struct ev_periodic *w,
+ev_tstamp now)>, e.g.:
+
+   static ev_tstamp my_rescheduler (struct ev_periodic *w, ev_tstamp now)
+   {
+     return now + 60.;
+   }
+
+It must return the next time to trigger, based on the passed time value
+(that is, the lowest time value larger than to the second argument). It
+will usually be called just before the callback will be triggered, but
+might be called at other times, too.
+
+NOTE: I<< This callback must always return a time that is later than the
+passed C<now> value >>. Not even C<now> itself will do, it I<must> be larger.
+
+This can be used to create very complex timers, such as a timer that
+triggers on each midnight, local time. To do this, you would calculate the
+next midnight after C<now> and return the timestamp value for this. How
+you do this is, again, up to you (but it is not trivial, which is the main
+reason I omitted it as an example).
+
+=back
+
+=item ev_periodic_again (loop, ev_periodic *)
+
+Simply stops and restarts the periodic watcher again. This is only useful
+when you changed some parameters or the reschedule callback would return
+a different time than the last time it was called (e.g. in a crond like
+program when the crontabs have changed).
+
+=item ev_tstamp offset [read-write]
+
+When repeating, this contains the offset value, otherwise this is the
+absolute point in time (the C<at> value passed to C<ev_periodic_set>).
+
+Can be modified any time, but changes only take effect when the periodic
+timer fires or C<ev_periodic_again> is being called.
+
+=item ev_tstamp interval [read-write]
+
+The current interval value. Can be modified any time, but changes only
+take effect when the periodic timer fires or C<ev_periodic_again> is being
+called.
+
+=item ev_tstamp (*reschedule_cb)(struct ev_periodic *w, ev_tstamp now) [read-write]
+
+The current reschedule callback, or C<0>, if this functionality is
+switched off. Can be changed any time, but changes only take effect when
+the periodic timer fires or C<ev_periodic_again> is being called.
+
+=item ev_tstamp at [read-only]
+
+When active, contains the absolute time that the watcher is supposed to
+trigger next.
+
+=back
+
+=head3 Examples
+
+Example: Call a callback every hour, or, more precisely, whenever the
+system clock is divisible by 3600. The callback invocation times have
+potentially a lot of jittering, but good long-term stability.
+
+  static void
+  clock_cb (struct ev_loop *loop, struct ev_io *w, int revents)
+  {
+    ... its now a full hour (UTC, or TAI or whatever your clock follows)
+  }
+
+  struct ev_periodic hourly_tick;
+  ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
+  ev_periodic_start (loop, &hourly_tick);
+
+Example: The same as above, but use a reschedule callback to do it:
+
+  #include <math.h>
+
+  static ev_tstamp
+  my_scheduler_cb (struct ev_periodic *w, ev_tstamp now)
+  {
+    return fmod (now, 3600.) + 3600.;
+  }
+
+  ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
+
+Example: Call a callback every hour, starting now:
+
+  struct ev_periodic hourly_tick;
+  ev_periodic_init (&hourly_tick, clock_cb,
+                    fmod (ev_now (loop), 3600.), 3600., 0);
+  ev_periodic_start (loop, &hourly_tick);
+  
+
+=head2 C<ev_signal> - signal me when a signal gets signalled!
+
+Signal watchers will trigger an event when the process receives a specific
+signal one or more times. Even though signals are very asynchronous, libev
+will try it's best to deliver signals synchronously, i.e. as part of the
+normal event processing, like any other event.
+
+You can configure as many watchers as you like per signal. Only when the
+first watcher gets started will libev actually register a signal watcher
+with the kernel (thus it coexists with your own signal handlers as long
+as you don't register any with libev). Similarly, when the last signal
+watcher for a signal is stopped libev will reset the signal handler to
+SIG_DFL (regardless of what it was set to before).
+
+If possible and supported, libev will install its handlers with
+C<SA_RESTART> behaviour enabled, so syscalls should not be unduly
+interrupted. If you have a problem with syscalls getting interrupted by
+signals you can block all signals in an C<ev_check> watcher and unblock
+them in an C<ev_prepare> watcher.
+
+=head3 Watcher-Specific Functions and Data Members
+
+=over 4
+
+=item ev_signal_init (ev_signal *, callback, int signum)
+
+=item ev_signal_set (ev_signal *, int signum)
+
+Configures the watcher to trigger on the given signal number (usually one
+of the C<SIGxxx> constants).
+
+=item int signum [read-only]
+
+The signal the watcher watches out for.
+
+=back
+
+=head3 Examples
+
+Example: Try to exit cleanly on SIGINT and SIGTERM.
+
+  static void
+  sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
+  {
+    ev_unloop (loop, EVUNLOOP_ALL);
+  }
+
+  struct ev_signal signal_watcher;
+  ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
+  ev_signal_start (loop, &sigint_cb);
+
+
+=head2 C<ev_child> - watch out for process status changes
+
+Child watchers trigger when your process receives a SIGCHLD in response to
+some child status changes (most typically when a child of yours dies). It
+is permissible to install a child watcher I<after> the child has been
+forked (which implies it might have already exited), as long as the event
+loop isn't entered (or is continued from a watcher).
+
+Only the default event loop is capable of handling signals, and therefore
+you can only rgeister child watchers in the default event loop.
+
+=head3 Process Interaction
+
+Libev grabs C<SIGCHLD> as soon as the default event loop is
+initialised. This is necessary to guarantee proper behaviour even if
+the first child watcher is started after the child exits. The occurance
+of C<SIGCHLD> is recorded asynchronously, but child reaping is done
+synchronously as part of the event loop processing. Libev always reaps all
+children, even ones not watched.
+
+=head3 Overriding the Built-In Processing
+
+Libev offers no special support for overriding the built-in child
+processing, but if your application collides with libev's default child
+handler, you can override it easily by installing your own handler for
+C<SIGCHLD> after initialising the default loop, and making sure the
+default loop never gets destroyed. You are encouraged, however, to use an
+event-based approach to child reaping and thus use libev's support for
+that, so other libev users can use C<ev_child> watchers freely.
+
+=head3 Watcher-Specific Functions and Data Members
+
+=over 4
+
+=item ev_child_init (ev_child *, callback, int pid, int trace)
+
+=item ev_child_set (ev_child *, int pid, int trace)
+
+Configures the watcher to wait for status changes of process C<pid> (or
+I<any> process if C<pid> is specified as C<0>). The callback can look
+at the C<rstatus> member of the C<ev_child> watcher structure to see
+the status word (use the macros from C<sys/wait.h> and see your systems
+C<waitpid> documentation). The C<rpid> member contains the pid of the
+process causing the status change. C<trace> must be either C<0> (only
+activate the watcher when the process terminates) or C<1> (additionally
+activate the watcher when the process is stopped or continued).
+
+=item int pid [read-only]
+
+The process id this watcher watches out for, or C<0>, meaning any process id.
+
+=item int rpid [read-write]
+
+The process id that detected a status change.
+
+=item int rstatus [read-write]
+
+The process exit/trace status caused by C<rpid> (see your systems
+C<waitpid> and C<sys/wait.h> documentation for details).
+
+=back
+
+=head3 Examples
+
+Example: C<fork()> a new process and install a child handler to wait for
+its completion.
+
+  ev_child cw;
+
+  static void
+  child_cb (EV_P_ struct ev_child *w, int revents)
+  {
+    ev_child_stop (EV_A_ w);
+    printf ("process %d exited with status %x\n", w->rpid, w->rstatus);
+  }
+
+  pid_t pid = fork ();
+
+  if (pid < 0)
+    // error
+  else if (pid == 0)
+    {
+      // the forked child executes here
+      exit (1);
+    }
+  else
+    {
+      ev_child_init (&cw, child_cb, pid, 0);
+      ev_child_start (EV_DEFAULT_ &cw);
+    }
+
+
+=head2 C<ev_stat> - did the file attributes just change?
+
+This watches a filesystem path for attribute changes. That is, it calls
+C<stat> regularly (or when the OS says it changed) and sees if it changed
+compared to the last time, invoking the callback if it did.
+
+The path does not need to exist: changing from "path exists" to "path does
+not exist" is a status change like any other. The condition "path does
+not exist" is signified by the C<st_nlink> field being zero (which is
+otherwise always forced to be at least one) and all the other fields of
+the stat buffer having unspecified contents.
+
+The path I<should> be absolute and I<must not> end in a slash. If it is
+relative and your working directory changes, the behaviour is undefined.
+
+Since there is no standard to do this, the portable implementation simply
+calls C<stat (2)> regularly on the path to see if it changed somehow. You
+can specify a recommended polling interval for this case. If you specify
+a polling interval of C<0> (highly recommended!) then a I<suitable,
+unspecified default> value will be used (which you can expect to be around
+five seconds, although this might change dynamically). Libev will also
+impose a minimum interval which is currently around C<0.1>, but thats
+usually overkill.
+
+This watcher type is not meant for massive numbers of stat watchers,
+as even with OS-supported change notifications, this can be
+resource-intensive.
+
+At the time of this writing, only the Linux inotify interface is
+implemented (implementing kqueue support is left as an exercise for the
+reader). Inotify will be used to give hints only and should not change the
+semantics of C<ev_stat> watchers, which means that libev sometimes needs
+to fall back to regular polling again even with inotify, but changes are
+usually detected immediately, and if the file exists there will be no
+polling.
+
+=head3 ABI Issues (Largefile Support)
+
+Libev by default (unless the user overrides this) uses the default
+compilation environment, which means that on systems with optionally
+disabled large file support, you get the 32 bit version of the stat
+structure. When using the library from programs that change the ABI to
+use 64 bit file offsets the programs will fail. In that case you have to
+compile libev with the same flags to get binary compatibility. This is
+obviously the case with any flags that change the ABI, but the problem is
+most noticably with ev_stat and largefile support.
+
+=head3 Inotify
+
+When C<inotify (7)> support has been compiled into libev (generally only
+available on Linux) and present at runtime, it will be used to speed up
+change detection where possible. The inotify descriptor will be created lazily
+when the first C<ev_stat> watcher is being started.
+
+Inotify presense does not change the semantics of C<ev_stat> watchers
+except that changes might be detected earlier, and in some cases, to avoid
+making regular C<stat> calls. Even in the presense of inotify support
+there are many cases where libev has to resort to regular C<stat> polling.
+
+(There is no support for kqueue, as apparently it cannot be used to
+implement this functionality, due to the requirement of having a file
+descriptor open on the object at all times).
+
+=head3 The special problem of stat time resolution
+
+The C<stat ()> syscall only supports full-second resolution portably, and
+even on systems where the resolution is higher, many filesystems still
+only support whole seconds.
+
+That means that, if the time is the only thing that changes, you might
+miss updates: on the first update, C<ev_stat> detects a change and calls
+your callback, which does something. When there is another update within
+the same second, C<ev_stat> will be unable to detect it.
+
+The solution to this is to delay acting on a change for a second (or till
+the next second boundary), using a roughly one-second delay C<ev_timer>
+(C<ev_timer_set (w, 0., 1.01); ev_timer_again (loop, w)>). The C<.01>
+is added to work around small timing inconsistencies of some operating
+systems.
+
+=head3 Watcher-Specific Functions and Data Members
+
+=over 4
+
+=item ev_stat_init (ev_stat *, callback, const char *path, ev_tstamp interval)
+
+=item ev_stat_set (ev_stat *, const char *path, ev_tstamp interval)
+
+Configures the watcher to wait for status changes of the given
+C<path>. The C<interval> is a hint on how quickly a change is expected to
+be detected and should normally be specified as C<0> to let libev choose
+a suitable value. The memory pointed to by C<path> must point to the same
+path for as long as the watcher is active.
+
+The callback will be receive C<EV_STAT> when a change was detected,
+relative to the attributes at the time the watcher was started (or the
+last change was detected).
+
+=item ev_stat_stat (loop, ev_stat *)
+
+Updates the stat buffer immediately with new values. If you change the
+watched path in your callback, you could call this fucntion to avoid
+detecting this change (while introducing a race condition). Can also be
+useful simply to find out the new values.
+
+=item ev_statdata attr [read-only]
+
+The most-recently detected attributes of the file. Although the type is of
+C<ev_statdata>, this is usually the (or one of the) C<struct stat> types
+suitable for your system. If the C<st_nlink> member is C<0>, then there
+was some error while C<stat>ing the file.
+
+=item ev_statdata prev [read-only]
+
+The previous attributes of the file. The callback gets invoked whenever
+C<prev> != C<attr>.
+
+=item ev_tstamp interval [read-only]
+
+The specified interval.
+
+=item const char *path [read-only]
+
+The filesystem path that is being watched.
+
+=back
+
+=head3 Examples
+
+Example: Watch C</etc/passwd> for attribute changes.
+
+  static void
+  passwd_cb (struct ev_loop *loop, ev_stat *w, int revents)
+  {
+    /* /etc/passwd changed in some way */
+    if (w->attr.st_nlink)
+      {
+        printf ("passwd current size  %ld\n", (long)w->attr.st_size);
+        printf ("passwd current atime %ld\n", (long)w->attr.st_mtime);
+        printf ("passwd current mtime %ld\n", (long)w->attr.st_mtime);
+      }
+    else
+      /* you shalt not abuse printf for puts */
+      puts ("wow, /etc/passwd is not there, expect problems. "
+            "if this is windows, they already arrived\n");
+  }
+
+  ...
+  ev_stat passwd;
+
+  ev_stat_init (&passwd, passwd_cb, "/etc/passwd", 0.);
+  ev_stat_start (loop, &passwd);
+
+Example: Like above, but additionally use a one-second delay so we do not
+miss updates (however, frequent updates will delay processing, too, so
+one might do the work both on C<ev_stat> callback invocation I<and> on
+C<ev_timer> callback invocation).
+
+  static ev_stat passwd;
+  static ev_timer timer;
+
+  static void
+  timer_cb (EV_P_ ev_timer *w, int revents)
+  {
+    ev_timer_stop (EV_A_ w);
+
+    /* now it's one second after the most recent passwd change */
+  }
+
+  static void
+  stat_cb (EV_P_ ev_stat *w, int revents)
+  {
+    /* reset the one-second timer */
+    ev_timer_again (EV_A_ &timer);
+  }
+
+  ...
+  ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
+  ev_stat_start (loop, &passwd);
+  ev_timer_init (&timer, timer_cb, 0., 1.01);
+
+
+=head2 C<ev_idle> - when you've got nothing better to do...
+
+Idle watchers trigger events when no other events of the same or higher
+priority are pending (prepare, check and other idle watchers do not
+count).
+
+That is, as long as your process is busy handling sockets or timeouts
+(or even signals, imagine) of the same or higher priority it will not be
+triggered. But when your process is idle (or only lower-priority watchers
+are pending), the idle watchers are being called once per event loop
+iteration - until stopped, that is, or your process receives more events
+and becomes busy again with higher priority stuff.
+
+The most noteworthy effect is that as long as any idle watchers are
+active, the process will not block when waiting for new events.
+
+Apart from keeping your process non-blocking (which is a useful
+effect on its own sometimes), idle watchers are a good place to do
+"pseudo-background processing", or delay processing stuff to after the
+event loop has handled all outstanding events.
+
+=head3 Watcher-Specific Functions and Data Members
+
+=over 4
+
+=item ev_idle_init (ev_signal *, callback)
+
+Initialises and configures the idle watcher - it has no parameters of any
+kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
+believe me.
+
+=back
+
+=head3 Examples
+
+Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the
+callback, free it. Also, use no error checking, as usual.
+
+  static void
+  idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents)
+  {
+    free (w);
+    // now do something you wanted to do when the program has
+    // no longer anything immediate to do.
+  }
+
+  struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
+  ev_idle_init (idle_watcher, idle_cb);
+  ev_idle_start (loop, idle_cb);
+
+
+=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
+
+Prepare and check watchers are usually (but not always) used in tandem:
+prepare watchers get invoked before the process blocks and check watchers
+afterwards.
+
+You I<must not> call C<ev_loop> or similar functions that enter
+the current event loop from either C<ev_prepare> or C<ev_check>
+watchers. Other loops than the current one are fine, however. The
+rationale behind this is that you do not need to check for recursion in
+those watchers, i.e. the sequence will always be C<ev_prepare>, blocking,
+C<ev_check> so if you have one watcher of each kind they will always be
+called in pairs bracketing the blocking call.
+
+Their main purpose is to integrate other event mechanisms into libev and
+their use is somewhat advanced. This could be used, for example, to track
+variable changes, implement your own watchers, integrate net-snmp or a
+coroutine library and lots more. They are also occasionally useful if
+you cache some data and want to flush it before blocking (for example,
+in X programs you might want to do an C<XFlush ()> in an C<ev_prepare>
+watcher).
+
+This is done by examining in each prepare call which file descriptors need
+to be watched by the other library, registering C<ev_io> watchers for
+them and starting an C<ev_timer> watcher for any timeouts (many libraries
+provide just this functionality). Then, in the check watcher you check for
+any events that occured (by checking the pending status of all watchers
+and stopping them) and call back into the library. The I/O and timer
+callbacks will never actually be called (but must be valid nevertheless,
+because you never know, you know?).
+
+As another example, the Perl Coro module uses these hooks to integrate
+coroutines into libev programs, by yielding to other active coroutines
+during each prepare and only letting the process block if no coroutines
+are ready to run (it's actually more complicated: it only runs coroutines
+with priority higher than or equal to the event loop and one coroutine
+of lower priority, but only once, using idle watchers to keep the event
+loop from blocking if lower-priority coroutines are active, thus mapping
+low-priority coroutines to idle/background tasks).
+
+It is recommended to give C<ev_check> watchers highest (C<EV_MAXPRI>)
+priority, to ensure that they are being run before any other watchers
+after the poll. Also, C<ev_check> watchers (and C<ev_prepare> watchers,
+too) should not activate ("feed") events into libev. While libev fully
+supports this, they will be called before other C<ev_check> watchers
+did their job. As C<ev_check> watchers are often used to embed other
+(non-libev) event loops those other event loops might be in an unusable
+state until their C<ev_check> watcher ran (always remind yourself to
+coexist peacefully with others).
+
+=head3 Watcher-Specific Functions and Data Members
+
+=over 4
+
+=item ev_prepare_init (ev_prepare *, callback)
+
+=item ev_check_init (ev_check *, callback)
+
+Initialises and configures the prepare or check watcher - they have no
+parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
+macros, but using them is utterly, utterly and completely pointless.
+
+=back
+
+=head3 Examples
+
+There are a number of principal ways to embed other event loops or modules
+into libev. Here are some ideas on how to include libadns into libev
+(there is a Perl module named C<EV::ADNS> that does this, which you could
+use for an actually working example. Another Perl module named C<EV::Glib>
+embeds a Glib main context into libev, and finally, C<Glib::EV> embeds EV
+into the Glib event loop).
+
+Method 1: Add IO watchers and a timeout watcher in a prepare handler,
+and in a check watcher, destroy them and call into libadns. What follows
+is pseudo-code only of course. This requires you to either use a low
+priority for the check watcher or use C<ev_clear_pending> explicitly, as
+the callbacks for the IO/timeout watchers might not have been called yet.
+
+  static ev_io iow [nfd];
+  static ev_timer tw;
+
+  static void
+  io_cb (ev_loop *loop, ev_io *w, int revents)
+  {
+  }
+
+  // create io watchers for each fd and a timer before blocking
+  static void
+  adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
+  {
+    int timeout = 3600000;
+    struct pollfd fds [nfd];
+    // actual code will need to loop here and realloc etc.
+    adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
+
+    /* the callback is illegal, but won't be called as we stop during check */
+    ev_timer_init (&tw, 0, timeout * 1e-3);
+    ev_timer_start (loop, &tw);
+
+    // create one ev_io per pollfd
+    for (int i = 0; i < nfd; ++i)
+      {
+        ev_io_init (iow + i, io_cb, fds [i].fd,
+          ((fds [i].events & POLLIN ? EV_READ : 0)
+           | (fds [i].events & POLLOUT ? EV_WRITE : 0)));
+
+        fds [i].revents = 0;
+        ev_io_start (loop, iow + i);
+      }
+  }
+
+  // stop all watchers after blocking
+  static void
+  adns_check_cb (ev_loop *loop, ev_check *w, int revents)
+  {
+    ev_timer_stop (loop, &tw);
+
+    for (int i = 0; i < nfd; ++i)
+      {
+        // set the relevant poll flags
+        // could also call adns_processreadable etc. here
+        struct pollfd *fd = fds + i;
+        int revents = ev_clear_pending (iow + i);
+        if (revents & EV_READ ) fd->revents |= fd->events & POLLIN;
+        if (revents & EV_WRITE) fd->revents |= fd->events & POLLOUT;
+
+        // now stop the watcher
+        ev_io_stop (loop, iow + i);
+      }
+
+    adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
+  }
+
+Method 2: This would be just like method 1, but you run C<adns_afterpoll>
+in the prepare watcher and would dispose of the check watcher.
+
+Method 3: If the module to be embedded supports explicit event
+notification (adns does), you can also make use of the actual watcher
+callbacks, and only destroy/create the watchers in the prepare watcher.
+
+  static void
+  timer_cb (EV_P_ ev_timer *w, int revents)
+  {
+    adns_state ads = (adns_state)w->data;
+    update_now (EV_A);
+
+    adns_processtimeouts (ads, &tv_now);
+  }
+
+  static void
+  io_cb (EV_P_ ev_io *w, int revents)
+  {
+    adns_state ads = (adns_state)w->data;
+    update_now (EV_A);
+
+    if (revents & EV_READ ) adns_processreadable  (ads, w->fd, &tv_now);
+    if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now);
+  }
+
+  // do not ever call adns_afterpoll
+
+Method 4: Do not use a prepare or check watcher because the module you
+want to embed is too inflexible to support it. Instead, youc na override
+their poll function.  The drawback with this solution is that the main
+loop is now no longer controllable by EV. The C<Glib::EV> module does
+this.
+
+  static gint
+  event_poll_func (GPollFD *fds, guint nfds, gint timeout)
+  {
+    int got_events = 0;
+
+    for (n = 0; n < nfds; ++n)
+      // create/start io watcher that sets the relevant bits in fds[n] and increment got_events
+
+    if (timeout >= 0)
+      // create/start timer
+
+    // poll
+    ev_loop (EV_A_ 0);
+
+    // stop timer again
+    if (timeout >= 0)
+      ev_timer_stop (EV_A_ &to);
+
+    // stop io watchers again - their callbacks should have set
+    for (n = 0; n < nfds; ++n)
+      ev_io_stop (EV_A_ iow [n]);
+
+    return got_events;
+  }
+
+
+=head2 C<ev_embed> - when one backend isn't enough...
+
+This is a rather advanced watcher type that lets you embed one event loop
+into another (currently only C<ev_io> events are supported in the embedded
+loop, other types of watchers might be handled in a delayed or incorrect
+fashion and must not be used).
+
+There are primarily two reasons you would want that: work around bugs and
+prioritise I/O.
+
+As an example for a bug workaround, the kqueue backend might only support
+sockets on some platform, so it is unusable as generic backend, but you
+still want to make use of it because you have many sockets and it scales
+so nicely. In this case, you would create a kqueue-based loop and embed it
+into your default loop (which might use e.g. poll). Overall operation will
+be a bit slower because first libev has to poll and then call kevent, but
+at least you can use both at what they are best.
+
+As for prioritising I/O: rarely you have the case where some fds have
+to be watched and handled very quickly (with low latency), and even
+priorities and idle watchers might have too much overhead. In this case
+you would put all the high priority stuff in one loop and all the rest in
+a second one, and embed the second one in the first.
+
+As long as the watcher is active, the callback will be invoked every time
+there might be events pending in the embedded loop. The callback must then
+call C<ev_embed_sweep (mainloop, watcher)> to make a single sweep and invoke
+their callbacks (you could also start an idle watcher to give the embedded
+loop strictly lower priority for example). You can also set the callback
+to C<0>, in which case the embed watcher will automatically execute the
+embedded loop sweep.
+
+As long as the watcher is started it will automatically handle events. The
+callback will be invoked whenever some events have been handled. You can
+set the callback to C<0> to avoid having to specify one if you are not
+interested in that.
+
+Also, there have not currently been made special provisions for forking:
+when you fork, you not only have to call C<ev_loop_fork> on both loops,
+but you will also have to stop and restart any C<ev_embed> watchers
+yourself.
+
+Unfortunately, not all backends are embeddable, only the ones returned by
+C<ev_embeddable_backends> are, which, unfortunately, does not include any
+portable one.
+
+So when you want to use this feature you will always have to be prepared
+that you cannot get an embeddable loop. The recommended way to get around
+this is to have a separate variables for your embeddable loop, try to
+create it, and if that fails, use the normal loop for everything.
+
+=head3 Watcher-Specific Functions and Data Members
+
+=over 4
+
+=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
+
+=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)
+
+Configures the watcher to embed the given loop, which must be
+embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
+invoked automatically, otherwise it is the responsibility of the callback
+to invoke it (it will continue to be called until the sweep has been done,
+if you do not want thta, you need to temporarily stop the embed watcher).
+
+=item ev_embed_sweep (loop, ev_embed *)
+
+Make a single, non-blocking sweep over the embedded loop. This works
+similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
+apropriate way for embedded loops.
+
+=item struct ev_loop *other [read-only]
+
+The embedded event loop.
+
+=back
+
+=head3 Examples
+
+Example: Try to get an embeddable event loop and embed it into the default
+event loop. If that is not possible, use the default loop. The default
+loop is stored in C<loop_hi>, while the mebeddable loop is stored in
+C<loop_lo> (which is C<loop_hi> in the acse no embeddable loop can be
+used).
+
+  struct ev_loop *loop_hi = ev_default_init (0);
+  struct ev_loop *loop_lo = 0;
+  struct ev_embed embed;
+  
+  // see if there is a chance of getting one that works
+  // (remember that a flags value of 0 means autodetection)
+  loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
+    ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
+    : 0;
+
+  // if we got one, then embed it, otherwise default to loop_hi
+  if (loop_lo)
+    {
+      ev_embed_init (&embed, 0, loop_lo);
+      ev_embed_start (loop_hi, &embed);
+    }
+  else
+    loop_lo = loop_hi;
+
+Example: Check if kqueue is available but not recommended and create
+a kqueue backend for use with sockets (which usually work with any
+kqueue implementation). Store the kqueue/socket-only event loop in
+C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too).
+
+  struct ev_loop *loop = ev_default_init (0);
+  struct ev_loop *loop_socket = 0;
+  struct ev_embed embed;
+  
+  if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
+    if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
+      {
+        ev_embed_init (&embed, 0, loop_socket);
+        ev_embed_start (loop, &embed);
+      }
+
+  if (!loop_socket)
+    loop_socket = loop;
+
+  // now use loop_socket for all sockets, and loop for everything else
+
+
+=head2 C<ev_fork> - the audacity to resume the event loop after a fork
+
+Fork watchers are called when a C<fork ()> was detected (usually because
+whoever is a good citizen cared to tell libev about it by calling
+C<ev_default_fork> or C<ev_loop_fork>). The invocation is done before the
+event loop blocks next and before C<ev_check> watchers are being called,
+and only in the child after the fork. If whoever good citizen calling
+C<ev_default_fork> cheats and calls it in the wrong process, the fork
+handlers will be invoked, too, of course.
+
+=head3 Watcher-Specific Functions and Data Members
+
+=over 4
+
+=item ev_fork_init (ev_signal *, callback)
+
+Initialises and configures the fork watcher - it has no parameters of any
+kind. There is a C<ev_fork_set> macro, but using it is utterly pointless,
+believe me.
+
+=back
+
+
+=head2 C<ev_async> - how to wake up another event loop
+
+In general, you cannot use an C<ev_loop> from multiple threads or other
+asynchronous sources such as signal handlers (as opposed to multiple event
+loops - those are of course safe to use in different threads).
+
+Sometimes, however, you need to wake up another event loop you do not
+control, for example because it belongs to another thread. This is what
+C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you
+can signal 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).
+
+Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not
+just the default loop.
+
+=head3 Queueing
+
+C<ev_async> does not support queueing of data in any way. The reason
+is that the author does not know of a simple (or any) algorithm for a
+multiple-writer-single-reader queue that works in all cases and doesn't
+need elaborate support such as pthreads.
+
+That means that if you want to queue data, you have to provide your own
+queue. But at least I can tell you would implement locking around your
+queue:
+
+=over 4
+
+=item queueing from a signal handler context
+
+To implement race-free queueing, you simply add to the queue in the signal
+handler but you block the signal handler in the watcher callback. Here is an example that does that for
+some fictitiuous SIGUSR1 handler:
+
+   static ev_async mysig;
+
+   static void
+   sigusr1_handler (void)
+   {
+     sometype data;
+
+     // no locking etc.
+     queue_put (data);
+     ev_async_send (EV_DEFAULT_ &mysig);
+   }
+
+   static void
+   mysig_cb (EV_P_ ev_async *w, int revents)
+   {
+     sometype data;
+     sigset_t block, prev;
+
+     sigemptyset (&block);
+     sigaddset (&block, SIGUSR1);
+     sigprocmask (SIG_BLOCK, &block, &prev);
+
+     while (queue_get (&data))
+       process (data);
+
+     if (sigismember (&prev, SIGUSR1)
+       sigprocmask (SIG_UNBLOCK, &block, 0);
+   }
+
+(Note: pthreads in theory requires you to use C<pthread_setmask>
+instead of C<sigprocmask> when you use threads, but libev doesn't do it
+either...).
+
+=item queueing from a thread context
+
+The strategy for threads is different, as you cannot (easily) block
+threads but you can easily preempt them, so to queue safely you need to
+employ a traditional mutex lock, such as in this pthread example:
+
+   static ev_async mysig;
+   static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER;
+
+   static void
+   otherthread (void)
+   {
+     // only need to lock the actual queueing operation
+     pthread_mutex_lock (&mymutex);
+     queue_put (data);
+     pthread_mutex_unlock (&mymutex);
+
+     ev_async_send (EV_DEFAULT_ &mysig);
+   }
+
+   static void
+   mysig_cb (EV_P_ ev_async *w, int revents)
+   {
+     pthread_mutex_lock (&mymutex);
+
+     while (queue_get (&data))
+       process (data);
+
+     pthread_mutex_unlock (&mymutex);
+   }
+
+=back
+
+
+=head3 Watcher-Specific Functions and Data Members
+
+=over 4
+
+=item ev_async_init (ev_async *, callback)
+
+Initialises and configures the async watcher - it has no parameters of any
+kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless,
+believe me.
+
+=item ev_async_send (loop, ev_async *)
+
+Sends/signals/activates the given C<ev_async> watcher, that is, feeds
+an C<EV_ASYNC> event on the watcher into the event loop. Unlike
+C<ev_feed_event>, this call is safe to do in other threads, signal or
+similar contexts (see the dicusssion of C<EV_ATOMIC_T> in the embedding
+section below on what exactly this means).
+
+This call incurs the overhead of a syscall only once per loop iteration,
+so while the overhead might be noticable, it doesn't apply to repeated
+calls to C<ev_async_send>.
+
+=item bool = ev_async_pending (ev_async *)
+
+Returns a non-zero value when C<ev_async_send> has been called on the
+watcher but the event has not yet been processed (or even noted) by the
+event loop.
+
+C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
+the loop iterates next and checks for the watcher to have become active,
+it will reset the flag again. C<ev_async_pending> can be used to very
+quickly check wether invoking the loop might be a good idea.
+
+Not that this does I<not> check wether the watcher itself is pending, only
+wether it has been requested to make this watcher pending.
+
+=back
+
+
+=head1 OTHER FUNCTIONS
+
+There are some other functions of possible interest. Described. Here. Now.
+
+=over 4
+
+=item ev_once (loop, int fd, int events, ev_tstamp timeout, callback)
+
+This function combines a simple timer and an I/O watcher, calls your
+callback on whichever event happens first and automatically stop both
+watchers. This is useful if you want to wait for a single event on an fd
+or timeout without having to allocate/configure/start/stop/free one or
+more watchers yourself.
+
+If C<fd> is less than 0, then no I/O watcher will be started and events
+is being ignored. Otherwise, an C<ev_io> watcher for the given C<fd> and
+C<events> set will be craeted and started.
+
+If C<timeout> is less than 0, then no timeout watcher will be
+started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
+repeat = 0) will be started. While C<0> is a valid timeout, it is of
+dubious value.
+
+The callback has the type C<void (*cb)(int revents, void *arg)> and gets
+passed an C<revents> set like normal event callbacks (a combination of
+C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg>
+value passed to C<ev_once>:
+
+  static void stdin_ready (int revents, void *arg)
+  {
+    if (revents & EV_TIMEOUT)
+      /* doh, nothing entered */;
+    else if (revents & EV_READ)
+      /* stdin might have data for us, joy! */;
+  }
+
+  ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
+
+=item ev_feed_event (ev_loop *, watcher *, int revents)
+
+Feeds the given event set into the event loop, as if the specified event
+had happened for the specified watcher (which must be a pointer to an
+initialised but not necessarily started event watcher).
+
+=item ev_feed_fd_event (ev_loop *, int fd, int revents)
+
+Feed an event on the given fd, as if a file descriptor backend detected
+the given events it.
+
+=item ev_feed_signal_event (ev_loop *loop, int signum)
+
+Feed an event as if the given signal occured (C<loop> must be the default
+loop!).
+
+=back
+
+
+=head1 LIBEVENT EMULATION
+
+Libev offers a compatibility emulation layer for libevent. It cannot
+emulate the internals of libevent, so here are some usage hints:
+
+=over 4
+
+=item * Use it by including <event.h>, as usual.
+
+=item * The following members are fully supported: ev_base, ev_callback,
+ev_arg, ev_fd, ev_res, ev_events.
+
+=item * Avoid using ev_flags and the EVLIST_*-macros, while it is
+maintained by libev, it does not work exactly the same way as in libevent (consider
+it a private API).
+
+=item * Priorities are not currently supported. Initialising priorities
+will fail and all watchers will have the same priority, even though there
+is an ev_pri field.
+
+=item * Other members are not supported.
+
+=item * The libev emulation is I<not> ABI compatible to libevent, you need
+to use the libev header file and library.
+
+=back
+
+=head1 C++ SUPPORT
+
+Libev comes with some simplistic wrapper classes for C++ that mainly allow
+you to use some convinience methods to start/stop watchers and also change
+the callback model to a model using method callbacks on objects.
+
+To use it,
+   
+  #include <ev++.h>
+
+This automatically includes F<ev.h> and puts all of its definitions (many
+of them macros) into the global namespace. All C++ specific things are
+put into the C<ev> namespace. It should support all the same embedding
+options as F<ev.h>, most notably C<EV_MULTIPLICITY>.
+
+Care has been taken to keep the overhead low. The only data member the C++
+classes add (compared to plain C-style watchers) is the event loop pointer
+that the watcher is associated with (or no additional members at all if
+you disable C<EV_MULTIPLICITY> when embedding libev).
+
+Currently, functions, and static and non-static member functions can be
+used as callbacks. Other types should be easy to add as long as they only
+need one additional pointer for context. If you need support for other
+types of functors please contact the author (preferably after implementing
+it).
+
+Here is a list of things available in the C<ev> namespace:
+
+=over 4
+
+=item C<ev::READ>, C<ev::WRITE> etc.
+
+These are just enum values with the same values as the C<EV_READ> etc.
+macros from F<ev.h>.
+
+=item C<ev::tstamp>, C<ev::now>
+
+Aliases to the same types/functions as with the C<ev_> prefix.
+
+=item C<ev::io>, C<ev::timer>, C<ev::periodic>, C<ev::idle>, C<ev::sig> etc.
+
+For each C<ev_TYPE> watcher in F<ev.h> there is a corresponding class of
+the same name in the C<ev> namespace, with the exception of C<ev_signal>
+which is called C<ev::sig> to avoid clashes with the C<signal> macro
+defines by many implementations.
+
+All of those classes have these methods:
+
+=over 4
+
+=item ev::TYPE::TYPE ()
+
+=item ev::TYPE::TYPE (struct ev_loop *)
+
+=item ev::TYPE::~TYPE
+
+The constructor (optionally) takes an event loop to associate the watcher
+with. If it is omitted, it will use C<EV_DEFAULT>.
+
+The constructor calls C<ev_init> for you, which means you have to call the
+C<set> method before starting it.
+
+It will not set a callback, however: You have to call the templated C<set>
+method to set a callback before you can start the watcher.
+
+(The reason why you have to use a method is a limitation in C++ which does
+not allow explicit template arguments for constructors).
+
+The destructor automatically stops the watcher if it is active.
+
+=item w->set<class, &class::method> (object *)
+
+This method sets the callback method to call. The method has to have a
+signature of C<void (*)(ev_TYPE &, int)>, it receives the watcher as
+first argument and the C<revents> as second. The object must be given as
+parameter and is stored in the C<data> member of the watcher.
+
+This method synthesizes efficient thunking code to call your method from
+the C callback that libev requires. If your compiler can inline your
+callback (i.e. it is visible to it at the place of the C<set> call and
+your compiler is good :), then the method will be fully inlined into the
+thunking function, making it as fast as a direct C callback.
+
+Example: simple class declaration and watcher initialisation
+
+  struct myclass
+  {
+    void io_cb (ev::io &w, int revents) { }
+  }
+
+  myclass obj;
+  ev::io iow;
+  iow.set <myclass, &myclass::io_cb> (&obj);
+
+=item w->set<function> (void *data = 0)
+
+Also sets a callback, but uses a static method or plain function as
+callback. The optional C<data> argument will be stored in the watcher's
+C<data> member and is free for you to use.
+
+The prototype of the C<function> must be C<void (*)(ev::TYPE &w, int)>.
+
+See the method-C<set> above for more details.
+
+Example:
+
+  static void io_cb (ev::io &w, int revents) { }
+  iow.set <io_cb> ();
+
+=item w->set (struct ev_loop *)
+
+Associates a different C<struct ev_loop> with this watcher. You can only
+do this when the watcher is inactive (and not pending either).
+
+=item w->set ([args])
+
+Basically the same as C<ev_TYPE_set>, with the same args. Must be
+called at least once. Unlike the C counterpart, an active watcher gets
+automatically stopped and restarted when reconfiguring it with this
+method.
+
+=item w->start ()
+
+Starts the watcher. Note that there is no C<loop> argument, as the
+constructor already stores the event loop.
+
+=item w->stop ()
+
+Stops the watcher if it is active. Again, no C<loop> argument.
+
+=item w->again () (C<ev::timer>, C<ev::periodic> only)
+
+For C<ev::timer> and C<ev::periodic>, this invokes the corresponding
+C<ev_TYPE_again> function.
+
+=item w->sweep () (C<ev::embed> only)
+
+Invokes C<ev_embed_sweep>.
+
+=item w->update () (C<ev::stat> only)
+
+Invokes C<ev_stat_stat>.
+
+=back
+
+=back
+
+Example: Define a class with an IO and idle watcher, start one of them in
+the constructor.
+
+  class myclass
+  {
+    ev::io   io;  void io_cb   (ev::io   &w, int revents);
+    ev:idle idle  void idle_cb (ev::idle &w, int revents);
+
+    myclass (int fd)
+    {
+      io  .set <myclass, &myclass::io_cb  > (this);
+      idle.set <myclass, &myclass::idle_cb> (this);
+
+      io.start (fd, ev::READ);
+    }
+  };
+
+
+=head1 OTHER LANGUAGE BINDINGS
+
+Libev does not offer other language bindings itself, but bindings for a
+numbe rof languages exist in the form of third-party packages. If you know
+any interesting language binding in addition to the ones listed here, drop
+me a note.
+
+=over 4
+
+=item Perl
+
+The EV module implements the full libev API and is actually used to test
+libev. EV is developed together with libev. Apart from the EV core module,
+there are additional modules that implement libev-compatible interfaces
+to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the
+C<libglib> event core (C<Glib::EV> and C<EV::Glib>).
+
+It can be found and installed via CPAN, its homepage is found at
+L<http://software.schmorp.de/pkg/EV>.
+
+=item Ruby
+
+Tony Arcieri has written a ruby extension that offers access to a subset
+of the libev API and adds filehandle abstractions, asynchronous DNS and
+more on top of it. It can be found via gem servers. Its homepage is at
+L<http://rev.rubyforge.org/>.
+
+=item D
+
+Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
+be found at L<http://git.llucax.com.ar/?p=software/ev.d.git;a=summary>.
+
+=back
+
+
+=head1 MACRO MAGIC
+
+Libev can be compiled with a variety of options, the most fundamantal
+of which is C<EV_MULTIPLICITY>. This option determines whether (most)
+functions and callbacks have an initial C<struct ev_loop *> argument.
+
+To make it easier to write programs that cope with either variant, the
+following macros are defined:
+
+=over 4
+
+=item C<EV_A>, C<EV_A_>
+
+This provides the loop I<argument> for functions, if one is required ("ev
+loop argument"). The C<EV_A> form is used when this is the sole argument,
+C<EV_A_> is used when other arguments are following. Example:
+
+  ev_unref (EV_A);
+  ev_timer_add (EV_A_ watcher);
+  ev_loop (EV_A_ 0);
+
+It assumes the variable C<loop> of type C<struct ev_loop *> is in scope,
+which is often provided by the following macro.
+
+=item C<EV_P>, C<EV_P_>
+
+This provides the loop I<parameter> for functions, if one is required ("ev
+loop parameter"). The C<EV_P> form is used when this is the sole parameter,
+C<EV_P_> is used when other parameters are following. Example:
+
+  // this is how ev_unref is being declared
+  static void ev_unref (EV_P);
+
+  // this is how you can declare your typical callback
+  static void cb (EV_P_ ev_timer *w, int revents)
+
+It declares a parameter C<loop> of type C<struct ev_loop *>, quite
+suitable for use with C<EV_A>.
+
+=item C<EV_DEFAULT>, C<EV_DEFAULT_>
+
+Similar to the other two macros, this gives you the value of the default
+loop, if multiple loops are supported ("ev loop default").
+
+=back
+
+Example: Declare and initialise a check watcher, utilising the above
+macros so it will work regardless of whether multiple loops are supported
+or not.
+
+  static void
+  check_cb (EV_P_ ev_timer *w, int revents)
+  {
+    ev_check_stop (EV_A_ w);
+  }
+
+  ev_check check;
+  ev_check_init (&check, check_cb);
+  ev_check_start (EV_DEFAULT_ &check);
+  ev_loop (EV_DEFAULT_ 0);
+
+=head1 EMBEDDING
+
+Libev can (and often is) directly embedded into host
+applications. Examples of applications that embed it include the Deliantra
+Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
+and rxvt-unicode.
+
+The goal is to enable you to just copy the necessary files into your
+source directory without having to change even a single line in them, so
+you can easily upgrade by simply copying (or having a checked-out copy of
+libev somewhere in your source tree).
+
+=head2 FILESETS
+
+Depending on what features you need you need to include one or more sets of files
+in your app.
+
+=head3 CORE EVENT LOOP
+
+To include only the libev core (all the C<ev_*> functions), with manual
+configuration (no autoconf):
+
+  #define EV_STANDALONE 1
+  #include "ev.c"
+
+This will automatically include F<ev.h>, too, and should be done in a
+single C source file only to provide the function implementations. To use
+it, do the same for F<ev.h> in all files wishing to use this API (best
+done by writing a wrapper around F<ev.h> that you can include instead and
+where you can put other configuration options):
+
+  #define EV_STANDALONE 1
+  #include "ev.h"
+
+Both header files and implementation files can be compiled with a C++
+compiler (at least, thats a stated goal, and breakage will be treated
+as a bug).
+
+You need the following files in your source tree, or in a directory
+in your include path (e.g. in libev/ when using -Ilibev):
+
+  ev.h
+  ev.c
+  ev_vars.h
+  ev_wrap.h
+
+  ev_win32.c      required on win32 platforms only
+
+  ev_select.c     only when select backend is enabled (which is enabled by default)
+  ev_poll.c       only when poll backend is enabled (disabled by default)
+  ev_epoll.c      only when the epoll backend is enabled (disabled by default)
+  ev_kqueue.c     only when the kqueue backend is enabled (disabled by default)
+  ev_port.c       only when the solaris port backend is enabled (disabled by default)
+
+F<ev.c> includes the backend files directly when enabled, so you only need
+to compile this single file.
+
+=head3 LIBEVENT COMPATIBILITY API
+
+To include the libevent compatibility API, also include:
+
+  #include "event.c"
+
+in the file including F<ev.c>, and:
+
+  #include "event.h"
+
+in the files that want to use the libevent API. This also includes F<ev.h>.
+
+You need the following additional files for this:
+
+  event.h
+  event.c
+
+=head3 AUTOCONF SUPPORT
+
+Instead of using C<EV_STANDALONE=1> and providing your config in
+whatever way you want, you can also C<m4_include([libev.m4])> in your
+F<configure.ac> and leave C<EV_STANDALONE> undefined. F<ev.c> will then
+include F<config.h> and configure itself accordingly.
+
+For this of course you need the m4 file:
+
+  libev.m4
+
+=head2 PREPROCESSOR SYMBOLS/MACROS
+
+Libev can be configured via a variety of preprocessor symbols you have to define
+before including any of its files. The default is not to build for multiplicity
+and only include the select backend.
+
+=over 4
+
+=item EV_STANDALONE
+
+Must always be C<1> if you do not use autoconf configuration, which
+keeps libev from including F<config.h>, and it also defines dummy
+implementations for some libevent functions (such as logging, which is not
+supported). It will also not define any of the structs usually found in
+F<event.h> that are not directly supported by the libev core alone.
+
+=item EV_USE_MONOTONIC
+
+If defined to be C<1>, libev will try to detect the availability of the
+monotonic clock option at both compiletime and runtime. Otherwise no use
+of the monotonic clock option will be attempted. If you enable this, you
+usually have to link against librt or something similar. Enabling it when
+the functionality isn't available is safe, though, although you have
+to make sure you link against any libraries where the C<clock_gettime>
+function is hiding in (often F<-lrt>).
+
+=item EV_USE_REALTIME
+
+If defined to be C<1>, libev will try to detect the availability of the
+realtime clock option at compiletime (and assume its availability at
+runtime if successful). Otherwise no use of the realtime clock option will
+be attempted. This effectively replaces C<gettimeofday> by C<clock_get
+(CLOCK_REALTIME, ...)> and will not normally affect correctness. See the
+note about libraries in the description of C<EV_USE_MONOTONIC>, though.
+
+=item EV_USE_NANOSLEEP
+
+If defined to be C<1>, libev will assume that C<nanosleep ()> is available
+and will use it for delays. Otherwise it will use C<select ()>.
+
+=item EV_USE_SELECT
+
+If undefined or defined to be C<1>, libev will compile in support for the
+C<select>(2) backend. No attempt at autodetection will be done: if no
+other method takes over, select will be it. Otherwise the select backend
+will not be compiled in.
+
+=item EV_SELECT_USE_FD_SET
+
+If defined to C<1>, then the select backend will use the system C<fd_set>
+structure. This is useful if libev doesn't compile due to a missing
+C<NFDBITS> or C<fd_mask> definition or it misguesses the bitset layout on
+exotic systems. This usually limits the range of file descriptors to some
+low limit such as 1024 or might have other limitations (winsocket only
+allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might
+influence the size of the C<fd_set> used.
+
+=item EV_SELECT_IS_WINSOCKET
+
+When defined to C<1>, the select backend will assume that
+select/socket/connect etc. don't understand file descriptors but
+wants osf handles on win32 (this is the case when the select to
+be used is the winsock select). This means that it will call
+C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
+it is assumed that all these functions actually work on fds, even
+on win32. Should not be defined on non-win32 platforms.
+
+=item EV_FD_TO_WIN32_HANDLE
+
+If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
+file descriptors to socket handles. When not defining this symbol (the
+default), then libev will call C<_get_osfhandle>, which is usually
+correct. In some cases, programs use their own file descriptor management,
+in which case they can provide this function to map fds to socket handles.
+
+=item EV_USE_POLL
+
+If defined to be C<1>, libev will compile in support for the C<poll>(2)
+backend. Otherwise it will be enabled on non-win32 platforms. It
+takes precedence over select.
+
+=item EV_USE_EPOLL
+
+If defined to be C<1>, libev will compile in support for the Linux
+C<epoll>(7) backend. Its availability will be detected at runtime,
+otherwise another method will be used as fallback. This is the
+preferred backend for GNU/Linux systems.
+
+=item EV_USE_KQUEUE
+
+If defined to be C<1>, libev will compile in support for the BSD style
+C<kqueue>(2) backend. Its actual availability will be detected at runtime,
+otherwise another method will be used as fallback. This is the preferred
+backend for BSD and BSD-like systems, although on most BSDs kqueue only
+supports some types of fds correctly (the only platform we found that
+supports ptys for example was NetBSD), so kqueue might be compiled in, but
+not be used unless explicitly requested. The best way to use it is to find
+out whether kqueue supports your type of fd properly and use an embedded
+kqueue loop.
+
+=item EV_USE_PORT
+
+If defined to be C<1>, libev will compile in support for the Solaris
+10 port style backend. Its availability will be detected at runtime,
+otherwise another method will be used as fallback. This is the preferred
+backend for Solaris 10 systems.
+
+=item EV_USE_DEVPOLL
+
+reserved for future expansion, works like the USE symbols above.
+
+=item EV_USE_INOTIFY
+
+If defined to be C<1>, libev will compile in support for the Linux inotify
+interface to speed up C<ev_stat> watchers. Its actual availability will
+be detected at runtime.
+
+=item EV_ATOMIC_T
+
+Libev requires an integer type (suitable for storing C<0> or C<1>) whose
+access is atomic with respect to other threads or signal contexts. No such
+type is easily found in the C language, so you can provide your own type
+that you know is safe for your purposes. It is used both for signal handler "locking"
+as well as for signal and thread safety in C<ev_async> watchers.
+
+In the absense of this define, libev will use C<sig_atomic_t volatile>
+(from F<signal.h>), which is usually good enough on most platforms.
+
+=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>, 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
+
+If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
+F<ev.c>'s idea of where to find the F<config.h> file, similarly to
+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 default is C<"event.h">.
+
+=item EV_PROTOTYPES
+
+If defined to be C<0>, then F<ev.h> will not define any function
+prototypes, but still define all the structs and other symbols. This is
+occasionally useful if you want to provide your own wrapper functions
+around libev functions.
+
+=item EV_MULTIPLICITY
+
+If undefined or defined to C<1>, then all event-loop-specific functions
+will have the C<struct ev_loop *> as first argument, and you can create
+additional independent event loops. Otherwise there will be no support
+for multiple event loops and there is no first event loop pointer
+argument. Instead, all functions act on the single default loop.
+
+=item EV_MINPRI
+
+=item EV_MAXPRI
+
+The range of allowed priorities. C<EV_MINPRI> must be smaller or equal to
+C<EV_MAXPRI>, but otherwise there are no non-obvious limitations. You can
+provide for more priorities by overriding those symbols (usually defined
+to be C<-2> and C<2>, respectively).
+
+When doing priority-based operations, libev usually has to linearly search
+all the priorities, so having many of them (hundreds) uses a lot of space
+and time, so using the defaults of five priorities (-2 .. +2) is usually
+fine.
+
+If your embedding app does not need any priorities, defining these both to
+C<0> will save some memory and cpu.
+
+=item EV_PERIODIC_ENABLE
+
+If undefined or defined to be C<1>, then periodic timers are supported. If
+defined to be C<0>, then they are not. Disabling them saves a few kB of
+code.
+
+=item EV_IDLE_ENABLE
+
+If undefined or defined to be C<1>, then idle watchers are supported. If
+defined to be C<0>, then they are not. Disabling them saves a few kB of
+code.
+
+=item EV_EMBED_ENABLE
+
+If undefined or defined to be C<1>, then embed watchers are supported. If
+defined to be C<0>, then they are not.
+
+=item EV_STAT_ENABLE
+
+If undefined or defined to be C<1>, then stat watchers are supported. If
+defined to be C<0>, then they are not.
+
+=item EV_FORK_ENABLE
+
+If undefined or defined to be C<1>, then fork watchers are supported. If
+defined to be C<0>, then they are not.
+
+=item EV_ASYNC_ENABLE
+
+If undefined or defined to be C<1>, then async watchers are supported. If
+defined to be C<0>, then they are not.
+
+=item EV_MINIMAL
+
+If you need to shave off some kilobytes of code at the expense of some
+speed, define this symbol to C<1>. Currently only used for gcc to override
+some inlining decisions, saves roughly 30% codesize of amd64.
+
+=item EV_PID_HASHSIZE
+
+C<ev_child> watchers use a small hash table to distribute workload by
+pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
+than enough. If you need to manage thousands of children you might want to
+increase this value (I<must> be a power of two).
+
+=item EV_INOTIFY_HASHSIZE
+
+C<ev_stat> watchers use a small hash table to distribute workload by
+inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>),
+usually more than enough. If you need to manage thousands of C<ev_stat>
+watchers you might want to increase this value (I<must> be a power of
+two).
+
+=item EV_COMMON
+
+By default, all watchers have a C<void *data> member. By redefining
+this macro to a something else you can include more and other types of
+members. You have to define it each time you include one of the files,
+though, and it must be identical each time.
+
+For example, the perl EV module uses something like this:
+
+  #define EV_COMMON                       \
+    SV *self; /* contains this struct */  \
+    SV *cb_sv, *fh /* note no trailing ";" */
+
+=item EV_CB_DECLARE (type)
+
+=item EV_CB_INVOKE (watcher, revents)
+
+=item ev_set_cb (ev, cb)
+
+Can be used to change the callback member declaration in each watcher,
+and the way callbacks are invoked and set. Must expand to a struct member
+definition and a statement, respectively. See the F<ev.h> header file for
+their default definitions. One possible use for overriding these is to
+avoid the C<struct ev_loop *> as first argument in all cases, or to use
+method calls instead of plain function calls in C++.
+
+=head2 EXPORTED API SYMBOLS
+
+If you need to re-export the API (e.g. via a dll) and you need a list of
+exported symbols, you can use the provided F<Symbol.*> files which list
+all public symbols, one per line:
+
+  Symbols.ev      for libev proper
+  Symbols.event   for the libevent emulation
+
+This can also be used to rename all public symbols to avoid clashes with
+multiple versions of libev linked together (which is obviously bad in
+itself, but sometimes it is inconvinient to avoid this).
+
+A sed command like this will create wrapper C<#define>'s that you need to
+include before including F<ev.h>:
+
+   <Symbols.ev sed -e "s/.*/#define & myprefix_&/" >wrap.h
+
+This would create a file F<wrap.h> which essentially looks like this:
+
+   #define ev_backend     myprefix_ev_backend
+   #define ev_check_start myprefix_ev_check_start
+   #define ev_check_stop  myprefix_ev_check_stop
+   ...
+
+=head2 EXAMPLES
+
+For a real-world example of a program the includes libev
+verbatim, you can have a look at the EV perl module
+(L<http://software.schmorp.de/pkg/EV.html>). It has the libev files in
+the F<libev/> subdirectory and includes them in the F<EV/EVAPI.h> (public
+interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file
+will be compiled. It is pretty complex because it provides its own header
+file.
+
+The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
+that everybody includes and which overrides some configure choices:
+
+  #define EV_MINIMAL 1
+  #define EV_USE_POLL 0
+  #define EV_MULTIPLICITY 0
+  #define EV_PERIODIC_ENABLE 0
+  #define EV_STAT_ENABLE 0
+  #define EV_FORK_ENABLE 0
+  #define EV_CONFIG_H <config.h>
+  #define EV_MINPRI 0
+  #define EV_MAXPRI 0
+
+  #include "ev++.h"
+
+And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
+
+  #include "ev_cpp.h"
+  #include "ev.c"
+
+
+=head1 COMPLEXITIES
+
+In this section the complexities of (many of) the algorithms used inside
+libev will be explained. For complexity discussions about backends see the
+documentation for C<ev_default_init>.
+
+All of the following are about amortised time: If an array needs to be
+extended, libev needs to realloc and move the whole array, but this
+happens asymptotically never with higher number of elements, so O(1) might
+mean it might do a lengthy realloc operation in rare cases, but on average
+it is much faster and asymptotically approaches constant time.
+
+=over 4
+
+=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
+
+This means that, when you have a watcher that triggers in one hour and
+there are 100 watchers that would trigger before that then inserting will
+have to skip roughly seven (C<ld 100>) of these watchers.
+
+=item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
+
+That means that changing a timer costs less than removing/adding them
+as only the relative motion in the event queue has to be paid for.
+
+=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)
+
+These just add the watcher into an array or at the head of a list.
+
+=item Stopping check/prepare/idle/fork/async watchers: O(1)
+
+=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
+
+These watchers are stored in lists then need to be walked to find the
+correct watcher to remove. The lists are usually short (you don't usually
+have many watchers waiting for the same fd or signal).
+
+=item Finding the next timer in each loop iteration: O(1)
+
+By virtue of using a binary heap, the next timer is always found at the
+beginning of the storage array.
+
+=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
+
+A change means an I/O watcher gets started or stopped, which requires
+libev to recalculate its status (and possibly tell the kernel, depending
+on backend and wether C<ev_io_set> was used).
+
+=item Activating one watcher (putting it into the pending state): O(1)
+
+=item Priority handling: O(number_of_priorities)
+
+Priorities are implemented by allocating some space for each
+priority. When doing priority-based operations, libev usually has to
+linearly search all the priorities, but starting/stopping and activating
+watchers becomes O(1) w.r.t. priority handling.
+
+=item Sending an ev_async: O(1)
+
+=item Processing ev_async_send: O(number_of_async_watchers)
+
+=item Processing signals: O(max_signal_number)
+
+Sending involves a syscall I<iff> there were no other C<ev_async_send>
+calls in the current loop iteration. Checking for async and signal events
+involves iterating over all running async watchers or all signal numbers.
+
+=back
+
+
+=head1 Win32 platform limitations and workarounds
+
+Win32 doesn't support any of the standards (e.g. POSIX) that libev
+requires, and its I/O model is fundamentally incompatible with the POSIX
+model. Libev still offers limited functionality on this platform in
+the form of the C<EVBACKEND_SELECT> backend, and only supports socket
+descriptors. This only applies when using Win32 natively, not when using
+e.g. cygwin.
+
+There is no supported compilation method available on windows except
+embedding it into other applications.
+
+Due to the many, low, and arbitrary limits on the win32 platform and the
+abysmal performance of winsockets, using a large number of sockets is not
+recommended (and not reasonable). If your program needs to use more than
+a hundred or so sockets, then likely it needs to use a totally different
+implementation for windows, as libev offers the POSIX model, which cannot
+be implemented efficiently on windows (microsoft monopoly games).
+
+=over 4
+
+=item The winsocket select function
+
+The winsocket C<select> function doesn't follow POSIX in that it requires
+socket I<handles> and not socket I<file descriptors>. This makes select
+very inefficient, and also requires a mapping from file descriptors
+to socket handles. See the discussion of the C<EV_SELECT_USE_FD_SET>,
+C<EV_SELECT_IS_WINSOCKET> and C<EV_FD_TO_WIN32_HANDLE> preprocessor
+symbols for more info.
+
+The configuration for a "naked" win32 using the microsoft runtime
+libraries and raw winsocket select is:
+
+  #define EV_USE_SELECT 1
+  #define EV_SELECT_IS_WINSOCKET 1   /* forces EV_SELECT_USE_FD_SET, too */
+
+Note that winsockets handling of fd sets is O(n), so you can easily get a
+complexity in the O(n²) range when using win32.
+
+=item Limited number of file descriptors
+
+Windows has numerous arbitrary (and low) limits on things. Early versions
+of winsocket's select only supported waiting for a max. of C<64> handles
+(probably owning to the fact that all windows kernels can only wait for
+C<64> things at the same time internally; microsoft recommends spawning a
+chain of threads and wait for 63 handles and the previous thread in each).
+
+Newer versions support more handles, but you need to define C<FD_SETSIZE>
+to some high number (e.g. C<2048>) before compiling the winsocket select
+call (which might be in libev or elsewhere, for example, perl does its own
+select emulation on windows).
+
+Another limit is the number of file descriptors in the microsoft runtime
+libraries, which by default is C<64> (there must be a hidden I<64> fetish
+or something like this inside microsoft). You can increase this by calling
+C<_setmaxstdio>, which can increase this limit to C<2048> (another
+arbitrary limit), but is broken in many versions of the microsoft runtime
+libraries.
+
+This might get you to about C<512> or C<2048> sockets (depending on
+windows version and/or the phase of the moon). To get more, you need to
+wrap all I/O functions and provide your own fd management, but the cost of
+calling select (O(n²)) will likely make this unworkable.
+
+=back
+
+
+=head1 AUTHOR
+
+Marc Lehmann <libev@schmorp.de>.
+