--- libev/ev.pod	2012/05/04 20:22:27	1.409
+++ libev/ev.pod	2013/11/22 16:42:10	1.431
@@ -1,3 +1,5 @@
+=encoding utf-8
+
 =head1 NAME
 
 libev - a high performance full-featured event loop written in C
@@ -84,9 +86,9 @@
 
 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>.
+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
 
@@ -398,8 +400,10 @@
 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.
+useful to try out specific backends to test their performance, to work
+around bugs, or to make libev threadsafe (accessing environment variables
+cannot be done in a threadsafe way, but usually it works if no other
+thread modifies them).
 
 =item C<EVFLAG_FORKCHECK>
 
@@ -571,7 +575,7 @@
 cause an extra system call as with C<EVBACKEND_EPOLL>, it still adds up to
 two event changes per incident. Support for C<fork ()> is very bad (you
 might have to leak fd's on fork, but it's more sane than epoll) and it
-drops fds silently in similarly hard-to-detect cases
+drops fds silently in similarly hard-to-detect cases.
 
 This backend usually performs well under most conditions.
 
@@ -686,7 +690,7 @@
 the child process. You I<must> call it (or use C<EVFLAG_FORKCHECK>) in the
 child before resuming or calling C<ev_run>.
 
-Again, you I<have> to call it on I<any> loop that you want to re-use after 
+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.
@@ -766,7 +770,7 @@
 very long time without entering the event loop, updating libev's idea of
 the current time is a good idea.
 
-See also L<The special problem of time updates> in the C<ev_timer> section.
+See also L</The special problem of time updates> in the C<ev_timer> section.
 
 =item ev_suspend (loop)
 
@@ -1348,7 +1352,7 @@
 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 :).
 
-See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
+See L</WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
 priorities.
 
 =item ev_invoke (loop, ev_TYPE *watcher, int revents)
@@ -1383,7 +1387,7 @@
 
 =back
 
-See also the L<ASSOCIATING CUSTOM DATA WITH A WATCHER> and L<BUILDING YOUR
+See also the L</ASSOCIATING CUSTOM DATA WITH A WATCHER> and L</BUILDING YOUR
 OWN COMPOSITE WATCHERS> idioms.
 
 =head2 WATCHER STATES
@@ -1395,7 +1399,7 @@
 
 =over 4
 
-=item initialiased
+=item initialised
 
 Before a watcher can be registered with the event loop it has to be
 initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
@@ -2138,7 +2142,7 @@
 
 =back
 
-This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
+This sounds a bit complicated, see L</Be smart about timeouts>, above, for a
 usage example.
 
 =item ev_tstamp ev_timer_remaining (loop, ev_timer *)
@@ -2411,9 +2415,9 @@
 C<SIGINT> in both the default loop and another loop at the same time. At
 the moment, C<SIGCHLD> is permanently tied to the default loop.
 
-When the first watcher gets started will libev actually register something
-with the kernel (thus it coexists with your own signal handlers as long as
-you don't register any with libev for the same signal).
+Only after the first watcher for a signal is started will libev actually
+register something with the kernel. It thus coexists with your own signal
+handlers as long as you don't register any with libev for the same signal.
 
 If possible and supported, libev will install its handlers with
 C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
@@ -2608,8 +2612,9 @@
 
 This watches a file system path for attribute changes. That is, it calls
 C<stat> on that path in regular intervals (or when the OS says it changed)
-and sees if it changed compared to the last time, invoking the callback if
-it did.
+and sees if it changed compared to the last time, invoking the callback
+if it did. Starting the watcher C<stat>'s the file, so only changes that
+happen after the watcher has been started will be reported.
 
 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
@@ -2860,7 +2865,7 @@
 to do something on each event loop iteration - for example to balance load
 between different connections.
 
-See L<Abusing an C<ev_check> watcher for its side-effect> for a longer
+See L</Abusing an ev_check watcher for its side-effect> for a longer
 example.
 
 =head3 Watcher-Specific Functions and Data Members
@@ -2964,7 +2969,6 @@
 next event loop iteration. However, that isn't as soon as possible -
 without external events, your C<ev_check> watcher will not be invoked.
 
-
 This is where C<ev_idle> watchers come in handy - all you need is a
 single global idle watcher that is active as long as you have one active
 C<ev_check> watcher. The C<ev_idle> watcher makes sure the event loop
@@ -3180,7 +3184,7 @@
 
 =item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
 
-=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)
+=item ev_embed_set (ev_embed *, 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
@@ -3253,11 +3257,11 @@
 
 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.
+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 The special problem of life after fork - how is it possible?
 
@@ -3661,9 +3665,9 @@
 A common way around all these issues is to make sure that
 C<start_new_request> I<always> returns before the callback is invoked. If
 C<start_new_request> immediately knows the result, it can artificially
-delay invoking the callback by e.g. using a C<prepare> or C<idle> watcher
-for example, or more sneakily, by reusing an existing (stopped) watcher
-and pushing it into the pending queue:
+delay invoking the callback by using a C<prepare> or C<idle> watcher for
+example, or more sneakily, by reusing an existing (stopped) watcher and
+pushing it into the pending queue:
 
    ev_set_cb (watcher, callback);
    ev_feed_event (EV_A_ watcher, 0);
@@ -3681,7 +3685,7 @@
 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.
+other combination: In these cases, a simple C<ev_break> will not work.
 
 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
@@ -3890,7 +3894,7 @@
 switching to a coroutine, you push the watcher onto the queue and notify
 any waiters.
 
-To embed libev, see L<EMBEDDING>, but in short, it's easiest to create two
+To embed libev, see L</EMBEDDING>, but in short, it's easiest to create two
 files, F<my_ev.h> and F<my_ev.c> that include the respective libev files:
 
    // my_ev.h
@@ -3952,7 +3956,7 @@
 
 Proper exception specifications might have to be added to callbacks passed
 to libev: exceptions may be thrown only from watcher callbacks, all
-other callbacks (allocator, syserr, loop acquire/release and periodioc
+other callbacks (allocator, syserr, loop acquire/release and periodic
 reschedule callbacks) must not throw exceptions, and might need a C<throw
 ()> specification. If you have code that needs to be compiled as both C
 and C++ you can use the C<EV_THROW> macro for this:
@@ -3982,7 +3986,7 @@
 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
@@ -4123,10 +4127,14 @@
 
 =item w->set ([arguments])
 
-Basically the same as C<ev_TYPE_set>, with the same arguments. Either this
-method or a suitable start method must be called at least once. Unlike the
-C counterpart, an active watcher gets automatically stopped and restarted
-when reconfiguring it with this method.
+Basically the same as C<ev_TYPE_set> (except for C<ev::embed> watchers>),
+with the same arguments. Either this method or a suitable start method
+must be called at least once. Unlike the C counterpart, an active watcher
+gets automatically stopped and restarted when reconfiguring it with this
+method.
+
+For C<ev::embed> watchers this method is called C<set_embed>, to avoid
+clashing with the C<set (loop)> method.
 
 =item w->start ()
 
@@ -4240,6 +4248,14 @@
 time of this writing, only C<ev_io> and C<ev_timer>), to be found at
 L<http://github.com/brimworks/lua-ev>.
 
+=item Javascript
+
+Node.js (L<http://nodejs.org>) uses libev as the underlying event library.
+
+=item Others
+
+There are others, and I stopped counting.
+
 =back
 
 
@@ -4548,6 +4564,13 @@
 file descriptors again. Note that the replacement function has to close
 the underlying OS handle.
 
+=item EV_USE_WSASOCKET
+
+If defined to be C<1>, libev will use C<WSASocket> to create its internal
+communication socket, which works better in some environments. Otherwise,
+the normal C<socket> function will be used, which works better in other
+environments.
+
 =item EV_USE_POLL
 
 If defined to be C<1>, libev will compile in support for the C<poll>(2)
@@ -4601,23 +4624,22 @@
 
 =item EV_NO_THREADS
 
-If defined to be C<1>, libev will assume that it will never be called
-from different threads, which is a stronger assumption than C<EV_NO_SMP>,
-above. This reduces dependencies and makes libev faster.
+If defined to be C<1>, libev will assume that it will never be called from
+different threads (that includes signal handlers), which is a stronger
+assumption than C<EV_NO_SMP>, above. This reduces dependencies and makes
+libev faster.
 
 =item EV_ATOMIC_T
 
 Libev requires an integer type (suitable for storing C<0> or C<1>) whose
-access is atomic and serialised 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.
+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 absence of this define, libev will use C<sig_atomic_t volatile>
-(from F<signal.h>), which is usually good enough on most platforms,
-although strictly speaking using a type that also implies a memory fence
-is required.
+(from F<signal.h>), which is usually good enough on most platforms.
 
 =item EV_H (h)
 
@@ -4995,7 +5017,7 @@
 
 =back
 
-See also L<THREAD LOCKING EXAMPLE>.
+See also L</THREAD LOCKING EXAMPLE>.
 
 =head3 COROUTINES
 
@@ -5296,8 +5318,8 @@
 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.
+except the initial one, and run the signal handling loop in the initial
+thread as well.
 
 =item C<long> must be large enough for common memory allocation sizes
 
@@ -5411,7 +5433,7 @@
 =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>
+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
@@ -5464,7 +5486,7 @@
 =item active
 
 A watcher is active as long as it has been started and not yet stopped.
-See L<WATCHER STATES> for details.
+See L</WATCHER STATES> for details.
 
 =item application
 
@@ -5510,7 +5532,7 @@
 =item pending
 
 A watcher is pending as soon as the corresponding event has been
-detected. See L<WATCHER STATES> for details.
+detected. See L</WATCHER STATES> for details.
 
 =item real time