--- libev/ev.pod	2010/10/24 19:44:08	1.325
+++ libev/ev.pod	2010/11/10 14:36:42	1.345
@@ -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
@@ -235,7 +243,7 @@
 
 See the description of C<ev_embed> watchers for more info.
 
-=item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]
+=item ev_set_allocator (void *(*cb)(void *ptr, long size))
 
 Sets the allocation function to use (the prototype is similar - the
 semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
@@ -271,7 +279,7 @@
    ...
    ev_set_allocator (persistent_realloc);
 
-=item ev_set_syserr_cb (void (*cb)(const char *msg)); [NOT REENTRANT]
+=item ev_set_syserr_cb (void (*cb)(const char *msg))
 
 Set the callback function to call on a retryable system call error (such
 as failed select, poll, epoll_wait). The message is a printable string
@@ -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
 
@@ -349,9 +357,9 @@
 This will create and initialise a new event loop object. If the loop
 could not be initialised, returns false.
 
-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.
+This function 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.
 
 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>).
@@ -396,14 +404,14 @@
 =item C<EVFLAG_NOINOTIFY>
 
 When this flag is specified, then libev will not attempt to use the
-I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
+I<inotify> API for its C<ev_stat> watchers. Apart from debugging and
 testing, this flag can be useful to conserve inotify file descriptors, as
 otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
 
 =item C<EVFLAG_SIGNALFD>
 
 When this flag is specified, then libev will attempt to use the
-I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
+I<signalfd> API for its C<ev_signal> (and C<ev_child>) watchers. This API
 delivers signals synchronously, which makes it both faster and might make
 it possible to get the queued signal data. It can also simplify signal
 handling with threads, as long as you properly block signals in your
@@ -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
@@ -609,7 +621,7 @@
 C<ev_default_loop>, in which case it is not thread-safe.
 
 Note that it is not advisable to call this function on the default loop
-except in the rare occasion where you really need to free it's resources.
+except in the rare occasion where you really need to free its resources.
 If you need dynamically allocated loops it is better to use C<ev_loop_new>
 and C<ev_loop_destroy>.
 
@@ -667,15 +679,16 @@
 =item unsigned int ev_depth (loop)
 
 Returns the number of times C<ev_run> was entered minus the number of
-times C<ev_run> was exited, in other words, the recursion depth.
+times C<ev_run> was exited normally, in other words, the recursion depth.
 
 Outside C<ev_run>, this number is zero. In a callback, this number is
 C<1>, unless C<ev_run> was invoked recursively (or from another thread),
 in which case it is higher.
 
-Leaving C<ev_run> abnormally (setjmp/longjmp, cancelling the thread
-etc.), doesn't count as "exit" - consider this as a hint to avoid such
-ungentleman-like behaviour unless it's really convenient.
+Leaving C<ev_run> abnormally (setjmp/longjmp, cancelling the thread,
+throwing an exception etc.), doesn't count as "exit" - consider this
+as a hint to avoid such ungentleman-like behaviour unless it's really
+convenient, in which case it is fully supported.
 
 =item unsigned int ev_backend (loop)
 
@@ -747,6 +760,11 @@
 of relying on its watchers stopping correctly, that is truly a thing of
 beauty.
 
+This function is also I<mostly> exception-safe - you can break out of
+a C<ev_run> call by calling C<longjmp> in a callback, throwing a C++
+exception and so on. This does not decrement the C<ev_depth> value, nor
+will it clear any outstanding C<EVBREAK_ONE> breaks.
+
 A flags value of C<EVRUN_NOWAIT> will look for new events, will handle
 those events and any already outstanding ones, but will not wait and
 block your process in case there are no events and will return after one
@@ -817,9 +835,10 @@
 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 on the next call to C<ev_run>.
 
-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, in
+which case it will have no effect.
 
 =item ev_ref (loop)
 
@@ -972,11 +991,11 @@
 
 =item ev_set_userdata (loop, void *data)
 
-=item ev_userdata (loop)
+=item void *ev_userdata (loop)
 
 Set and retrieve a single C<void *> associated with a loop. When
 C<ev_set_userdata> has never been called, then C<ev_userdata> returns
-C<0.>
+C<0>.
 
 These two functions can be used to associate arbitrary data with a loop,
 and are intended solely for the C<invoke_pending_cb>, C<release> and
@@ -1116,7 +1135,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 +1167,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 +1318,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 +1383,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
@@ -2251,7 +2269,7 @@
 
 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
+will try its best to deliver signals synchronously, i.e. as part of the
 normal event processing, like any other event.
 
 If you want signals to be delivered truly asynchronously, just use
@@ -3100,21 +3118,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 watchers for your
+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 +3146,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
 
@@ -3346,6 +3369,56 @@
 =back
 
 
+=head1 COMMON OR USEFUL IDIOMS (OR BOTH)
+
+This section explains some common idioms that are not immediately
+obvious. Note that examples are sprinkled over the whole manual, and this
+section only contains stuff that wouldn't fit anywhere else.
+
+=over 4
+
+=item Model/nested event loop invocations and exit conditions.
+
+Often (especially in GUI toolkits) there are places where you have
+I<modal> interaction, which is most easily implemented by recursively
+invoking C<ev_run>.
+
+This brings the problem of exiting - a callback might want to finish the
+main C<ev_run> call, but not the nested one (e.g. user clicked "Quit", but
+a modal "Are you sure?" dialog is still waiting), or just the nested one
+and not the main one (e.g. user clocked "Ok" in a modal dialog), or some
+other combination: In these cases, C<ev_break> will not work alone.
+
+The solution is to maintain "break this loop" variable for each C<ev_run>
+invocation, and use a loop around C<ev_run> until the condition is
+triggered, using C<EVRUN_ONCE>:
+
+   // main loop
+   int exit_main_loop = 0;
+
+   while (!exit_main_loop)
+     ev_run (EV_DEFAULT_ EVRUN_ONCE);
+
+   // in a model watcher
+   int exit_nested_loop = 0;
+
+   while (!exit_nested_loop)
+     ev_run (EV_A_ EVRUN_ONCE);
+
+To exit from any of these loops, just set the corresponding exit variable:
+
+   // exit modal loop
+   exit_nested_loop = 1;
+
+   // exit main program, after modal loop is finished
+   exit_main_loop = 1;
+
+   // exit both
+   exit_main_loop = exit_nested_loop = 1;
+
+=back
+
+
 =head1 LIBEVENT EMULATION
 
 Libev offers a compatibility emulation layer for libevent. It cannot
@@ -3353,6 +3426,11 @@
 
 =over 4
 
+=item * Only the libevent-1.4.1-beta API is being emulated.
+
+This was the newest libevent version available when libev was implemented,
+and is still mostly uncanged in 2010.
+
 =item * Use it by including <event.h>, as usual.
 
 =item * The following members are fully supported: ev_base, ev_callback,
@@ -3367,7 +3445,7 @@
 is an ev_pri field.
 
 =item * In libevent, the last base created gets the signals, in libev, the
-first base created (== the default loop) gets the signals.
+base that registered the signal gets the signals.
 
 =item * Other members are not supported.
 
@@ -4754,6 +4832,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 +4952,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 +5001,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 +5084,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.