--- Coro/Coro.pm 2001/09/02 01:03:53 1.32 +++ Coro/Coro.pm 2003/11/30 22:49:25 1.57 @@ -21,9 +21,7 @@ =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 + C stack), that is, a coroutine has it's own @@ -34,11 +32,15 @@ package Coro; +BEGIN { eval { require warnings } && warnings->unimport ("uninitialized") } + use Coro::State; +use vars qw($idle $main $current); + use base Exporter; -$VERSION = 0.49; +$VERSION = "0.9"; @EXPORT = qw(async cede schedule terminate current); %EXPORT_TAGS = ( @@ -77,13 +79,15 @@ } +=over 4 + =item $main This coroutine represents the main program. =cut -our $main = new Coro; +$main = new Coro; =item $current (or as function: current) @@ -96,7 +100,7 @@ $main->{specific} = $current->{specific}; } -our $current = $main; +$current = $main; sub current() { $current } @@ -108,7 +112,7 @@ =cut # should be done using priorities :( -our $idle = new Coro sub { +$idle = new Coro sub { print STDERR "FATAL: deadlock detected\n"; exit(51); }; @@ -116,15 +120,28 @@ # 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; +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. @@ -142,9 +159,6 @@ 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(&@) { @@ -170,7 +184,7 @@ =cut -=item terminate +=item terminate [arg...] Terminates the current process. @@ -179,6 +193,7 @@ =cut sub terminate { + $current->{status} = [@_]; $current->cancel; &schedule; die; # NORETURN @@ -197,11 +212,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 @@ -218,7 +231,7 @@ =item $process->ready -Put the current process into the ready queue. +Put the given process into the ready queue. =cut @@ -231,14 +244,33 @@ 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 the priority of the process. Higher priority processes get run before -lower priority processes. Priorities are smalled signed integer (currently --4 .. +3), that you can refer to using PRIO_xxx constants (use the import -tag :prio to get then): +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 @@ -273,6 +305,19 @@ $_[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 =cut @@ -281,23 +326,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, L, L, +L, Handle>, L. =head1 AUTHOR