--- Coro/Coro.pm 2001/07/22 03:24:10 1.21 +++ Coro/Coro.pm 2003/09/28 09:00:48 1.54 @@ -16,41 +16,39 @@ # some more async code } - yield; + cede; =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), 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. - -WARNING: When using this module, make sure that, at program end, no -coroutines are still running OR just call exit before falling off the -end. The reason for this is that some coroutine of yours might have called -into a C function, and falling off the end of main:: results in returning -to that C function instead if to the main C interpreter. ++ @_ + $_ + $@ + $^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; +no warnings qw(uninitialized); + use Coro::State; use base Exporter; -$VERSION = 0.10; +$VERSION = 0.7; -@EXPORT = qw(async yield schedule terminate current); -@EXPORT_OK = qw($current); +@EXPORT = qw(async cede schedule terminate current); +%EXPORT_TAGS = ( + prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], +); +@EXPORT_OK = @{$EXPORT_TAGS{prio}}; { my @async; + my $init; # this way of handling attributes simply is NOT scalable ;() sub import { @@ -62,6 +60,13 @@ for (@_) { if ($_ eq "Coro") { push @async, $ref; + unless ($init++) { + eval q{ + sub INIT { + &async(pop @async) while @async; + } + }; + } } else { push @attrs, $_; } @@ -70,11 +75,10 @@ }; } - sub INIT { - &async(pop @async) while @async; - } } +=over 4 + =item $main This coroutine represents the main program. @@ -111,11 +115,31 @@ exit(51); }; -# we really need priorities... -my @ready; # the ready queue. hehe, rather broken ;) +# this coroutine is necessary because a coroutine +# cannot destroy itself. +my @destroy; +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 + 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. @@ -140,6 +164,7 @@ sub async(&@) { my $pid = new Coro @_; + $manager->ready; # this ensures that the stack is cloned from the manager $pid->ready; $pid; } @@ -152,27 +177,15 @@ =cut -my $prev; - -sub schedule { - # should be done using priorities :( - ($prev, $current) = ($current, shift @ready || $idle); - 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. +"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 yield { - $current->ready; - &schedule; -} - -=item terminate +=item terminate [arg...] Terminates the current process. @@ -181,9 +194,10 @@ =cut sub terminate { - $current->{_results} = [@_]; - delete $current->{_coro_state}; + $current->{status} = [@_]; + $current->cancel; &schedule; + die; # NORETURN } =back @@ -199,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 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 @@ -220,12 +232,91 @@ =item $process->ready -Put the current process into the ready queue. +Put the given process into the ready queue. + +=cut + +=item $process->cancel + +Like C, but terminates the specified process instead. + +=cut + +sub cancel { + push @destroy, $_[0]; + $manager->ready; + &schedule if $current == $_[0]; +} + +=item $process->join + +Wait until the coroutine terminates and return any values given to the +C function. C 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 (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 + + # set priority to HIGH + current->prio(PRIO_HIGH); + +The idle coroutine ($Coro::idle) always has a lower priority than any +existing coroutine. + +Changing the priority of the current process will take effect immediately, +but changing the priority of processes in the ready queue (but not +running) will only take effect after the next schedule (of that +process). This is a bug that will be fixed in some future version. =cut -sub ready { - push @ready, $_[0]; +sub prio { + my $old = $_[0]{prio}; + $_[0]{prio} = $_[1] if @_ > 1; + $old; +} + +=item $newprio = $process->nice($change) + +Similar to C, but subtract the given value from the priority (i.e. +higher values mean lower priority, just as in unix). + +=cut + +sub nice { + $_[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 @@ -236,22 +327,19 @@ =head1 BUGS/LIMITATIONS - - 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). + - 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 L, L, L, L, -L, L, L. +L, L, L, L, +L, Handle>, L. =head1 AUTHOR