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 stacks (a few k) and optionally C stack. All this is very system-dependent. On my x86_64-pc-linux-gnu system this amounts to about 8k per (non-trivial) coroutine.

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 it will be executed again. If it throws an exception the program will terminate.

The initial save flags for a new state is SAVE_DEFAULT, which can be changed using the save method.

Calling exit in a coroutine will not work correctly, so do not do that.

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.

$old_save_flags = $state->save ([$new_save_flags])

It is possible to "localise" certain global variables for each state: for example, it would be awkward if @_ or $_ would suddenly change just because you temporarily switched to another coroutine, so Coro::State can save those variables in the state object on transfers.

The $new_save_flags value can be used to specify which variables (and other things) are to be saved (and later restored) on each transfer, by ORing the following constants together:

   Constant    Effect
   SAVE_DEFAV  save/restore @_
   SAVE_DEFSV  save/restore $_
   SAVE_ERRSV  save/restore $@
   SAVE_IRSSV  save/restore $/ (the Input Record Separator, slow)
   SAVE_DEFFH  save/restore default filehandle (select)
   SAVE_DEF    the default set of saves
   SAVE_ALL    everything that can be saved

These constants are not exported by default. If you don't need any extra additional variables saved, use 0 as the flags value.

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);
  }

$old_save_flags = $state->save_also ($new_save_flags)

Like save, but adds the given flags to the existing save flags, and still returns the old flag set.

$guard = $state->guarded_save ($new_save_flags)

Like save_also, but returns a guard that resets the save flags when destroyed.

This is useful when you need to save additional state in a lexically scoped block.

$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. As C level coroutines are curretly rarely being deallocated, a high number means that you used many C coroutines in the past.

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.

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/