--- libev/ev.pod	2010/10/24 19:44:27	1.326
+++ libev/ev.pod	2010/10/31 21:16:26	1.338
@@ -80,6 +80,14 @@
 Familiarity with event based programming techniques in general is assumed
 throughout this document.
 
+=head1 WHAT TO READ WHEN IN A HURRY
+
+This manual tries to be very detailed, but unfortunately, this also makes
+it very long. If you just want to know the basics of libev, I suggest
+reading L<ANATOMY OF A WATCHER>, then the L<EXAMPLE PROGRAM> above and
+look up the missing functions in L<GLOBAL FUNCTIONS> and the C<ev_io> and
+C<ev_timer> sections in L<WATCHER TYPES>.
+
 =head1 ABOUT LIBEV
 
 Libev is an event loop: you register interest in certain events (such as a
@@ -302,8 +310,8 @@
 libev 3 had an C<ev_loop> function colliding with the struct name).
 
 The library knows two types of such loops, the I<default> loop, which
-supports signals and child events, and dynamically created event loops
-which do not.
+supports child process events, and dynamically created event loops which
+do not.
 
 =over 4
 
@@ -457,11 +465,13 @@
 The epoll mechanism deserves honorable mention as the most misdesigned
 of the more advanced event mechanisms: mere annoyances include silently
 dropping file descriptors, requiring a system call per change per file
-descriptor (and unnecessary guessing of parameters), problems with dup and
-so on. The biggest issue is fork races, however - if a program forks then
-I<both> parent and child process have to recreate the epoll set, which can
-take considerable time (one syscall per file descriptor) and is of course
-hard to detect.
+descriptor (and unnecessary guessing of parameters), problems with dup,
+returning before the timeout value, resulting in additional iterations
+(and only giving 5ms accuracy while select on the same platform gives
+0.1ms) and so on. The biggest issue is fork races, however - if a program
+forks then I<both> parent and child process have to recreate the epoll
+set, which can take considerable time (one syscall per file descriptor)
+and is of course hard to detect.
 
 Epoll is also notoriously buggy - embedding epoll fds I<should> work, but
 of course I<doesn't>, and epoll just loves to report events for totally
@@ -473,6 +483,8 @@
 not least, it also refuses to work with some file descriptors which work
 perfectly fine with C<select> (files, many character devices...).
 
+Epoll is truly the train wreck analog among event poll mechanisms.
+
 While stopping, setting and starting an I/O watcher in the same iteration
 will result in some caching, there is still a system call per such
 incident (because the same I<file descriptor> could point to a different
@@ -817,9 +829,9 @@
 C<EVBREAK_ONE>, which will make the innermost C<ev_run> call return, or
 C<EVBREAK_ALL>, which will make all nested C<ev_run> calls return.
 
-This "unloop state" will be cleared when entering C<ev_run> again.
+This "break state" will be cleared when entering C<ev_run> again.
 
-It is safe to call C<ev_break> from outside any C<ev_run> calls. ##TODO##
+It is safe to call C<ev_break> from outside any C<ev_run> calls, too.
 
 =item ev_ref (loop)
 
@@ -1116,7 +1128,7 @@
 
 =item C<EV_CLEANUP>
 
-The event loop is abotu to be destroyed (see C<ev_cleanup>).
+The event loop is about to be destroyed (see C<ev_cleanup>).
 
 =item C<EV_ASYNC>
 
@@ -1148,65 +1160,6 @@
 
 =back
 
-=head2 WATCHER STATES
-
-There are various watcher states mentioned throughout this manual -
-active, pending and so on. In this section these states and the rules to
-transition between them will be described in more detail - and while these
-rules might look complicated, they usually do "the right thing".
-
-=over 4
-
-=item initialiased
-
-Before a watcher can be registered with the event looop it has to be
-initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
-C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
-
-In this state it is simply some block of memory that is suitable for use
-in an event loop. It can be moved around, freed, reused etc. at will.
-
-=item started/running/active
-
-Once a watcher has been started with a call to C<ev_TYPE_start> it becomes
-property of the event loop, and is actively waiting for events. While in
-this state it cannot be accessed (except in a few documented ways), moved,
-freed or anything else - the only legal thing is to keep a pointer to it,
-and call libev functions on it that are documented to work on active watchers.
-
-=item pending
-
-If a watcher is active and libev determines that an event it is interested
-in has occurred (such as a timer expiring), it will become pending. It will
-stay in this pending state until either it is stopped or its callback is
-about to be invoked, so it is not normally pending inside the watcher
-callback.
-
-The watcher might or might not be active while it is pending (for example,
-an expired non-repeating timer can be pending but no longer active). If it
-is stopped, it can be freely accessed (e.g. by calling C<ev_TYPE_set>),
-but it is still property of the event loop at this time, so cannot be
-moved, freed or reused. And if it is active the rules described in the
-previous item still apply.
-
-It is also possible to feed an event on a watcher that is not active (e.g.
-via C<ev_feed_event>), in which case it becomes pending without being
-active.
-
-=item stopped
-
-A watcher can be stopped implicitly by libev (in which case it might still
-be pending), or explicitly by calling its C<ev_TYPE_stop> function. The
-latter will clear any pending state the watcher might be in, regardless
-of whether it was active or not, so stopping a watcher explicitly before
-freeing it is often a good idea.
-
-While stopped (and not pending) the watcher is essentially in the
-initialised state, that is it can be reused, moved, modified in any way
-you wish.
-
-=back
-
 =head2 GENERIC WATCHER FUNCTIONS
 
 =over 4
@@ -1358,7 +1311,6 @@
 
 =back
 
-
 =head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
 
 Each watcher has, by default, a member C<void *data> that you can change
@@ -1424,6 +1376,65 @@
        (((char *)w) - offsetof (struct my_biggy, t2));
    }
 
+=head2 WATCHER STATES
+
+There are various watcher states mentioned throughout this manual -
+active, pending and so on. In this section these states and the rules to
+transition between them will be described in more detail - and while these
+rules might look complicated, they usually do "the right thing".
+
+=over 4
+
+=item initialiased
+
+Before a watcher can be registered with the event looop it has to be
+initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
+C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
+
+In this state it is simply some block of memory that is suitable for use
+in an event loop. It can be moved around, freed, reused etc. at will.
+
+=item started/running/active
+
+Once a watcher has been started with a call to C<ev_TYPE_start> it becomes
+property of the event loop, and is actively waiting for events. While in
+this state it cannot be accessed (except in a few documented ways), moved,
+freed or anything else - the only legal thing is to keep a pointer to it,
+and call libev functions on it that are documented to work on active watchers.
+
+=item pending
+
+If a watcher is active and libev determines that an event it is interested
+in has occurred (such as a timer expiring), it will become pending. It will
+stay in this pending state until either it is stopped or its callback is
+about to be invoked, so it is not normally pending inside the watcher
+callback.
+
+The watcher might or might not be active while it is pending (for example,
+an expired non-repeating timer can be pending but no longer active). If it
+is stopped, it can be freely accessed (e.g. by calling C<ev_TYPE_set>),
+but it is still property of the event loop at this time, so cannot be
+moved, freed or reused. And if it is active the rules described in the
+previous item still apply.
+
+It is also possible to feed an event on a watcher that is not active (e.g.
+via C<ev_feed_event>), in which case it becomes pending without being
+active.
+
+=item stopped
+
+A watcher can be stopped implicitly by libev (in which case it might still
+be pending), or explicitly by calling its C<ev_TYPE_stop> function. The
+latter will clear any pending state the watcher might be in, regardless
+of whether it was active or not, so stopping a watcher explicitly before
+freeing it is often a good idea.
+
+While stopped (and not pending) the watcher is essentially in the
+initialised state, that is it can be reused, moved, modified in any way
+you wish.
+
+=back
+
 =head2 WATCHER PRIORITY MODELS
 
 Many event loops support I<watcher priorities>, which are usually small
@@ -3100,21 +3111,26 @@
 
 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.
+really.
 
 =back
 
 
 =head2 C<ev_cleanup> - even the best things end
 
-Cleanup watchers are called just before the event loop they are registered
-with is being destroyed.
+Cleanup watchers are called just before the event loop is being destroyed
+by a call to C<ev_loop_destroy>.
 
 While there is no guarantee that the event loop gets destroyed, cleanup
 watchers provide a convenient method to install cleanup hooks for your
 program, worker threads and so on - you just to make sure to destroy the
 loop when you want them to be invoked.
 
+Cleanup watchers are invoked in the same way as any other watcher. Unlike
+all other watchers, they do not keep a reference to the event loop (which
+makes a lot of sense if you think about it). Like all other watchers, you
+can call libev functions in the callback, except C<ev_cleanup_start>.
+
 =head3 Watcher-Specific Functions and Data Members
 
 =over 4
@@ -3123,7 +3139,7 @@
 
 Initialises and configures the cleanup watcher - it has no parameters of
 any kind. There is a C<ev_cleanup_set> macro, but using it is utterly
-pointless, believe me.
+pointless, I assure you.
 
 =back
 
@@ -4754,6 +4770,11 @@
 callback: The watcher callbacks have different type signatures, but libev
 calls them using an C<ev_watcher *> internally.
 
+=item pointer accesses must be thread-atomic
+
+Accessing a pointer value must be atomic, it must both be readable and
+writable in one piece - this is the case on all current architectures.
+
 =item C<sig_atomic_t volatile> must be thread-atomic as well
 
 The type C<sig_atomic_t volatile> (or whatever is defined as
@@ -4869,14 +4890,21 @@
 
 =head1 PORTING FROM LIBEV 3.X TO 4.X
 
-The major version 4 introduced some minor incompatible changes to the API.
+The major version 4 introduced some 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.
+At the moment, the C<ev.h> header file provides compatibility definitions
+for all changes, so most programs should still compile. The compatibility
+layer might be removed in later versions of libev, so better update to the
+new API early than late.
 
 =over 4
 
+=item C<EV_COMPAT3> backwards compatibility mechanism
+
+The backward compatibility mechanism can be controlled by
+C<EV_COMPAT3>. See L<PREPROCESSOR SYMBOLS/MACROS> in the L<EMBEDDING>
+section.
+
 =item C<ev_default_destroy> and C<ev_default_fork> have been removed
 
 These calls can be replaced easily by their C<ev_loop_xxx> counterparts:
@@ -4911,12 +4939,6 @@
 C<ev_loop_fork> because it would otherwise clash with the C<ev_fork>
 typedef.
 
-=item C<EV_COMPAT3> backwards compatibility mechanism
-
-The backward compatibility mechanism can be controlled by
-C<EV_COMPAT3>. See L<PREPROCESSOR SYMBOLS/MACROS> in the L<EMBEDDING>
-section.
-
 =item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
 
 The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
@@ -5000,5 +5022,6 @@
 
 =head1 AUTHOR
 
-Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
+Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael
+Magnusson and Emanuele Giaquinta.