--- AnyEvent/README	2007/11/09 19:37:05	1.12
+++ AnyEvent/README	2008/04/07 19:46:50	1.14
@@ -18,6 +18,48 @@
        $w->wait; # enters "main loop" till $condvar gets ->broadcast
        $w->broadcast; # wake up current and all future wait's
 
+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 *compatible*, AnyEvent is *free of
+    policy* and AnyEvent is *small and efficient*.
+
+    First and foremost, *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
+    *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 *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 can arguably be somewhat
+    useful) and you want to force your users to use the one and only event
+    model, you should *not* use this module.
+
 DESCRIPTION
     AnyEvent provides an identical interface to multiple event loops. This
     allows module authors to utilise an event loop without forcing module
@@ -67,7 +109,7 @@
 
     "fh" the Perl *filehandle* (not filedescriptor) to watch for events.
     "poll" must be a string that is either "r" or "w", that creates a
-    watcher waiting for "r"eadable or "w"ritable events. "cb" teh callback
+    watcher waiting for "r"eadable or "w"ritable events. "cb" the callback
     to invoke everytime the filehandle becomes ready.
 
     Only one io watcher per "fh" and "poll" combination is allowed (i.e. on
@@ -105,7 +147,7 @@
        });
 
        # to cancel the timer:
-       undef $w
+       undef $w;
 
   CONDITION WATCHERS
     Condition watchers can be created by calling the "AnyEvent->condvar"
@@ -114,6 +156,12 @@
     A condition watcher watches for a condition - precisely that the
     "->broadcast" method has been called.
 
+    Note that condition watchers recurse into the event loop - if you have
+    two watchers that call "->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:
 
     $cv->wait
@@ -183,7 +231,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.