--- libev/ev.pod	2008/04/06 09:53:18	1.142
+++ libev/ev.pod	2008/05/06 23:34:16	1.150
@@ -198,18 +198,21 @@
 =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.
+semantics are identical to the C<realloc> C89/SuS/POSIX function). It is
+used to allocate and free memory (no surprises here). If it returns zero
+when memory needs to be allocated (C<size != 0>), the library might abort
+or take some potentially destructive action.
+
+Since some systems (at least OpenBSD and Darwin) fail to implement
+correct C<realloc> semantics, libev will use a wrapper around the system
+C<realloc> and C<free> functions by default.
 
 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).
+retries (example requires a standards-compliant C<realloc>).
 
    static void *
    persistent_realloc (void *ptr, size_t size)
@@ -258,13 +261,6 @@
 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)
@@ -1379,6 +1375,11 @@
 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 ev_periodic_at (ev_periodic *)
+
+When active, returns the absolute time that the watcher is supposed to
+trigger next.
+
 =item ev_tstamp offset [read-write]
 
 When repeating, this contains the offset value, otherwise this is the
@@ -1399,11 +1400,6 @@
 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
@@ -1616,11 +1612,12 @@
 
 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.
+reader, note, however, that the author sees no way of implementing ev_stat
+semantics with kqueue). 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)
 
@@ -1640,9 +1637,9 @@
 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
+Inotify presence 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
+making regular C<stat> calls. Even in the presence 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
@@ -1655,16 +1652,25 @@
 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.
+That means that, if the time is the only thing that changes, you can
+easily 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 as the stat
+data does not change.
+
+The solution to this is to delay acting on a change for slightly more
+than second (or till slightly after the next full second boundary), using
+a roughly one-second-delay C<ev_timer> (e.g. C<ev_timer_set (w, 0., 1.02);
+ev_timer_again (loop, w)>).
+
+The C<.02> offset is added to work around small timing inconsistencies
+of some operating systems (where the second counter of the current time
+might be be delayed. One such system is the Linux kernel, where a call to
+C<gettimeofday> might return a timestamp with a full second later than
+a subsequent C<time> call - if the equivalent of C<time ()> is used to
+update file times then there will be a small window where the kernel uses
+the previous second to update file times but libev might already execute
+the timer callback).
 
 =head3 Watcher-Specific Functions and Data Members
 
@@ -1680,28 +1686,32 @@
 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).
+The callback will 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.
+watched path in your callback, you could call this function to avoid
+detecting this change (while introducing a race condition if you are not
+the only one changing the path). 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
+The most-recently detected attributes of the file. Although the type is
 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.
+suitable for your system, but you can only rely on the POSIX-standardised
+members to be present. 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>.
+C<prev> != C<attr>, or, more precisely, one or more of these members
+differ: C<st_dev>, C<st_ino>, C<st_mode>, C<st_nlink>, C<st_uid>,
+C<st_gid>, C<st_rdev>, C<st_size>, C<st_atime>, C<st_mtime>, C<st_ctime>.
 
 =item ev_tstamp interval [read-only]
 
@@ -1765,7 +1775,7 @@
   ...
   ev_stat_init (&passwd, stat_cb, "/etc/passwd", 0.);
   ev_stat_start (loop, &passwd);
-  ev_timer_init (&timer, timer_cb, 0., 1.01);
+  ev_timer_init (&timer, timer_cb, 0., 1.02);
 
 
 =head2 C<ev_idle> - when you've got nothing better to do...
@@ -1863,7 +1873,7 @@
 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
+supports this, they might get executed 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
@@ -1888,9 +1898,9 @@
 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).
+use as a 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
@@ -2384,6 +2394,9 @@
 will fail and all watchers will have the same priority, even though there
 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.
+
 =item * Other members are not supported.
 
 =item * The libev emulation is I<not> ABI compatible to libevent, you need
@@ -2635,6 +2648,16 @@
 Similar to the other two macros, this gives you the value of the default
 loop, if multiple loops are supported ("ev loop default").
 
+=item C<EV_DEFAULT_UC>, C<EV_DEFAULT_UC_>
+
+Usage identical to C<EV_DEFAULT> and C<EV_DEFAULT_>, but requires that the
+default loop has been initialised (C<UC> == unchecked). Their behaviour
+is undefined when the default loop has not been initialised by a previous
+execution of C<EV_DEFAULT>, C<EV_DEFAULT_> or C<ev_default_init (...)>.
+
+It is often prudent to use C<EV_DEFAULT> when initialising the first
+watcher in a function but use C<EV_DEFAULT_UC> afterwards.
+
 =back
 
 Example: Declare and initialise a check watcher, utilising the above
@@ -3059,6 +3082,63 @@
   #include "ev.c"
 
 
+=head1 THREADS AND COROUTINES
+
+=head2 THREADS
+
+Libev itself is completely threadsafe, but it uses no locking. This
+means that you can use as many loops as you want in parallel, as long as
+only one thread ever calls into one libev function with the same loop
+parameter.
+
+Or put differently: calls with different loop parameters can be done in
+parallel from multiple threads, calls with the same loop parameter must be
+done serially (but can be done from different threads, as long as only one
+thread ever is inside a call at any point in time, e.g. by using a mutex
+per loop).
+
+If you want to know which design is best for your problem, then I cannot
+help you but by giving some generic advice:
+
+=over 4
+
+=item * most applications have a main thread: use the default libev loop
+in that thread, or create a seperate thread running only the default loop.
+
+This helps integrating other libraries or software modules that use libev
+themselves and don't care/know about threading.
+
+=item * one loop per thread is usually a good model.
+
+Doing this is almost never wrong, sometimes a better-performance model
+exists, but it is always a good start.
+
+=item * other models exist, such as the leader/follower pattern, where one
+loop is handed through multiple threads in a kind of round-robbin fashion.
+
+Chosing a model is hard - look around, learn, know that usually you cna do
+better than you currently do :-)
+
+=item * often you need to talk to some other thread which blocks in the
+event loop - C<ev_async> watchers can be used to wake them up from other
+threads safely (or from signal contexts...).
+
+=back
+
+=head2 COROUTINES
+
+Libev is much more accomodating to coroutines ("cooperative threads"):
+libev fully supports nesting calls to it's functions from different
+coroutines (e.g. you can call C<ev_loop> on the same loop from two
+different coroutines and switch freely between both coroutines running the
+loop, as long as you don't confuse yourself). The only exception is that
+you must not do this from C<ev_periodic> reschedule callbacks.
+
+Care has been invested into making sure that libev does not keep local
+state inside C<ev_loop>, and other calls do not usually allow coroutine
+switches.
+
+
 =head1 COMPLEXITIES
 
 In this section the complexities of (many of) the algorithms used inside
@@ -3138,15 +3218,21 @@
 descriptors. This only applies when using Win32 natively, not when using
 e.g. cygwin.
 
+Lifting these limitations would basically require the full
+re-implementation of the I/O system. If you are into these kinds of
+things, then note that glib does exactly that for you in a very portable
+way (note also that glib is the slowest event library known to man).
+
 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).
+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 readyness
+notification model, which cannot be implemented efficiently on windows
+(microsoft monopoly games).
 
 =over 4
 
@@ -3170,11 +3256,13 @@
 
 =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).
+Windows has numerous arbitrary (and low) limits on things.
+
+Early versions of winsocket's select only supported waiting for a maximum
+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. Great).
 
 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
@@ -3196,6 +3284,53 @@
 =back
 
 
+=head1 PORTABILITY REQUIREMENTS
+
+In addition to a working ISO-C implementation, libev relies on a few
+additional extensions:
+
+=over 4
+
+=item C<sig_atomic_t volatile> must be thread-atomic as well
+
+The type C<sig_atomic_t volatile> (or whatever is defined as
+C<EV_ATOMIC_T>) must be atomic w.r.t. accesses from different
+threads. This is not part of the specification for C<sig_atomic_t>, but is
+believed to be sufficiently portable.
+
+=item C<sigprocmask> must work in a threaded environment
+
+Libev uses C<sigprocmask> to temporarily block signals. This is not
+allowed in a threaded program (C<pthread_sigmask> has to be used). Typical
+pthread implementations will either allow C<sigprocmask> in the "main
+thread" or will block signals process-wide, both behaviours would
+be compatible with libev. Interaction between C<sigprocmask> and
+C<pthread_sigmask> could complicate things, however.
+
+The most portable way to handle signals is to block signals in all threads
+except the initial one, and run the default loop in the initial thread as
+well.
+
+=item C<long> must be large enough for common memory allocation sizes
+
+To improve portability and simplify using libev, libev uses C<long>
+internally instead of C<size_t> when allocating its data structures. On
+non-POSIX systems (Microsoft...) this might be unexpectedly low, but
+is still at least 31 bits everywhere, which is enough for hundreds of
+millions of watchers.
+
+=item C<double> must hold a time value in seconds with enough accuracy
+
+The type C<double> is used to represent timestamps. It is required to have
+at least 51 bits of mantissa, which is good enough for at least into the
+year 4000. This requirement is fulfilled by implementations implementing
+IEEE 754 (basically all existing ones).
+
+=back
+
+If you know of other additional requirements drop me a note.
+
+
 =head1 AUTHOR
 
 Marc Lehmann <libev@schmorp.de>.