--- Coro/Coro.pm 2001/09/16 01:34:35 1.34 +++ Coro/Coro.pm 2006/11/25 01:14:11 1.86 @@ -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,17 +32,24 @@ package Coro; +use strict; +no warnings "uninitialized"; + use Coro::State; -use base Exporter; +use base qw(Coro::State Exporter); + +our $idle; # idle handler +our $main; # main coroutine +our $current; # current coroutine -$VERSION = 0.5; +our $VERSION = '2.5'; -@EXPORT = qw(async cede schedule terminate current); -%EXPORT_TAGS = ( +our @EXPORT = qw(async cede schedule terminate current); +our %EXPORT_TAGS = ( prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], ); -@EXPORT_OK = @{$EXPORT_TAGS{prio}}; +our @EXPORT_OK = @{$EXPORT_TAGS{prio}}; { my @async; @@ -52,7 +57,10 @@ # this way of handling attributes simply is NOT scalable ;() sub import { + no strict 'refs'; + Coro->export_to_level(1, @_); + my $old = *{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"}{CODE}; *{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"} = sub { my ($package, $ref) = (shift, shift); @@ -77,17 +85,24 @@ } +=over 4 + =item $main This coroutine represents the main program. =cut -our $main = new Coro; +$main = new Coro; =item $current (or as function: current) -The current coroutine (the last coroutine switched to). The initial value is C<$main> (of course). +The current coroutine (the last coroutine switched to). The initial value +is C<$main> (of course). + +This variable is B I. It is provided for performance +reasons. If performance is not essentiel you are encouraged to use the +C function instead. =cut @@ -96,35 +111,56 @@ $main->{specific} = $current->{specific}; } -our $current = $main; +$current = $main; sub current() { $current } =item $idle -The coroutine to switch to when no other coroutine is running. The default -implementation prints "FATAL: deadlock detected" and exits. +A callback that is called whenever the scheduler finds no ready coroutines +to run. The default implementation prints "FATAL: deadlock detected" and +exits. + +This hook is overwritten by modules such as C and +C to wait on an external event that hopefully wakes up some +coroutine. =cut -# should be done using priorities :( -our $idle = new Coro sub { +$idle = sub { print STDERR "FATAL: deadlock detected\n"; - exit(51); + 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; +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} || []}; + + # the next line destroys the coro state, but keeps the + # process itself intact (we basically make it a zombie + # process that always runs the manager thread, so it's possible + # to transfer() to this process). + $coro->_clone_state_from ($manager); + } &schedule; } }; # static methods. not really. +=back + =head2 STATIC METHODS Static methods are actually functions that operate on the current process only. @@ -137,21 +173,20 @@ (usually unused). When the sub returns the new process is automatically terminated. +When the coroutine dies, the program will exit, just as in the main +program. + # 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 @_; - $manager->ready; # this ensures that the stack is cloned from the manager $pid->ready; - $pid; + $pid } =item schedule @@ -170,18 +205,14 @@ =cut -=item terminate - -Terminates the current process. +=item terminate [arg...] -Future versions of this function will allow result arguments. +Terminates the current process with the given status values (see L). =cut sub terminate { - $current->cancel; - &schedule; - die; # NORETURN + $current->cancel (@_); } =back @@ -197,48 +228,70 @@ =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 -sub _newcoro { +sub _new_coro { + $current->_clear_idle_sp; # (re-)set the idle sp on the following cede + _set_cede_self; # ensures that cede cede's us first + cede; terminate &{+shift}; } sub new { my $class = shift; - bless { - _coro_state => (new Coro::State $_[0] && \&_newcoro, @_), - }, $class; + + $class->SUPER::new (\&_new_coro, @_) } =item $process->ready -Put the current process into the ready queue. +Put the given process into the ready queue. =cut -=item $process->cancel +=item $process->cancel (arg...) -Like C, but terminates the specified process instead. +Terminates the given process and makes it return the given arguments as +status (default: the empty list). =cut sub cancel { - push @destroy, $_[0]; + my $self = shift; + $self->{status} = [@_]; + push @destroy, $self; $manager->ready; + &schedule if $current == $self; +} + +=item $process->join + +Wait until the coroutine terminates and return any values given to the +C or C functions. 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) +=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 @@ -254,23 +307,22 @@ 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 prio { - my $old = $_[0]{prio}; - $_[0]{prio} = $_[1] if @_ > 1; - $old; -} - -=item $newprio = $process->nice($change) +=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). +=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 nice { - $_[0]{prio} -= $_[1]; +sub desc { + my $old = $_[0]{desc}; + $_[0]{desc} = $_[1] if @_ > 1; + $old; } =back @@ -281,22 +333,28 @@ =head1 BUGS/LIMITATIONS - - 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 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. +Support/Utility: L, L, L, L. + +Locking/IPC: L, L, L, L, L. + +Event/IO: L, L, L, L, L. + +Embedding: L =head1 AUTHOR - Marc Lehmann - http://www.goof.com/pcg/marc/ + Marc Lehmann + http://home.schmorp.de/ =cut