--- Coro/Coro.pm	2006/11/25 01:14:11	1.86
+++ Coro/Coro.pm	2006/12/01 02:17:37	1.91
@@ -43,7 +43,7 @@
 our $main;    # main coroutine
 our $current; # current coroutine
 
-our $VERSION = '2.5';
+our $VERSION = '3.0';
 
 our @EXPORT = qw(async cede schedule terminate current);
 our %EXPORT_TAGS = (
@@ -119,11 +119,14 @@
 
 A callback that is called whenever the scheduler finds no ready coroutines
 to run. The default implementation prints "FATAL: deadlock detected" and
-exits.
+exits, because the program has no other way to continue.
 
 This hook is overwritten by modules such as C<Coro::Timer> and
-C<Coro::Event> to wait on an external event that hopefully wakes up some
-coroutine.
+C<Coro::Event> to wait on an external event that hopefully wake up a
+coroutine so the scheduler can run it.
+
+Please note that if your callback recursively invokes perl (e.g. for event
+handlers), then it must be prepared to be called recursively.
 
 =cut
 
@@ -173,6 +176,8 @@
 (usually unused). When the sub returns the new process is automatically
 terminated.
 
+Calling C<exit> in a coroutine will not work correctly, so do not do that.
+
 When the coroutine dies, the program will exit, just as in the main
 program.
 
@@ -193,7 +198,27 @@
 
 Calls the scheduler. Please note that the current process will not be put
 into the ready queue, so calling this function usually means you will
-never be called again.
+never be called again unless something else (e.g. an event handler) calls
+ready.
+
+The canonical way to wait on external events is this:
+
+   {
+      # remember current process
+      my $current = $Coro::current;
+
+      # register a hypothetical event handler
+      on_event_invoke sub {
+         # wake up sleeping coroutine
+         $current->ready;
+         undef $current;
+      };
+
+      # call schedule until event occured.
+      # in case we are woken up for other reasons
+      # (current still defined), loop.
+      Coro::schedule while $current;
+   }
 
 =cut
 
@@ -232,12 +257,11 @@
 called. To make the process run you must first put it into the ready queue
 by calling the ready method.
 
+Calling C<exit> in a coroutine will not work correctly, so do not do that.
+
 =cut
 
 sub _new_coro {
-   $current->_clear_idle_sp; # (re-)set the idle sp on the following cede
-   _set_cede_self;  # ensures that cede cede's us first
-   cede;
    terminate &{+shift};
 }
 
@@ -247,11 +271,15 @@
    $class->SUPER::new (\&_new_coro, @_)
 }
 
-=item $process->ready
+=item $success = $process->ready
 
-Put the given process into the ready queue.
+Put the given process into the ready queue (according to it's priority)
+and return true. If the process is already in the ready queue, do nothing
+and return false.
 
-=cut
+=item $is_ready = $process->is_ready
+
+Return wether the process is currently the ready queue or not,
 
 =item $process->cancel (arg...)