--- AnyEvent/lib/AnyEvent.pm	2008/04/07 19:42:18	1.44
+++ AnyEvent/lib/AnyEvent.pm	2008/04/14 19:00:23	1.48
@@ -60,9 +60,9 @@
 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.
+Of course, if you want lots of policy (this can arguably be somewhat
+useful) and you want to force your users to use the one and only event
+model, you should I<not> use this module.
 
 
 =head1 DESCRIPTION
@@ -181,16 +181,24 @@
 Wait (blocking if necessary) until the C<< ->broadcast >> method has been
 called on c<$cv>, while servicing other watchers normally.
 
-Not all event models support a blocking wait - some die in that case, so
-if you are using this from a module, never require a blocking wait, but
-let the caller decide wether the call will block or not (for example,
-by coupling condition variables with some kind of request results and
-supporting callbacks so the caller knows that getting the result will not
-block, while still suppporting blockign waits if the caller so desires).
-
 You can only wait once on a condition - additional calls will return
 immediately.
 
+Not all event models support a blocking wait - some die in that case
+(programs might want to do that so they stay interactive), so I<if you
+are using this from a module, never require a blocking wait>, but let the
+caller decide wether the call will block or not (for example, by coupling
+condition variables with some kind of request results and supporting
+callbacks so the caller knows that getting the result will not block,
+while still suppporting blocking waits if the caller so desires).
+
+Another reason I<never> to C<< ->wait >> in a module is that you cannot
+sensibly have two C<< ->wait >>'s in parallel, as that would require
+multiple interpreters or coroutines/threads, none of which C<AnyEvent>
+can supply (the coroutine-aware backends C<Coro::EV> and C<Coro::Event>
+explicitly support concurrent C<< ->wait >>'s from different coroutines,
+however).
+
 =item $cv->broadcast
 
 Flag the condition as ready - a running C<< ->wait >> and all further
@@ -254,9 +262,9 @@
    AnyEvent::Impl::EV        based on EV (an interface to libev, also 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::Glib      based on Glib, third-best choice.
    AnyEvent::Impl::Tk        based on Tk, very bad choice.
-   AnyEvent::Impl::Perl      pure-perl implementation, inefficient.
+   AnyEvent::Impl::Perl      pure-perl implementation, inefficient but portable.
 
 =item AnyEvent::detect