--- libev/ev.pod	2010/03/09 08:46:17	1.281
+++ libev/ev.pod	2010/03/24 18:27:13	1.293
@@ -126,13 +126,14 @@
 =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. When you need to do any calculations
-on it, you should treat it as some floating point value. Unlike the name
-component C<stamp> might indicate, it is also used for time differences
-throughout libev.
+the (fractional) number of seconds since the (POSIX) epoch (in practise
+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. When you need to do
+any calculations on it, you should treat it as some floating point value.
+
+Unlike the name component C<stamp> might indicate, it is also used for
+time differences (e.g. delays) throughout libev.
 
 =head1 ERROR HANDLING
 
@@ -347,9 +348,8 @@
 
 =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.
+Instead of calling 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
@@ -569,11 +569,9 @@
 =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).
+always distinct from the default loop.
 
-Note that this function I<is> thread-safe, and the recommended way to use
+Note that this function I<is> thread-safe, and one common 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.
 
@@ -585,13 +583,12 @@
 
 =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 yourself 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).
+Destroys the default loop (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 yourself 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 (and installed signal
 handlers), will not be freed by this function, and related watchers (such
@@ -616,9 +613,15 @@
 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.
 
+Again, you I<have> to call it on I<any> loop that you want to re-use after 
+a fork, I<even if you do not plan to use the loop in the parent>. This is
+because some kernel interfaces *cough* I<kqueue> *cough* do funny things
+during fork.
+
 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.
+process if and only if you want to use the event loop in the child. If you
+just fork+exec or create a new loop in the child, 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
@@ -630,25 +633,26 @@
 
 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 that you want to re-use in the child, and how you do this is
-entirely your own problem.
+after fork that you want to re-use in the child, and how you keep track of 
+them is entirely your own problem.
 
 =item int ev_is_default_loop (loop)
 
 Returns true when the given loop is, in fact, the default loop, and false
 otherwise.
 
-=item unsigned int ev_loop_count (loop)
+=item unsigned int ev_iteration (loop)
 
-Returns the count of loop iterations for the loop, which is identical to
+Returns the current iteration count 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.
+C<ev_prepare> and C<ev_check> calls - and is incremented between the
+prepare and check phases.
 
-=item unsigned int ev_loop_depth (loop)
+=item unsigned int ev_depth (loop)
 
 Returns the number of times C<ev_loop> was entered minus the number of
 times C<ev_loop> was exited, in other words, the recursion depth.
@@ -658,7 +662,8 @@
 in which case it is higher.
 
 Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread
-etc.), doesn't count as exit.
+etc.), doesn't count as "exit" - consider this as a hint to avoid such
+ungentleman behaviour unless it's really convenient.
 
 =item unsigned int ev_backend (loop)
 
@@ -1034,7 +1039,7 @@
 The file descriptor in the C<ev_io> watcher has become readable and/or
 writable.
 
-=item C<EV_TIMEOUT>
+=item C<EV_TIMER>
 
 The C<ev_timer> watcher has timed out.
 
@@ -1540,6 +1545,44 @@
 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 The special problem of accept()ing when you can't
+
+Many implementations of the POSIX C<accept> function (for example,
+found in post-2004 Linux) have the peculiar behaviour of not removing a
+connection from the pending queue in all error cases.
+
+For example, larger servers often run out of file descriptors (because
+of resource limits), causing C<accept> to fail with C<ENFILE> but not
+rejecting the connection, leading to libev signalling readiness on
+the next iteration again (the connection still exists after all), and
+typically causing the program to loop at 100% CPU usage.
+
+Unfortunately, the set of errors that cause this issue differs between
+operating systems, there is usually little the app can do to remedy the
+situation, and no known thread-safe method of removing the connection to
+cope with overload is known (to me).
+
+One of the easiest ways to handle this situation is to just ignore it
+- when the program encounters an overload, it will just loop until the
+situation is over. While this is a form of busy waiting, no OS offers an
+event-based way to handle this situation, so it's the best one can do.
+
+A better way to handle the situation is to log any errors other than
+C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
+messages, and continue as usual, which at least gives the user an idea of
+what could be wrong ("raise the ulimit!"). For extra points one could stop
+the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
+usage.
+
+If your program is single-threaded, then you could also keep a dummy file
+descriptor for overload situations (e.g. by opening F</dev/null>), and
+when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
+close that fd, and create a new dummy fd. This will gracefully refuse
+clients under typical overload conditions.
+
+The last way to handle it is to simply log the error and C<exit>, as
+is often done with C<malloc> failures, but this results in an easy
+opportunity for a DoS attack.
 
 =head3 Watcher-Specific Functions
 
@@ -1728,7 +1771,7 @@
 
    ev_init (timer, callback);
    last_activity = ev_now (loop);
-   callback (loop, timer, EV_TIMEOUT);
+   callback (loop, timer, EV_TIMER);
 
 And when there is some activity, simply store the current time in
 C<last_activity>, no libev calls at all:
@@ -3143,9 +3186,9 @@
 started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
 repeat = 0) will be started. C<0> is a valid timeout.
 
-The callback has the type C<void (*cb)(int revents, void *arg)> and gets
+The callback has the type C<void (*cb)(int revents, void *arg)> and is
 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>
+C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMER>) and the C<arg>
 value passed to C<ev_once>. Note that it is possible to receive I<both>
 a timeout and an io event at the same time - you probably should give io
 events precedence.
@@ -3156,7 +3199,7 @@
    {
      if (revents & EV_READ)
        /* stdin might have data for us, joy! */;
-     else if (revents & EV_TIMEOUT)
+     else if (revents & EV_TIMER)
        /* doh, nothing entered */;
    }
 
@@ -3624,7 +3667,7 @@
 
 Symbols marked with "(h)" do not change the ABI, and can have different
 values when compiling libev vs. including F<ev.h>, so it is permissible
-to redefine them before including F<ev.h> without breakign compatibility
+to redefine them before including F<ev.h> without breaking compatibility
 to a compiled library. All other symbols change the ABI, which means all
 users of libev and the libev code itself must be compiled with compatible
 settings.
@@ -3840,55 +3883,95 @@
 If your embedding application does not need any priorities, defining these
 both to C<0> will save some memory and CPU.
 
-=item EV_PERIODIC_ENABLE
+=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
+EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
+EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
+
+If undefined or defined to be C<1> (and the platform supports it), then
+the respective watcher type is supported. If defined to be C<0>, then it
+is not. Disabling watcher types mainly saves codesize.
 
-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_FEATURES
 
-=item EV_IDLE_ENABLE
+If you need to shave off some kilobytes of code at the expense of some
+speed (but with the full API), you can define this symbol to request
+certain subsets of functionality. The default is to enable all features
+that can be enabled on the platform.
+
+A typical way to use this symbol is to define it to C<0> (or to a bitset
+with some broad features you want) and then selectively re-enable
+additional parts you want, for example if you want everything minimal,
+but multiple event loop support, async and child watchers and the poll
+backend, use this:
+
+   #define EV_FEATURES 0
+   #define EV_MULTIPLICITY 1
+   #define EV_USE_POLL 1
+   #define EV_CHILD_ENABLE 1
+   #define EV_ASYNC_ENABLE 1
 
-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.
+The actual value is a bitset, it can be a combination of the following
+values:
 
-=item EV_EMBED_ENABLE
+=over 4
 
-If undefined or defined to be C<1>, then embed watchers are supported. If
-defined to be C<0>, then they are not. Embed watchers rely on most other
-watcher types, which therefore must not be disabled.
+=item C<1> - faster/larger code
 
-=item EV_STAT_ENABLE
+Use larger code to speed up some operations.
 
-If undefined or defined to be C<1>, then stat watchers are supported. If
-defined to be C<0>, then they are not.
+Currently this is used to override some inlining decisions (enlarging the  roughly
+30% code size on amd64.
 
-=item EV_FORK_ENABLE
+When optimising for size, use of compiler flags such as C<-Os> with
+gcc recommended, as well as C<-DNDEBUG>, as libev contains a number of
+assertions.
 
-If undefined or defined to be C<1>, then fork watchers are supported. If
-defined to be C<0>, then they are not.
+=item C<2> - faster/larger data structures
 
-=item EV_ASYNC_ENABLE
+Replaces the small 2-heap for timer management by a faster 4-heap, larger
+hash table sizes and so on. This will usually further increase codesize
+and can additionally have an effect on the size of data structures at
+runtime.
 
-If undefined or defined to be C<1>, then async watchers are supported. If
-defined to be C<0>, then they are not.
+=item C<4> - full API configuration
 
-=item EV_MINIMAL
+This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
+enables multiplicity (C<EV_MULTIPLICITY>=1).
 
-If you need to shave off some kilobytes of code at the expense of some
-speed (but with the full API), define this symbol to C<1>. Currently this
-is used to override some inlining decisions, saves roughly 30% code size
-on amd64. It also selects a much smaller 2-heap for timer management over
-the default 4-heap.
-
-You can save even more by disabling watcher types you do not need
-and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert>
-(C<-DNDEBUG>) will usually reduce code size a lot.
-
-Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to
-provide a bare-bones event library. See C<ev.h> for details on what parts
-of the API are still available, and do not complain if this subset changes
-over time.
+=item C<8> - full API
+
+This enables a lot of the "lesser used" API functions. See C<ev.h> for
+details on which parts of the API are still available without this
+feature, and do not complain if this subset changes over time.
+
+=item C<16> - enable all optional watcher types
+
+Enables all optional watcher types.  If you want to selectively enable
+only some watcher types other than I/O and timers (e.g. prepare,
+embed, async, child...) you can enable them manually by defining
+C<EV_watchertype_ENABLE> to C<1> instead.
+
+=item C<32> - enable all backends
+
+This enables all backends - without this feature, you need to enable at
+least one backend manually (C<EV_USE_SELECT> is a good choice).
+
+=item C<64> - enable OS-specific "helper" APIs
+
+Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
+default.
+
+=back
+
+Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
+reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb
+code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
+watchers, timers and monotonic clock support.
+
+With an intelligent-enough linker (gcc+binutils are intelligent enough
+when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
+your program might be left out as well - a binary starting a timer and an
+I/O watcher then might come out at only 5Kb.
 
 =item EV_AVOID_STDIO
 
@@ -3913,17 +3996,17 @@
 =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).
+pid. The default size is C<16> (or C<1> with C<EV_FEATURES> disabled),
+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).
+inotify watch id. The default size is C<16> (or C<1> with C<EV_FEATURES>
+disabled), 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_USE_4HEAP
 
@@ -3932,8 +4015,8 @@
 to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
 faster performance with many (thousands) of watchers.
 
-The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
-(disabled).
+The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
+will be C<0>.
 
 =item EV_HEAP_CACHE_AT
 
@@ -3944,8 +4027,8 @@
 but avoids random read accesses on heap changes. This improves performance
 noticeably with many (hundreds) of watchers.
 
-The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0>
-(disabled).
+The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
+will be C<0>.
 
 =item EV_VERIFY
 
@@ -3957,8 +4040,8 @@
 verification code will be called very frequently, which will slow down
 libev considerably.
 
-The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be
-C<0>.
+The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
+will be C<0>.
 
 =item EV_COMMON
 
@@ -4026,15 +4109,14 @@
 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_FEATURES 8
+   #define EV_USE_SELECT 1
+   #define EV_PREPARE_ENABLE 1
+   #define EV_IDLE_ENABLE 1
+   #define EV_SIGNAL_ENABLE 1
+   #define EV_CHILD_ENABLE 1
+   #define EV_USE_STDEXCEPT 0
    #define EV_CONFIG_H <config.h>
-   #define EV_MINPRI 0
-   #define EV_MAXPRI 0
 
    #include "ev++.h"
 
@@ -4546,6 +4628,45 @@
 =back
 
 
+=head1 PORTING FROM LIBEV 3.X TO 4.X
+
+The major version 4 introduced some minor incompatible changes to the API.
+
+At the moment, the C<ev.h> header file tries to implement superficial
+compatibility, so most programs should still compile. Those might be
+removed in later versions of libev, so better update early than late.
+
+=over 4
+
+=item C<ev_loop_count> renamed to C<ev_iteration>
+
+=item C<ev_loop_depth> renamed to C<ev_depth>
+
+=item C<ev_loop_verify> renamed to C<ev_verify>
+
+Most functions working on C<struct ev_loop> objects don't have an
+C<ev_loop_> prefix, so it was removed. Note that C<ev_loop_fork> is
+still called C<ev_loop_fork> because it would otherwise clash with the
+C<ev_fork> typedef.
+
+=item C<EV_TIMEOUT> renamed to C<EV_TIMER> in C<revents>
+
+This is a simple rename - all other watcher types use their name
+as revents flag, and now C<ev_timer> does, too.
+
+Both C<EV_TIMER> and C<EV_TIMEOUT> symbols were present in 3.x versions
+and continue to be present for the forseeable future, so this is mostly a
+documentation change.
+
+=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
+
+The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
+mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
+and work, but the library code will of course be larger.
+
+=back
+
+
 =head1 GLOSSARY
 
 =over 4
@@ -4576,7 +4697,7 @@
 any other events happening anymore.
 
 In libev, events are represented as single bits (such as C<EV_READ> or
-C<EV_TIMEOUT>).
+C<EV_TIMER>).
 
 =item event library