--- Coro/Coro.pm 2001/07/13 13:05:38 1.7 +++ Coro/Coro.pm 2001/08/11 00:37:31 1.29 @@ -1,134 +1,280 @@ =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 + } + + cede; =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. + +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; -BEGIN { - $VERSION = 0.03; +use Coro::State; + +use base Exporter; + +$VERSION = 0.45; + +@EXPORT = qw(async cede schedule terminate current); +@EXPORT_OK = qw($current); + +{ + my @async; + my $init; + + # 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; + unless ($init++) { + eval q{ + sub INIT { + &async(pop @async) while @async; + } + }; + } + } else { + push @attrs, $_; + } + } + return $old ? $old->($package, $ref, @attrs) : @attrs; + }; + } - require XSLoader; - XSLoader::load Coro, $VERSION; } -=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 call to this -coroutine will start execution at the given coderef. If, the subroutine -returns it will be executed again. +=item $current (or as function: 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; -Save the state of the current subroutine in C<$prev> and switch to the -coroutine saved in C<$next>. +sub current() { $current } -The "state" of a subroutine only ever includes scope, i.e. lexical -variables and the current execution state. It does not save/restore any -global variables such as C<$_> or C<$@> or any other special or non -special variables. So remember that every function call that might call -C (such as C) might clobber any global -and/or special variables. Yes, this is by design ;) You cna always create -your own process abstraction model that saves these variables. +=item $idle -The easiest way to do this is to create your own scheduling primitive like this: +The coroutine to switch to when no other coroutine is running. The default +implementation prints "FATAL: deadlock detected" and exits. - sub schedule { - local ($_, $@, ...); - $old->transfer($new); - } +=cut + +# should be done using priorities :( +our $idle = new Coro sub { + print STDERR "FATAL: deadlock detected\n"; + 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 ;) + +# 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 -# I call the _transfer function from a perl function -# because that way perl saves all important things on -# the stack. Actually, I'd do it from within XS, but -# I couldn't get it to work. -sub transfer { - _transfer($_[0], $_[1]); +sub async(&@) { + my $pid = new Coro @_; + $manager->ready; # this ensures that the stack is cloned from the manager + $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 cede + +"Cede" to other processes. This function puts the current process into the +ready queue and calls C, which has the effect of giving up the +current "timeslice" to other coroutines of the same or higher priority. + +=cut + +sub cede { + $current->ready; + &schedule; +} + +=item terminate + +Terminates the current process. + +Future versions of this function will allow result arguments. + +=cut + +sub terminate { + $current->cancel; + &schedule; + die; # NORETURN +} =back -=head1 BUGS +# 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]; +} + +=item $process->cancel + +Like C, but terminates the specified process instead. + +=cut + +sub cancel { + push @destroy, $_[0]; + $manager->ready; +} + +=back + +=cut + +1; + +=head1 BUGS/LIMITATIONS -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. + - 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). =head1 SEE ALSO -L, L. +L, L, L, L, +L, L, L, L, +L, L. =head1 AUTHOR