--- Coro/Coro.pm	2001/07/22 03:24:10	1.21
+++ Coro/Coro.pm	2005/02/22 19:51:58	1.65
@@ -16,41 +16,41 @@
     # some more async code
  }
 
- yield;
+ cede;
 
 =head1 DESCRIPTION
 
 This module collection manages coroutines. Coroutines are similar to
-Threads but don't run in parallel.
-
-This module is still experimental, see the BUGS section below.
+threads but don't run in parallel.
 
 In this module, coroutines are defined as "callchain + lexical variables
-+ @_ + $_ + $@ + $^W), 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.
-
-WARNING: When using this module, make sure that, at program end, no
-coroutines are still running OR just call exit before falling off the
-end. The reason for this is that some coroutine of yours might have called
-into a C function, and falling off the end of main:: results in returning
-to that C function instead if to the main C interpreter.
++ @_ + $_ + $@ + $^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;
 
+BEGIN { eval { require warnings } && warnings->unimport ("uninitialized") }
+
 use Coro::State;
 
+use vars qw($idle $main $current);
+
 use base Exporter;
 
-$VERSION = 0.10;
+$VERSION = 1.1;
 
-@EXPORT = qw(async yield schedule terminate current);
-@EXPORT_OK = qw($current);
+@EXPORT = qw(async cede schedule terminate current);
+%EXPORT_TAGS = (
+      prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
+);
+@EXPORT_OK = @{$EXPORT_TAGS{prio}};
 
 {
    my @async;
+   my $init;
 
    # this way of handling attributes simply is NOT scalable ;()
    sub import {
@@ -62,6 +62,13 @@
          for (@_) {
             if ($_ eq "Coro") {
                push @async, $ref;
+               unless ($init++) {
+                  eval q{
+                     sub INIT {
+                        &async(pop @async) while @async;
+                     }
+                  };
+               }
             } else {
                push @attrs, $_;
             }
@@ -70,18 +77,17 @@
       };
    }
 
-   sub INIT {
-      &async(pop @async) while @async;
-   }
 }
 
+=over 4
+
 =item $main
 
 This coroutine represents the main program.
 
 =cut
 
-our $main = new Coro;
+$main = new Coro;
 
 =item $current (or as function: current)
 
@@ -94,7 +100,7 @@
    $main->{specific} = $current->{specific};
 }
 
-our $current = $main;
+$current = $main;
 
 sub current() { $current }
 
@@ -106,16 +112,41 @@
 =cut
 
 # should be done using priorities :(
-our $idle = new Coro sub {
+$idle = new Coro sub {
    print STDERR "FATAL: deadlock detected\n";
    exit(51);
 };
 
-# we really need priorities...
-my @ready; # the ready queue. hehe, rather broken ;)
+# this coroutine is necessary because a coroutine
+# cannot destroy itself.
+my @destroy;
+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
+      # 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).
+         $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.
@@ -133,13 +164,11 @@
       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 @_;
+   $manager->ready; # this ensures that the stack is cloned from the manager
    $pid->ready;
    $pid;
 }
@@ -152,38 +181,22 @@
 
 =cut
 
-my $prev;
-
-sub schedule {
-   # should be done using priorities :(
-   ($prev, $current) = ($current, shift @ready || $idle);
-   Coro::State::transfer($prev, $current);
-}
-
-=item yield
+=item cede
 
-Yield to other processes. This function puts the current process into the
-ready queue and calls C<schedule>.
+"Cede" to other processes. This function puts the current process into the
+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
 
-sub yield {
-   $current->ready;
-   &schedule;
-}
-
-=item terminate
-
-Terminates the current process.
+=item terminate [arg...]
 
-Future versions of this function will allow result arguments.
+Terminates the current process with the given status values (see L<cancel>).
 
 =cut
 
 sub terminate {
-   $current->{_results} = [@_];
-   delete $current->{_coro_state};
-   &schedule;
+   $current->cancel (@_);
 }
 
 =back
@@ -199,11 +212,9 @@
 =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
-the ready queue 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.
+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
 
@@ -220,12 +231,94 @@
 
 =item $process->ready
 
-Put the current process into the ready queue.
+Put the given process into the ready queue.
+
+=cut
+
+=item $process->cancel (arg...)
+
+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, $self;
+   $manager->ready;
+   &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 (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
+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
+   current->prio(PRIO_HIGH);
+
+The idle coroutine ($Coro::idle) always has a lower priority than any
+existing coroutine.
+
+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 ready {
-   push @ready, $_[0];
+sub prio {
+   my $old = $_[0]{prio};
+   $_[0]{prio} = $_[1] if @_ > 1;
+   $old;
+}
+
+=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)
+
+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
@@ -236,27 +329,24 @@
 
 =head1 BUGS/LIMITATIONS
 
- - could be faster, especially when the core would introduce special
-   support for coroutines (like it does for threads).
- - there is still a memleak on coroutine termination that I could not
-   identify. Could be as small as a single SV.
- - this module is not well-tested.
- - if variables or arguments "disappear" (become undef) or become
-   corrupted please contact the author so he cen iron out the
-   remaining bugs.
- - this module is not thread-safe. You must only ever use this module from
-   the same thread (this requirement might be loosened in the future to
-   allow per-thread schedulers, but Coro::State does not yet allow this).
+ - you must make very sure that no coro is still active on global
+   destruction. very bad things might happen otherwise (usually segfaults).
+
+ - this module is not thread-safe. You should only ever use this module
+   from the same thread (this requirement might be losened in the future
+   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::Signal>, L<Coro::State>, L<Coro::Timer>, L<Coro::Event>,
+L<Coro::Handle>, L<Coro::RWLock>, L<Coro::Socket>.
 
 =head1 AUTHOR
 
  Marc Lehmann <pcg@goof.com>
- http://www.goof.com/pcg/marc/
+ http://home.schmorp.de/
 
 =cut