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

Comparing Coro/Coro.pm (file contents):
Revision 1.79 by root, Fri Nov 3 00:56:02 2006 UTC vs.
Revision 1.91 by root, Fri Dec 1 02:17:37 2006 UTC

 use strict;
 no warnings "uninitialized";
 use Coro::State;
-use base Exporter::;
+use base qw(Coro::State Exporter);
-our $idle;    # idle coroutine
+our $idle;    # idle handler
 our $main;    # main coroutine
 our $current; # current coroutine
-our $VERSION = '2.1';
+our $VERSION = '3.0';
 our @EXPORT = qw(async cede schedule terminate current);
 our %EXPORT_TAGS = (
       prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
 );
 $main = new Coro;
 =item $current (or as function: current)
-The current coroutine (the last coroutine switched to). The initial value is C<$main> (of course).
+The current coroutine (the last coroutine switched to). The initial value
+is C<$main> (of course).
+This variable is B<strictly> I<read-only>. It is provided for performance
+reasons. If performance is not essentiel you are encouraged to use the
+C<Coro::current> function instead.
 =cut
 # maybe some other module used Coro::Specific before...
 if ($current) {
 sub current() { $current }
 =item $idle
-The coroutine to switch to when no other coroutine is running. The default
+A callback that is called whenever the scheduler finds no ready coroutines
-implementation prints "FATAL: deadlock detected" and exits.
+to run. The default implementation prints "FATAL: deadlock detected" and
+exits, because the program has no other way to continue.
-=cut
+This hook is overwritten by modules such as C<Coro::Timer> and
+C<Coro::Event> to wait on an external event that hopefully wake up a
+coroutine so the scheduler can run it.
-# should be done using priorities :(
+Please note that if your callback recursively invokes perl (e.g. for event
-$idle = new Coro sub {
+handlers), then it must be prepared to be called recursively.
+=cut
+$idle = sub {
    print STDERR "FATAL: deadlock detected\n";
-   exit(51);
+   exit (51);
 };
 # this coroutine is necessary because a coroutine
 # cannot destroy itself.
 my @destroy;
-my $manager;
-$manager = new Coro sub {
+my $manager; $manager = new Coro sub {
    while () {
       # by overwriting the state object with the manager we destroy it
       # while still being able to schedule this coroutine (in case it has
       # been readied multiple times. this is harmless since the manager
       # can be called as many times as neccessary and will always
       while (@destroy) {
          my $coro = pop @destroy;
          $coro->{status} ||= [];
          $_->ready for @{delete $coro->{join} || []};
-         # the next line destroys the _coro_state, but keeps the
+         # the next line destroys the coro state, but keeps the
          # process itself intact (we basically make it a zombie
          # process that always runs the manager thread, so it's possible
          # to transfer() to this process).
-         $coro->{_coro_state} = $manager->{_coro_state};
+         $coro->_clone_state_from ($manager);
       }
       &schedule;
    }
 };
 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 {
 =cut
 sub async(&@) {
    my $pid = new Coro @_;
-   $manager->ready; # this ensures that the stack is cloned from the manager
    $pid->ready;
-   $pid;
+   $pid
 }
 =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.
-=cut
+Calling C<exit> in a coroutine will not work correctly, so do not do that.
+=cut
-sub _newcoro {
+sub _new_coro {
    terminate &{+shift};
 }
 sub new {
    my $class = shift;
-   bless {
-      _coro_state => (new Coro::State $_[0] && \&_newcoro, @_),
-   }, $class;
-}
+   $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).
       &schedule;
    }
    wantarray ? @{$self->{status}} : $self->{status}[0];
 }
-=item $oldprio = $process->prio($newprio)
+=item $oldprio = $process->prio ($newprio)
 Sets (or gets, if the argument is missing) the priority of the
 process. Higher priority processes get run before lower priority
 processes. Priorities are small signed integers (currently -4 .. +3),
 that you can refer to using PRIO_xxx constants (use the import tag :prio
 Changing the priority of the current process will take effect immediately,
 but changing the priority of processes in the ready queue (but not
 running) will only take effect after the next schedule (of that
 process). This is a bug that will be fixed in some future version.
-=cut
-sub prio {
-   my $old = $_[0]{prio};
-   $_[0]{prio} = $_[1] if @_ > 1;
-   $old;
-}
-=item $newprio = $process->nice($change)
+=item $newprio = $process->nice ($change)
 Similar to C<prio>, but subtract the given value from the priority (i.e.
 higher values mean lower priority, just as in unix).
-=cut
-sub nice {
-   $_[0]{prio} -= $_[1];
-}
-=item $olddesc = $process->desc($newdesc)
+=item $olddesc = $process->desc ($newdesc)
 Sets (or gets in case the argument is missing) the description for this
 process. This is just a free-form string you can associate with a process.
 =cut

Diff Legend

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

Comparing Coro/Coro.pm (file contents): Revision 1.79 by root, Fri Nov 3 00:56:02 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.79 by root, Fri Nov 3 00:56:02 2006 UTC vs.
Revision 1.91 by root, Fri Dec 1 02:17:37 2006 UTC