--- Coro/Coro.pm	2011/08/03 14:52:18	1.304
+++ Coro/Coro.pm	2012/12/07 23:23:15	1.314
@@ -197,8 +197,8 @@
       Coro::terminate "return value 1", "return value 2";
    };
 
-And yet another way is to C<< ->cancel >> (or C<< ->safe_cancel >>) the
-coro thread from another thread:
+Yet another way is to C<< ->cancel >> (or C<< ->safe_cancel >>) the coro
+thread from another thread:
 
    my $coro = async {
       exit 1;
@@ -220,12 +220,13 @@
 when a thread is in a C<tie> method or an C<AUTOLOAD> for example) is
 safe.
 
-Lastly, a coro thread object that isn't referenced is C<< ->cancel >>'ed
-automatically - just like other objects in Perl. This is not such a common
-case, however - a running thread is referencedy b C<$Coro::current>, a
-thread ready to run is referenced by the ready queue, a thread waiting
-on a lock or semaphore is referenced by being in some wait list and so
-on. But a thread that isn't in any of those queues gets cancelled:
+Last not least, a coro thread object that isn't referenced is C<<
+->cancel >>'ed automatically - just like other objects in Perl. This
+is not such a common case, however - a running thread is referencedy by
+C<$Coro::current>, a thread ready to run is referenced by the ready queue,
+a thread waiting on a lock or semaphore is referenced by being in some
+wait list and so on. But a thread that isn't in any of those queues gets
+cancelled:
 
    async {
       schedule; # cede to other coros, don't go into the ready queue
@@ -234,6 +235,28 @@
    cede;
    # now the async above is destroyed, as it is not referenced by anything.
 
+A slightly embellished example might make it clearer:
+
+   async {
+      my $guard = Guard::guard { print "destroyed\n" };
+      schedule while 1;
+   };
+
+   cede;
+
+Superficially one might not expect any output - since the C<async>
+implements an endless loop, the C<$guard> will not be cleaned up. However,
+since the thread object returned by C<async> is not stored anywhere, the
+thread is initially referenced because it is in the ready queue, when it
+runs it is referenced by C<$Coro::current>, but when it calls C<schedule>,
+it gets C<cancel>ed causing the guard object to be destroyed (see the next
+section), and printing it's message.
+
+If this seems a bit drastic, remember that this only happens when nothing
+references the thread anymore, which means there is no way to further
+execute it, ever. The only options at this point are leaking the thread,
+or cleaning it up, which brings us to...
+
 =item 5. Cleanup
 
 Threads will allocate various resources. Most but not all will be returned
@@ -261,12 +284,12 @@
 
    async {
       my $lock_guard = $sem->guard;
-      # if we reutrn, or die or get cancelled, here,
+      # if we return, or die or get cancelled, here,
       # then the semaphore will be "up"ed.
    };
 
 The C<Guard::guard> function comes in handy for any custom cleanup you
-might want to do (but you cannot switch to other coroutines form those
+might want to do (but you cannot switch to other coroutines from those
 code blocks):
 
    async {
@@ -293,11 +316,12 @@
 Even after a thread has terminated and cleaned up its resources, the Coro
 object still is there and stores the return values of the thread.
 
-The means the Coro object gets freed automatically when the thread has
-terminated and cleaned up and there arenot other references.
+When there are no other references, it will simply be cleaned up and
+freed.
 
-If there are, the Coro object will stay around, and you can call C<<
-->join >> as many times as you wish to retrieve the result values:
+If there areany references, the Coro object will stay around, and you
+can call C<< ->join >> as many times as you wish to retrieve the result
+values:
 
    async {
       print "hi\n";
@@ -344,7 +368,7 @@
 our $main;    # main coro
 our $current; # current coro
 
-our $VERSION = 6.04;
+our $VERSION = 6.23;
 
 our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait);
 our %EXPORT_TAGS = (
@@ -359,7 +383,7 @@
 =item $Coro::main
 
 This variable stores the Coro object that represents the main
-program. While you cna C<ready> it and do most other things you can do to
+program. While you can C<ready> it and do most other things you can do to
 coro, it is mainly useful to compare again C<$Coro::current>, to see
 whether you are running in the main program or not.
 
@@ -929,7 +953,7 @@
 
 This method simply sets the C<< $coro->{desc} >> member to the given
 string. You can modify this member directly if you wish, and in fact, this
-is often preferred to indicate major processing states that cna then be
+is often preferred to indicate major processing states that can then be
 seen for example in a L<Coro::Debug> session:
 
    sub my_long_function {
@@ -1131,7 +1155,7 @@
    }
 
 In the case where C<rouse_cb> and C<rouse_wait> are not flexible enough,
-you can roll your own, using C<schedule>:
+you can roll your own, using C<schedule> and C<ready>:
 
    sub wait_for_child($) {
       my ($pid) = @_;
@@ -1144,7 +1168,8 @@
       # pass a closure to ->child
       my $watcher = AnyEvent->child (pid => $pid, cb => sub {
          $rstatus = $_[1]; # remember rstatus
-         $done = 1; # mark $rstatus as valud
+         $done = 1;        # mark $rstatus as valid
+         $current->ready;  # wake up the waiting thread
       });
 
       # wait until the closure has been called