--- Coro/Coro.pm	2012/12/07 23:23:15	1.314
+++ Coro/Coro.pm	2014/09/06 20:14:25	1.328
@@ -368,7 +368,7 @@
 our $main;    # main coro
 our $current; # current coro
 
-our $VERSION = 6.23;
+our $VERSION = 6.41;
 
 our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait);
 our %EXPORT_TAGS = (
@@ -654,14 +654,14 @@
          $SIG{VTALRM} = sub { cede };
          # and then start the interval timer
          Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
-      }; 
+      };
       Coro::on_leave {
          # on leaving the thread, we stop the interval timer again
          Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
-      }; 
+      };
 
       &{+shift};
-   }  
+   }
 
    # use like this:
    timeslice {
@@ -669,7 +669,7 @@
       # monopolise the process. Since it runs in a timesliced
       # environment, it will regularly cede to other threads.
       while () { }
-   }; 
+   };
 
 
 =item killall
@@ -795,12 +795,16 @@
 complicated cleanup handlers that rely on its thread context, things will
 not work.
 
-Any cleanup code being run (e.g. from C<guard> blocks) will be run without
-a thread context, and is not allowed to switch to other threads. On the
-plus side, C<< ->cancel >> will always clean up the thread, no matter
-what.  If your cleanup code is complex or you want to avoid cancelling a
-C-thread that doesn't know how to clean up itself, it can be better to C<<
-->throw >> an exception, or use C<< ->safe_cancel >>.
+Any cleanup code being run (e.g. from C<guard> blocks, destructors and so
+on) will be run without a thread context, and is not allowed to switch
+to other threads. A common mistake is to call C<< ->cancel >> from a
+destructor called by die'ing inside the thread to be cancelled for
+example.
+
+On the plus side, C<< ->cancel >> will always clean up the thread, no
+matter what.  If your cleanup code is complex or you want to avoid
+cancelling a C-thread that doesn't know how to clean up itself, it can be
+better to C<< ->throw >> an exception, or use C<< ->safe_cancel >>.
 
 The arguments to C<< ->cancel >> are not copied, but instead will
 be referenced directly (e.g. if you pass C<$var> and after the call
@@ -816,11 +820,12 @@
 
 Works mostly like C<< ->cancel >>, but is inherently "safer", and
 consequently, can fail with an exception in cases the thread is not in a
-cancellable state.
+cancellable state. Essentially, C<< ->safe_cancel >> is a C<< ->cancel >>
+with extra checks before canceling.
 
-This method works a bit like throwing an exception that cannot be caught
-- specifically, it will clean up the thread from within itself, so
-all cleanup handlers (e.g. C<guard> blocks) are run with full thread
+It works a bit like throwing an exception that cannot be caught -
+specifically, it will clean up the thread from within itself, so all
+cleanup handlers (e.g. C<guard> blocks) are run with full thread
 context and can block if they wish. The downside is that there is no
 guarantee that the thread can be cancelled when you call this method, and
 therefore, it might fail. It is also considerably slower than C<cancel> or
@@ -916,7 +921,7 @@
 not> die, under any circumstances.
 
 There can be any number of C<on_destroy> callbacks per coro, and there is
-no way currently to remove a callback once added.
+currently no way to remove a callback once added.
 
 =item $oldprio = $coro->prio ($newprio)
 
@@ -1132,7 +1137,7 @@
    my $status = wait_for_child $pid;
 
 Coro offers two functions specifically designed to make this easy,
-C<Coro::rouse_cb> and C<Coro::rouse_wait>.
+C<rouse_cb> and C<rouse_wait>.
 
 The first function, C<rouse_cb>, generates and returns a callback that,
 when invoked, will save its arguments and notify the coro that
@@ -1148,9 +1153,9 @@
    sub wait_for_child($) {
       my ($pid) = @_;
 
-      my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb);
+      my $watcher = AnyEvent->child (pid => $pid, cb => rouse_cb);
 
-      my ($rpid, $rstatus) = Coro::rouse_wait;
+      my ($rpid, $rstatus) = rouse_wait;
       $rstatus
    }