[ViewVC] Diff of: cvs/Coro/Coro.pm

Comparing Coro/Coro.pm (file contents):
Revision 1.90 by root, Thu Nov 30 18:21:14 2006 UTC vs.
Revision 1.91 by root, Fri Dec 1 02:17:37 2006 UTC

 =item $idle
 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
+C<Coro::Event> to wait on an external event that hopefully wake up a
-coroutine.
+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
 $idle = sub {
    print STDERR "FATAL: deadlock detected\n";
 =item schedule
 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
 =item cede

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines