--- AnyEvent/lib/AnyEvent.pm	2007/11/23 10:42:00	1.37
+++ AnyEvent/lib/AnyEvent.pm	2008/04/07 19:42:18	1.44
@@ -20,6 +20,51 @@
    $w->wait; # enters "main loop" till $condvar gets ->broadcast
    $w->broadcast; # wake up current and all future wait's
 
+=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
+
+Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
+nowadays. So what is different about AnyEvent?
+
+Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of
+policy> and AnyEvent is I<small and efficient>.
+
+First and foremost, I<AnyEvent is not an event model> itself, it only
+interfaces to whatever event model the main program happens to use in a
+pragmatic way. For event models and certain classes of immortals alike,
+the statement "there can only be one" is a bitter reality, and AnyEvent
+helps hiding the differences.
+
+The goal of AnyEvent is to offer module authors the ability to do event
+programming (waiting for I/O or timer events) without subscribing to a
+religion, a way of living, and most importantly: without forcing your
+module users into the same thing by forcing them to use the same event
+model you use.
+
+For modules like POE or IO::Async (which is actually doing all I/O
+I<synchronously>...), using them in your module is like joining a
+cult: After you joined, you are dependent on them and you cannot use
+anything else, as it is simply incompatible to everything that isn't
+itself.
+
+AnyEvent + POE works fine. AnyEvent + Glib works fine. AnyEvent + Tk
+works fine etc. etc. but none of these work together with the rest: POE
++ IO::Async? no go. Tk + Event? no go. If your module uses one of
+those, every user of your module has to use it, too. If your module
+uses AnyEvent, it works transparently with all event models it supports
+(including stuff like POE and IO::Async).
+
+In addition of being free of having to use I<the one and only true event
+model>, AnyEvent also is free of bloat and policy: with POE or similar
+modules, you get an enourmous amount of code and strict rules you have
+to follow. AnyEvent, on the other hand, is lean and to the point by only
+offering the functionality that is useful, in as thin as a wrapper as
+technically possible.
+
+Of course, if you want lots of policy (this is arguably somewhat useful
+in many cases) and you want to force your users to the one and only event
+model your module forces on them, you should I<not> use this module.
+
+
 =head1 DESCRIPTION
 
 L<AnyEvent> provides an identical interface to multiple event loops. This
@@ -121,6 +166,12 @@
 A condition watcher watches for a condition - precisely that the C<<
 ->broadcast >> method has been called.
 
+Note that condition watchers recurse into the event loop - if you have
+two watchers that call C<< ->wait >> in a round-robbin fashion, you
+lose. Therefore, condition watchers are good to export to your caller, but
+you should avoid making a blocking wait, at least in callbacks, as this
+usually asks for trouble.
+
 The watcher has only two methods:
 
 =over 4
@@ -201,7 +252,7 @@
 
    AnyEvent::Impl::CoroEV    based on Coro::EV, best choice.
    AnyEvent::Impl::EV        based on EV (an interface to libev, also best choice).
-   AnyEvent::Impl::Coro      based on Coro::Event, second best choice.
+   AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
    AnyEvent::Impl::Event     based on Event, also second best choice :)
    AnyEvent::Impl::Glib      based on Glib, second-best choice.
    AnyEvent::Impl::Tk        based on Tk, very bad choice.
@@ -254,7 +305,7 @@
 
 use Carp;
 
-our $VERSION = '2.7';
+our $VERSION = '3.0';
 our $MODEL;
 
 our $AUTOLOAD;
@@ -267,7 +318,7 @@
 my @models = (
    [Coro::EV::             => AnyEvent::Impl::CoroEV::],
    [EV::                   => AnyEvent::Impl::EV::],
-   [Coro::Event::          => AnyEvent::Impl::Coro::],
+   [Coro::Event::          => AnyEvent::Impl::CoroEvent::],
    [Event::                => AnyEvent::Impl::Event::],
    [Glib::                 => AnyEvent::Impl::Glib::],
    [Tk::                   => AnyEvent::Impl::Tk::],
@@ -380,7 +431,7 @@
 our $WNOHANG;
 
 sub _child_wait {
-   while (0 <= (my $pid = waitpid -1, $WNOHANG)) {
+   while (0 < (my $pid = waitpid -1, $WNOHANG)) {
       $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }),
                          (values %{ $PID_CB{0}    || {} });
    }