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

Comparing Coro/Coro.pm (file contents):
Revision 1.38 by root, Wed Oct 3 01:09:56 2001 UTC vs.
Revision 1.61 by pcg, Fri May 14 13:25:08 2004 UTC

  cede;
 =head1 DESCRIPTION
 This module collection manages coroutines. Coroutines are similar to
-Threads but don't run in parallel.
+threads but don't run in parallel.
-This module is still experimental, see the BUGS section below.
 In this module, coroutines are defined as "callchain + lexical variables
 + @_ + $_ + $@ + $^W + C stack), that is, a coroutine has it's own
 callchain, it's own set of lexicals and it's own set of perl's most
 important global variables.
 =cut
 package Coro;
-no warnings qw(uninitialized);
+BEGIN { eval { require warnings } && warnings->unimport ("uninitialized") }
 use Coro::State;
+use vars qw($idle $main $current);
 use base Exporter;
-$VERSION = 0.51;
+$VERSION = 0.97;
 @EXPORT = qw(async cede schedule terminate current);
 %EXPORT_TAGS = (
       prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
 );
       };
    }
 }
+=over 4
 =item $main
 This coroutine represents the main program.
 =cut
-our $main = new Coro;
+$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).
 # maybe some other module used Coro::Specific before...
 if ($current) {
    $main->{specific} = $current->{specific};
 }
-our $current = $main;
+$current = $main;
 sub current() { $current }
 =item $idle
 implementation prints "FATAL: deadlock detected" and exits.
 =cut
 # should be done using priorities :(
-our $idle = new Coro sub {
+$idle = new Coro sub {
    print STDERR "FATAL: deadlock detected\n";
    exit(51);
 };
 # this coroutine is necessary because a coroutine
 # cannot destroy itself.
 my @destroy;
 my $manager;
 $manager = new Coro sub {
-   while() {
+   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
       # remove itself from the runqueue
+      while (@destroy) {
+         my $coro = pop @destroy;
+         $coro->{status} ||= [];
+         $_->ready for @{delete $coro->{join} || []};
+         # 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).
-      (pop @destroy)->{_coro_state} = $manager->{_coro_state} while @destroy;
+         $coro->{_coro_state} = $manager->{_coro_state};
+      }
       &schedule;
    }
 };
 # static methods. not really.
+=back
 =head2 STATIC METHODS
 Static methods are actually functions that operate on the current process only.
    # create a new coroutine that just prints its arguments
    async {
       print "@_\n";
    } 1,2,3,4;
-The coderef you submit MUST NOT be a closure that refers to variables
-in an outer scope. This does NOT work. Pass arguments into it instead.
 =cut
 sub async(&@) {
    my $pid = new Coro @_;
 ready queue and calls C<schedule>, which has the effect of giving up the
 current "timeslice" to other coroutines of the same or higher priority.
 =cut
-=item terminate
+=item terminate [arg...]
-Terminates the current process.
+Terminates the current process with the given status values (see L<cancel>).
-Future versions of this function will allow result arguments.
 =cut
 sub terminate {
-   $current->cancel;
+   $current->cancel (@_);
-   &schedule;
-   die; # NORETURN
 }
 =back
 # dynamic methods
 =over 4
 =item new Coro \&sub [, @args...]
 Create a new process and return it. When the sub returns the process
-automatically terminates. To start the process you must first put it into
+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
-the ready queue by calling the ready method.
+by calling the ready method.
-The coderef you submit MUST NOT be a closure that refers to variables
-in an outer scope. This does NOT work. Pass arguments into it instead.
 =cut
 sub _newcoro {
    terminate &{+shift};
    }, $class;
 }
 =item $process->ready
-Put the current process into the ready queue.
+Put the given process into the ready queue.
 =cut
-=item $process->cancel
+=item $process->cancel (arg...)
-Like C<terminate>, but terminates the specified process instead.
+Temrinates the given process and makes it return the given arguments as
+status (default: the empty list).
 =cut
 sub cancel {
+   my $self = shift;
+   $self->{status} = [@_];
-   push @destroy, $_[0];
+   push @destroy, $self;
    $manager->ready;
-   &schedule if $current == $_[0];
+   &schedule if $current == $self;
+}
+=item $process->join
+Wait until the coroutine terminates and return any values given to the
+C<terminate> or C<cancel> functions. C<join> can be called multiple times
+from multiple processes.
+=cut
+sub join {
+   my $self = shift;
+   unless ($self->{status}) {
+      push @{$self->{join}}, $current;
+      &schedule;
+   }
+   wantarray ? @{$self->{status}} : $self->{status}[0];
 }
 =item $oldprio = $process->prio($newprio)
-Sets the priority of the process. Higher priority processes get run before
+Sets (or gets, if the argument is missing) the priority of the
+process. Higher priority processes get run before lower priority
-lower priority processes. Priorities are smalled signed integer (currently
+processes. Priorities are small signed integers (currently -4 .. +3),
--4 .. +3), that you can refer to using PRIO_xxx constants (use the import
+that you can refer to using PRIO_xxx constants (use the import tag :prio
-tag :prio to get then):
+to get then):
    PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
        3    >     1     >      0      >    -1    >    -3     >    -4
    # set priority to HIGH
 sub nice {
    $_[0]{prio} -= $_[1];
 }
+=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
+sub desc {
+   my $old = $_[0]{desc};
+   $_[0]{desc} = $_[1] if @_ > 1;
+   $old;
+}
 =back
 =cut
 1;
 =head1 BUGS/LIMITATIONS
- - you must make very sure that no coro is still active on global destruction.
+ - you must make very sure that no coro is still active on global
-   very bad things might happen otherwise (usually segfaults).
+   destruction. very bad things might happen otherwise (usually segfaults).
- - this module is not thread-safe. You must only ever use this module from
+ - this module is not thread-safe. You should only ever use this module
-   the same thread (this requirement might be loosened in the future to
+   from the same thread (this requirement might be losened in the future
-   allow per-thread schedulers, but Coro::State does not yet allow this).
+   to allow per-thread schedulers, but Coro::State does not yet allow
+   this).
 =head1 SEE ALSO
 L<Coro::Channel>, L<Coro::Cont>, L<Coro::Specific>, L<Coro::Semaphore>,
-L<Coro::Signal>, L<Coro::State>, L<Coro::Event>, L<Coro::RWLock>,
+L<Coro::Signal>, L<Coro::State>, L<Coro::Timer>, L<Coro::Event>,
-L<Coro::Handle>, L<Coro::Socket>.
+L<Coro::L<Coro::RWLock>, Handle>, L<Coro::Socket>.
 =head1 AUTHOR
  Marc Lehmann <pcg@goof.com>
  http://www.goof.com/pcg/marc/

Diff Legend

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

Comparing Coro/Coro.pm (file contents): Revision 1.38 by root, Wed Oct 3 01:09:56 2001 UTC vs. Revision 1.61 by pcg, Fri May 14 13:25:08 2004 UTC

Diff Legend

Comparing Coro/Coro.pm (file contents):
Revision 1.38 by root, Wed Oct 3 01:09:56 2001 UTC vs.
Revision 1.61 by pcg, Fri May 14 13:25:08 2004 UTC