NAME

Coro::State - create and manage simple coroutines

SYNOPSIS

use Coro::State;

$new = new Coro::State sub {
   print "in coroutine (called with @_), switching back\n";
   $new->transfer ($main);
   print "in coroutine again, switching back\n";
   $new->transfer ($main);
}, 5;

$main = new Coro::State;

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";

DESCRIPTION

This module implements coroutines. Coroutines, similar to continuations, allow you to run more than one "thread of execution" in parallel. Unlike threads, there is no parallelism and only voluntary switching is used so locking problems are greatly reduced.

This can be used to implement non-local jumps, exception handling, (non-clonable) continuations and more.

This module provides only low-level functionality. See Coro and related modules for a higher level process abstraction including scheduling.

MODEL

Coro::State implements two different coroutine models: Perl and C. The C coroutines (called cctx's) are basically simplified perl interpreters running/interpreting the Perl coroutines. A single interpreter can run any number of Perl coroutines, so usually there are very few C coroutines.

When Perl code calls a C function (e.g. in an extension module) and that C function then calls back into Perl or does a coroutine switch the C coroutine can no longer execute other Perl coroutines, so it stays tied to the specific coroutine until it returns to the original Perl caller, after which it is again avaikable to run other Perl coroutines.

The main program always has its own "C coroutine" (which really is *the* Perl interpreter running the whole program), so there will always be at least one additional C coroutine. You can use the debugger (see Coro::Debug) to find out which coroutines are tied to their cctx and which aren't.

MEMORY CONSUMPTION

A newly created coroutine that has not been used only allocates a relatively small (a hundred bytes) structure. Only on the first transfer will perl allocate stacks (a few kb, 64 bit architetcures use twice as much, i.e. a few kb :) and optionally a C stack/coroutine (cctx) for coroutines that recurse through C functions. All this is very system-dependent. On my x86-pc-linux-gnu system this amounts to about 2k per (non-trivial but simple) coroutine.

You can view the actual memory consumption using Coro::Debug. Keep in mind that a for loop or other block constructs can easily consume 100-200 bytes per nesting level.

GLOBAL VARIABLES

$Coro::State::DIEHOOK

This works similarly to $SIG{__DIE__} and is used as the default die hook for newly created coroutines. This is useful if you want some generic logging function that works for all coroutines that don't set their own hook.

When Coro::State is first loaded it will install these handlers for the main program, too, unless they have been overwritten already.

The default handlers provided will behave like the built-in ones (as if they weren't there).

Note 1: You must store a valid code reference in these variables, undef will not do.

Note 2: The value of this variable will be shared among all coroutines, so changing its value will change it in all coroutines that don't have their own die handler.

$Coro::State::WARNHOOK

Similar to above die hook, but augments $SIG{__WARN__}.

FUNCTIONS

$coro = new Coro::State [$coderef[, @args...]]

Create a new coroutine and return it. The first transfer call to this coroutine will start execution at the given coderef.

If the subroutine returns the program will be terminated as if execution of the main program ended.

If it throws an exception the program will terminate unless the exception is caught, exactly like in the main program.

Calling exit in a coroutine does the same as calling it in the main program.

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 state in (note that this is dangerous, as no reference is taken to ensure that the "current coroutine state" survives, the caller is responsible to ensure that the cloned state does not go away).

The returned object is an empty hash which can be used for any purpose whatsoever, for example when subclassing Coro::State.

Certain variables are "localised" to each coroutine, that is, certain "global" variables are actually per coroutine. Not everything that would sensibly be localised currently is, and not everything that is localised makes sense for every application, and the future might bring changes.

The following global variables can have different values per coroutine, and have the stated initial values:

Variable       Initial Value
@_             whatever arguments were passed to the Coro
$_             undef
$@             undef
$/             "\n"
$SIG{__DIE__}  aliased to $Coro::State::DIEHOOK(*)
$SIG{__WARN__} aliased to $Coro::State::WARNHOOK(*)
(default fh)   *STDOUT
$1, $2...      all regex results are initially undefined

(*) reading the value from %SIG is not supported, but local'ising is.

If you feel that something important is missing then tell me. Also remember that every function call that might call transfer (such as Coro::Channel::put) might clobber any global and/or special variables. Yes, this is by design ;) You can always create your own process abstraction model that saves these variables.

The easiest way to do this is to create your own scheduling primitive like in the code below, and use it in your coroutines:

sub my_cede {
   local ($;, ...);
   Coro::cede;
}

$state->throw ([$scalar])

See Coro->throw.

$state->call ($coderef)

Try to call the given $coderef in the context of the given state. This works even when the state is currently within an XS function, and can be very dangerous. You can use it to acquire stack traces etc. (see the Coro::Debug module for more details). The coderef MUST NOT EVER transfer to another state.

$state->eval ($string)

Like call, but eval's the string. Dangerous.

$state->swap_defsv

$state->swap_defav

Swap the current $_ (swap_defsv) or @_ (swap_defav) with the equivalent in the saved state of $state. This can be used to give the coroutine a defined content for @_ and $_ before transfer'ing to it.

$state->trace ($flags)

Internal function to control tracing. I just mention this so you can stay away from abusing it.

$prev->transfer ($next)

Save the state of the current subroutine in $prev and switch to the coroutine saved in $next.

The "state" of a subroutine includes the scope, i.e. lexical variables and the current execution state (subroutine, stack).

$bytes = $state->rss

Returns the memory allocated by the coroutine (which includes static structures, various perl stacks but NOT local variables, arguments or any C context data). This is a rough indication of how much memory it might use.

$state->has_cctx

Returns whether the state currently uses a cctx/C context. An active state always has a cctx, as well as the main program. Other states only use a cctxts when needed.

Coro::State::force_cctx

Forces the allocation of a C context for the currently running coroutine (if not already done). Apart from benchmarking there is little point in doing so, however.

$ncctx = Coro::State::cctx_count

Returns the number of C-level coroutines allocated. If this number is very high (more than a dozen) it might help to identify points of C-level recursion in your code and moving this into a separate coroutine.

$nidle = Coro::State::cctx_idle

Returns the number of allocated but idle (free for reuse) C level coroutines. Currently, Coro will limit the number of idle/unused cctxs to 8.

$old = Coro::State::cctx_stacksize [$new_stacksize]

Returns the current C stack size and optionally sets the new minimum stack size to $new_stacksize longs. Existing stacks will not be changed, but Coro will try to replace smaller stacks as soon as possible. Any Coro::State that starts to use a stack after this call is guaranteed this minimum stack size.

Please note that Coroutines will only need to use a C-level stack if the interpreter recurses or calls a function in a module that calls back into the interpreter, so use of this feature is usually never needed.

$old = Coro::State::cctx_max_idle [$new_count]

Coro caches C contexts that are not in use currently, as creating them from scratch has some overhead.

This function returns the current maximum number of idle C contexts and optionally sets the new amount. The count must be at least 1, with the default being 4.

@states = Coro::State::list

Returns a list of all states currently allocated.

BUGS

This module is not thread-safe. You must only ever use this module from the same thread (this requirement might be removed in the future).

SEE ALSO

Coro.

AUTHOR

Marc Lehmann <schmorp@schmorp.de>
http://home.schmorp.de/