--- Coro/Coro.pm	2001/09/24 02:25:44	1.37
+++ Coro/Coro.pm	2003/05/27 01:15:26	1.53
@@ -21,9 +21,7 @@
 =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 + C stack), that is, a coroutine has it's own
@@ -40,7 +38,7 @@
 
 use base Exporter;
 
-$VERSION = 0.5;
+$VERSION = 0.7;
 
 @EXPORT = qw(async cede schedule terminate current);
 %EXPORT_TAGS = (
@@ -79,6 +77,8 @@
 
 }
 
+=over 4
+
 =item $main
 
 This coroutine represents the main program.
@@ -118,20 +118,28 @@
 # this coroutine is necessary because a coroutine
 # cannot destroy itself.
 my @destroy;
-my $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
       # remove itself from the runqueue
-      (pop @destroy)->{_coro_state} = $manager->{_coro_state} while @destroy;
+      while (@destroy) {
+         my $coro = pop @destroy;
+         $coro->{status} ||= [];
+         $_->ready for @{delete $coro->{join} || []};
+         $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.
@@ -177,7 +185,7 @@
 
 =cut
 
-=item terminate
+=item terminate [arg...]
 
 Terminates the current process.
 
@@ -186,6 +194,7 @@
 =cut
 
 sub terminate {
+   $current->{status} = [@_];
    $current->cancel;
    &schedule;
    die; # NORETURN
@@ -204,11 +213,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
 
@@ -225,7 +232,7 @@
 
 =item $process->ready
 
-Put the current process into the ready queue.
+Put the given process into the ready queue.
 
 =cut
 
@@ -241,12 +248,30 @@
    &schedule if $current == $_[0];
 }
 
+=item $process->join
+
+Wait until the coroutine terminates and return any values given to the
+C<terminate> function. 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
-lower priority processes. Priorities are smalled signed integer (currently
--4 .. +3), that you can refer to using PRIO_xxx constants (use the import
-tag :prio to get then):
+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
@@ -281,6 +306,19 @@
    $_[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
@@ -289,11 +327,13 @@
 
 =head1 BUGS/LIMITATIONS
 
- - 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 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