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, continuations and more.

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

MEMORY CONSUMPTION

A newly created coroutine that has not been used only allocates a relatively small (a few hundred bytes) structure. Only on the first transfer will perl allocate stacks (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_64-pc-linux-gnu system this amounts to about 8k per (non-trivial) coroutine. You can view the actual memory consumption using Coro::Debug.

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.

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 in.

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 in each coroutine, and have defined initial values:

Variable   Initial Value
@_         whatever arguments were passed to the Coro
$_         undef
$@         undef
$/         "\n"
(select)   STDOUT

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 this:

sub schedule {
   local ($;, ...);
   $old->transfer ($new);
}

$state->has_stack

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

$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 stack).

$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. Do not use. Untested. Unused. Biohazard.

$state->trace ($flags)

Internal function to control tracing. I just mention this so you can stay 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).

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.

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.

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's that starts to use a stack after this call is guarenteed this minimum 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.

@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 loosened in the future).

SEE ALSO

Coro.

AUTHOR

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