--- Coro/Coro.pm	2008/05/09 22:04:37	1.181
+++ Coro/Coro.pm	2008/10/30 09:57:00	1.206
@@ -18,6 +18,7 @@
   cede; # and again
   
   # use locking
+  use Coro::Semaphore;
   my $lock = new Coro::Semaphore;
   my $locked;
   
@@ -37,8 +38,9 @@
 
 Unlike a normal perl program, however, coroutines allow you to have
 multiple running interpreters that share data, which is especially useful
-to code pseudo-parallel processes, such as multiple HTTP-GET requests
-running concurrently.
+to code pseudo-parallel processes and for event-based programming, such as
+multiple HTTP-GET requests running concurrently. See L<Coro::AnyEvent> to
+learn more.
 
 Coroutines are also useful because Perl has no support for threads (the so
 called "threads" that perl offers are nothing more than the (bad) process
@@ -67,7 +69,7 @@
 our $main;    # main coroutine
 our $current; # current coroutine
 
-our $VERSION = 4.6;
+our $VERSION = 4.802;
 
 our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
 our %EXPORT_TAGS = (
@@ -82,7 +84,7 @@
 This variable stores the coroutine object that represents the main
 program. While you cna C<ready> it and do most other things you can do to
 coroutines, it is mainly useful to compare again C<$Coro::current>, to see
-wether you are running in the main program or not.
+whether you are running in the main program or not.
 
 =cut
 
@@ -221,7 +223,7 @@
 or bad :).
 
 On the plus side, this function is faster than creating (and destroying)
-a completely new coroutine, so if you need a lot of generic coroutines in
+a completly new coroutine, so if you need a lot of generic coroutines in
 quick successsion, use C<async_pool>, not C<async>.
 
 The code block is executed in an C<eval> context and a warning will be
@@ -235,12 +237,12 @@
 disabled, the description will be reset and the default output filehandle
 gets restored, so you can change all these. Otherwise the coroutine will
 be re-used "as-is": most notably if you change other per-coroutine global
-stuff such as C<$/> you I<must needs> to revert that change, which is most
-simply done by using local as in: C< local $/ >.
+stuff such as C<$/> you I<must needs> revert that change, which is most
+simply done by using local as in: C<< local $/ >>.
 
-The pool size is limited to C<8> idle coroutines (this can be adjusted by
-changing $Coro::POOL_SIZE), and there can be as many non-idle coros as
-required.
+The idle pool size is limited to C<8> idle coroutines (this can be
+adjusted by changing $Coro::POOL_SIZE), but there can be as many non-idle
+coros as required.
 
 If you are concerned about pooled coroutines growing a lot because a
 single C<async_pool> used a lot of stackspace you can e.g. C<async_pool
@@ -267,8 +269,10 @@
          }
       };
 
-      last if $@ eq "\3async_pool terminate\2\n";
-      warn $@ if $@;
+      if ($@) {
+         last if $@ eq "\3async_pool terminate\2\n";
+         warn $@;
+      }
    }
 }
 
@@ -308,7 +312,7 @@
 a variable, then arrange for some callback of yours to call C<< ->ready
 >> on that once some event happens, and last you call C<schedule> to put
 yourself to sleep. Note that a lot of things can wake your coroutine up,
-so you need to check wether the event indeed happened, e.g. by storing the
+so you need to check whether the event indeed happened, e.g. by storing the
 status in a variable.
 
 The canonical way to wait on external events is this:
@@ -357,7 +361,7 @@
 usually only one of them should inherit the running coroutines.
 
 Note that while this will try to free some of the main programs resources,
-you cnanot free all of them, so if a coroutine that is not the main
+you cannot free all of them, so if a coroutine that is not the main
 program calls this function, there will be some one-time resource leak.
 
 =cut
@@ -416,7 +420,7 @@
 
 =item $is_ready = $coroutine->is_ready
 
-Return wether the coroutine is currently the ready queue or not,
+Return whether the coroutine is currently the ready queue or not,
 
 =item $coroutine->cancel (arg...)
 
@@ -613,6 +617,12 @@
 another coroutine, or puts some other coroutine into the ready queue),
 there is no reason to use C<unblock_sub>.
 
+Note that you also need to use C<unblock_sub> for any other callbacks that
+are indirectly executed by any C-based event loop. For example, when you
+use a module that uses L<AnyEvent> (and you use L<Coro::AnyEvent>) and it
+provides callbacks that are the result of some event callback, then you
+must not block either, or use C<unblock_sub>.
+
 =cut
 
 our @unblock_queue;