--- Coro/Coro.pm 2001/07/03 04:02:31 1.3 +++ Coro/Coro.pm 2001/07/17 02:21:56 1.14 @@ -1,125 +1,240 @@ =head1 NAME -Coro - create and manage coroutines +Coro - coroutine process abstraction =head1 SYNOPSIS use Coro; - $new = new Coro sub { - print "in coroutine, switching back\n"; - $Coro::main->resume; - print "in coroutine again, switching back\n"; - $Coro::main->resume; + async { + # some asynchronous thread of execution }; - print "in main, switching to coroutine\n"; - $new->resume; - print "back in main, switch to coroutine again\n"; - $new->resume; - print "back in main\n"; + # alternatively create an async process like this: + + 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 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.01; +use Coro::State; + +use base Exporter; + +$VERSION = 0.05; - require XSLoader; - XSLoader::load Coro, $VERSION; +@EXPORT = qw(async yield schedule terminate); +@EXPORT_OK = qw($current); + +{ + 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 $main This coroutine represents the main program. +=cut + +our $main = new Coro; + =item $current The current coroutine (the last coroutine switched to). The initial value is C<$main> (of course). =cut -$main = $current = _newprocess { - # never being called -}; +# maybe some other module used Coro::Specific before... +if ($current) { + $main->{specific} = $current->{specific}; +} -=item $error, $error_msg, $error_coro +our $current = $main; -This coroutine will be called on fatal errors. C<$error_msg> and -C<$error_coro> return the error message and the error-causing coroutine, -respectively. +=item $idle -=cut +The coroutine to switch to when no other coroutine is running. The default +implementation prints "FATAL: deadlock detected" and exits. -$error_msg = -$error_coro = undef; +=cut -$error = _newprocess { - print STDERR "FATAL: $error_msg\nprogram aborted\n"; - exit 250; +# should be done using priorities :( +our $idle = new Coro sub { + print STDERR "FATAL: deadlock detected\n"; + exit(51); }; -=item $coro = new $coderef [, @args] +# we really need priorities... +## my @ready; #d# +our @ready = (); # the ready queue. hehe, rather broken ;) + +# static methods. not really. -Create a new coroutine and return it. The first C call to this -coroutine will start execution at the given coderef. If it returns it -should return a coroutine to switch to. If, after returning, the coroutine -is Cd again it starts execution again at the givne coderef. +=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 new { - my $class = $_[0]; - my $proc = $_[1]; - bless _newprocess { - do { - eval { &$proc->resume }; - if ($@) { - ($error_msg, $error_coro) = ($@, $current); - $error->resume; - } - } while (); - }, $class; +sub async(&@) { + my $pid = new Coro @_; + $pid->ready; + $pid; } -=item $coro->resume +=item schedule -Resume execution at the given coroutine. +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 my $prev; -sub resume { - $prev = $current; $current = $_[0]; - _transfer($prev, $current); +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. + +=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, L. +L, L, L, L, +L, L, L. =head1 AUTHOR