--- Coro/Coro.pm	2001/07/10 21:19:47	1.6
+++ Coro/Coro.pm	2001/07/17 02:21:56	1.14
@@ -1,118 +1,240 @@
 =head1 NAME
 
-Coro - create and manage simple coroutines
+Coro - coroutine process abstraction
 
 =head1 SYNOPSIS
 
  use Coro;
 
- $new = new Coro sub {
-    print "in coroutine, switching back\n";
-    $new->transfer($main);
-    print "in coroutine again, switching back\n";
-    $new->transfer($main);
+ async {
+    # some asynchronous thread of execution
  };
 
- $main = new Coro;
+ # alternatively create an async process like this:
 
- print "in main, switching to coroutine\n";
- $main->transfer($new);
- print "back in main, switch to coroutine again\n";
- $main->transfer($new);
- print "back in main\n";
+ sub some_func : Coro {
+    # some more async code
+ }
+
+ yield;
 
 =head1 DESCRIPTION
 
-This module implements coroutines. Coroutines, similar to continuations,
-allow you to run more than one "thread of execution" in parallel. Unlike
-threads this, only voluntary switching is used so locking problems are
-greatly reduced.
-
-Although this is the "main" module of the Coro family it provides only
-low-level functionality. See L<Coro::Process> and related modules for a
-more useful process abstraction including scheduling.
+This module collection manages coroutines. Coroutines are similar to
+Threads but don't run in parallel.
 
-=over 4
+This module is still experimental, see the BUGS section below.
 
 =cut
 
 package Coro;
 
-BEGIN {
-   $VERSION = 0.03;
+use Coro::State;
+
+use base Exporter;
+
+$VERSION = 0.05;
+
+@EXPORT = qw(async yield schedule terminate);
+@EXPORT_OK = qw($current);
 
-   require XSLoader;
-   XSLoader::load Coro, $VERSION;
+{
+   use subs 'async';
+
+   my @async;
+
+   # this way of handling attributes simply is NOT scalable ;()
+   sub import {
+      Coro->export_to_level(1, @_);
+      my $old = *{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"}{CODE};
+      *{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"} = sub {
+         my ($package, $ref) = (shift, shift);
+         my @attrs;
+         for (@_) {
+            if ($_ eq "Coro") {
+               push @async, $ref;
+            } else {
+               push @attrs, @_;
+            }
+         }
+         return $old ? $old->($package, $name, @attrs) : @attrs;
+      };
+   }
+
+   sub INIT {
+      async pop @async while @async;
+   }
 }
 
-=item $coro = new [$coderef [, @args]]
+=item $main
+
+This coroutine represents the main program.
+
+=cut
+
+our $main = new Coro;
 
-Create a new coroutine and return it. The first C<transfer> call to this
-coroutine will start execution at the given coderef. If, the subroutine
-returns it will be executed again.
+=item $current
 
-If the coderef is omitted this function will create a new "empty"
-coroutine, i.e. a coroutine that cannot be transfered to but can be used
-to save the current coroutine in.
+The current coroutine (the last coroutine switched to). The initial value is C<$main> (of course).
 
 =cut
 
-sub new {
-   my $class = $_[0];
-   my $proc = $_[1] || sub { die "tried to transfer to an empty coroutine" };
-   bless _newprocess {
-      do {
-         eval { &$proc };
-         if ($@) {
-            $error_msg  = $@;
-            $error_coro = _newprocess { };
-            &transfer($error_coro, $error);
-         }
-      } while (1);
-   }, $class;
+# maybe some other module used Coro::Specific before...
+if ($current) {
+   $main->{specific} = $current->{specific};
 }
 
-=item $prev->transfer($next)
+our $current = $main;
+
+=item $idle
 
-Save the state of the current subroutine in $prev and switch to the
-coroutine saved in $next.
+The coroutine to switch to when no other coroutine is running. The default
+implementation prints "FATAL: deadlock detected" and exits.
 
 =cut
 
-# I call the _transfer function from a perl function
-# because that way perl saves all important things on
-# the stack.
-sub transfer {
-   _transfer($_[0], $_[1]);
+# should be done using priorities :(
+our $idle = new Coro sub {
+   print STDERR "FATAL: deadlock detected\n";
+   exit(51);
+};
+
+# we really need priorities...
+## my @ready; #d#
+our @ready = (); # the ready queue. hehe, rather broken ;)
+
+# static methods. not really.
+
+=head2 STATIC METHODS
+
+Static methods are actually functions that operate on the current process only.
+
+=over 4
+
+=item async { ... } [@args...]
+
+Create a new asynchronous process and return it's process object
+(usually unused). When the sub returns the new process is automatically
+terminated.
+
+   # 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 @_;
+   $pid->ready;
+   $pid;
 }
 
-=item $error, $error_msg, $error_coro
+=item schedule
 
-This coroutine will be called on fatal errors. C<$error_msg> and
-C<$error_coro> return the error message and the error-causing coroutine
-(NOT an object) respectively. This API might change.
+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.
 
 =cut
 
-$error_msg =
-$error_coro = undef;
+my $prev;
 
-$error = _newprocess {
-   print STDERR "FATAL: $error_msg\nprogram aborted\n";
-   exit 50;
-};
+sub schedule {
+   # should be done using priorities :(
+   ($prev, $current) = ($current, shift @ready || $idle);
+   Coro::State::transfer($prev, $current);
+}
 
-1;
+=item yield
+
+Yield to other processes. This function puts the current process into the
+ready queue and calls C<schedule>.
+
+=cut
+
+sub yield {
+   $current->ready;
+   &schedule;
+}
+
+=item terminate
+
+Terminates the current process.
+
+Future versions of this function will allow result arguments.
+
+=cut
+
+sub terminate {
+   $current->{_results} = [@_];
+   &schedule;
+}
 
 =back
 
+# dynamic methods
+
+=head2 PROCESS METHODS
+
+These are the methods you can call on process objects.
+
+=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
+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.
+
+=cut
+
+sub _newcoro {
+   terminate &{+shift};
+}
+
+sub new {
+   my $class = shift;
+   bless {
+      _coro_state => (new Coro::State $_[0] && \&_newcoro, @_),
+   }, $class;
+}
+
+=item $process->ready
+
+Put the current process into the ready queue.
+
+=cut
+
+sub ready {
+   push @ready, $_[0];
+}
+
+=back
+
+=cut
+
+1;
+
 =head1 BUGS
 
-This module has not yet been extensively tested.
+ - 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.
 
 =head1 SEE ALSO
 
-L<Coro::Process>, L<Coro::Signal>.
+L<Coro::Channel>, L<Coro::Cont>, L<Coro::Specific>, L<Coro::Semaphore>,
+L<Coro::Signal>, L<Coro::State>, L<Coro::Event>.
 
 =head1 AUTHOR