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

Comparing Coro/Coro.pm (file contents):
Revision 1.88 by root, Sun Nov 26 02:54:55 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";
 Create a new asynchronous process and return it's process object
 (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.
    # create a new coroutine that just prints its arguments
    async {
 =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
 Create a new process and return it. When the sub returns the process
 automatically terminates as if C<terminate> with the returned values were
 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 {
    terminate &{+shift};
 }
    my $class = shift;
    $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...)
 Terminates the given process and makes it return the given arguments as
 status (default: the empty list).

Diff Legend

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

Comparing Coro/Coro.pm (file contents): Revision 1.88 by root, Sun Nov 26 02:54:55 2006 UTC vs. Revision 1.91 by root, Fri Dec 1 02:17:37 2006 UTC

Diff Legend

Comparing Coro/Coro.pm (file contents):
Revision 1.88 by root, Sun Nov 26 02:54:55 2006 UTC vs.
Revision 1.91 by root, Fri Dec 1 02:17:37 2006 UTC