--- Coro/Coro.pm	2001/07/19 02:45:09	1.17
+++ Coro/Coro.pm	2001/07/25 04:14:37	1.24
@@ -16,7 +16,7 @@
     # some more async code
  }
 
- yield;
+ cede;
 
 =head1 DESCRIPTION
 
@@ -25,6 +25,11 @@
 
 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;
@@ -33,14 +38,12 @@
 
 use base Exporter;
 
-$VERSION = 0.08;
+$VERSION = 0.12;
 
-@EXPORT = qw(async yield schedule terminate);
+@EXPORT = qw(async cede schedule terminate current);
 @EXPORT_OK = qw($current);
 
 {
-   use subs 'async';
-
    my @async;
 
    # this way of handling attributes simply is NOT scalable ;()
@@ -62,7 +65,7 @@
    }
 
    sub INIT {
-      async pop @async while @async;
+      &async(pop @async) while @async;
    }
 }
 
@@ -74,7 +77,7 @@
 
 our $main = new Coro;
 
-=item $current
+=item $current (or as function: current)
 
 The current coroutine (the last coroutine switched to). The initial value is C<$main> (of course).
 
@@ -87,6 +90,8 @@
 
 our $current = $main;
 
+sub current() { $current }
+
 =item $idle
 
 The coroutine to switch to when no other coroutine is running. The default
@@ -100,6 +105,16 @@
    exit(51);
 };
 
+# this coroutine is necessary because a coroutine
+# cannot destroy itself.
+my @destroy;
+my $manager = new Coro sub {
+   while() {
+      delete ((pop @destroy)->{_coro_state}) while @destroy;
+      &schedule;
+   }
+};
+
 # we really need priorities...
 my @ready; # the ready queue. hehe, rather broken ;)
 
@@ -129,6 +144,7 @@
 
 sub async(&@) {
    my $pid = new Coro @_;
+   $manager->ready; # this ensures that the stack is cloned from the manager
    $pid->ready;
    $pid;
 }
@@ -149,14 +165,15 @@
    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 {
+sub cede {
    $current->ready;
    &schedule;
 }
@@ -170,8 +187,10 @@
 =cut
 
 sub terminate {
-   $current->{_results} = [@_];
+   push @destroy, $current;
+   $manager->ready;
    &schedule;
+   # NORETURN
 }
 
 =back
@@ -234,7 +253,7 @@
    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::Satte does not yet allow this).
+   allow per-thread schedulers, but Coro::State does not yet allow this).
 
 =head1 SEE ALSO