Coro/Coro/State.pm

=head1 NAME

Coro::State - first class continuations

=head1 SYNOPSIS

 use Coro::State;

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

 $main = new Coro::State;

 print "in main, switching to coro\n";
 $main->transfer ($new);
 print "back in main, switch to coro again\n";
 $main->transfer ($new);
 print "back in main\n";

=head1 DESCRIPTION

This module implements coro. Coros, similar to threads and continuations,
allow you to run more than one "thread of execution" in parallel. Unlike
so-called "kernel" threads, there is no parallelism and only voluntary
switching is used so locking problems are greatly reduced. The latter is
called "cooperative" threading as opposed to "preemptive" threading.

This can be used to implement non-local jumps, exception handling,
continuation objects and more.

This module provides only low-level functionality. See L<Coro> and related
modules for a higher level threads abstraction including a scheduler.

=head2 MODEL

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

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

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

=head2 MEMORY CONSUMPTION

A newly created Coro::State that has not been used only allocates a
relatively small (a hundred bytes) structure. Only on the first
C<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/thread
(cctx) for threads 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) Coro::State.

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.

=cut

package Coro::State;

use common::sense;

use Carp;

our $DIEHOOK;
our $WARNHOOK;

BEGIN {
   $DIEHOOK  = sub { };
   $WARNHOOK = sub { warn $_[0] };
}

sub diehook  { &$DIEHOOK  }
sub warnhook { &$WARNHOOK }

use XSLoader;

BEGIN {
   our $VERSION = 5.37;

   # must be done here because the xs part expects it to exist
   # it might exist already because Coro::Specific created it.
   $Coro::current ||= { };

   {
      # save/restore the handlers before/after overwriting %SIG magic
      local $SIG{__DIE__};
      local $SIG{__WARN__};

      XSLoader::load __PACKAGE__, $VERSION;
   }

   # need to do it after overwriting the %SIG magic
   $SIG{__DIE__}  ||= \&diehook;
   $SIG{__WARN__} ||= \&warnhook;
}

use Exporter;
use base Exporter::;

=head2 GLOBAL VARIABLES

=over 4

=item $Coro::State::DIEHOOK

This works similarly to C<$SIG{__DIE__}> and is used as the default die
hook for newly created Coro::States. This is useful if you want some generic
logging function that works for all threads 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).

If you don't want to exit your program on uncaught exceptions, you must
not return from your die hook - call C<Coro::terminate> instead.

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

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

=item $Coro::State::WARNHOOK

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

=back

=head2 FUNCTIONS

=over 4

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

Create a new Coro::State thread object and return it. The first
C<transfer> call to this thread will start execution at the given
coderef, with the given arguments.

Note that the arguments will not be copied. Instead, as with normal
function calls, the thread receives passed arguments by reference, so
make sure you don't change them in unexpected ways.

Returning from such a thread is I<NOT> supported. Neither is calling
C<exit> or throwing an uncaught exception. The following paragraphs
describe what happens in current versions of Coro.

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 C<exit> in a thread does the same as calling it in the main
program, but due to libc bugs on many BSDs, this doesn't work reliable
everywhere.

If the coderef is omitted this function will create a new "empty"
thread, i.e. a thread that cannot be transfered to but can be used
to save the current thread state in (note that this is dangerous, as no
reference is taken to ensure that the "current thread 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 thread, that is, certain
"global" variables are actually per thread. 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 thread,
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
   $^H, %^H       zero/empty.
   $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 C<transfer> (such
as C<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 threads:

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

Another way is to use dynamic winders, see C<Coro::on_enter> and
C<Coro::on_leave> for this.

Yet another way that works onyl for variables is C<< ->swap_sv >>.

=item $prev->transfer ($next)

Save the state of the current subroutine in C<$prev> and switch to the
thread saved in C<$next>.

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

=item $state->is_new

Returns true iff this Coro::State object is "new", i.e. has never been run
yet. Those states basically consist of only the code reference to call and
the arguments, but consumes very little other resources. New states will
automatically get assigned a perl interpreter when they are transfered to.

=item $state->is_destroyed

Returns true iff the Coro::State object has been destroyed (by
C<cancel>), i.e. it's resources freed because they were C<cancel>'d (or
C<terminate>'d).

=item $state->cancel

Forcefully destructs the given Coro::State. While you can keep the
reference, and some memory is still allocated, the Coro::State object is
effecticely dead, destructors have been freed, it cannot be transfered to
anymore.

=item $state->throw ([$scalar])

See L<< Coro->throw >>.

=item $state->call ($coderef)

Try to call the given C<$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.

=item $state->eval ($string)

Like C<call>, but eval's the string. Dangerous.

=item $state->swap_defsv

=item $state->swap_defav

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

=item $state->swap_sv (\$sv, \$swap_sv)

This (very advanced) function can be used to make I<any> variable local to
a thread.

It works by swapping the contents of C<$sv> and C<$swap_sv> each time the
thread is entered and left again, i.e. it is similar to:

   $tmp = $sv; $sv = $swap_sv; $swap_sv = $tmp;

Except that it doesn't make an copies and works on hashes and even more
exotic values (code references!).

Needless to say, this function can be very very dangerous: you can easily
swap a hash with a reference (i.e. C<%hash> I<becomes> a reference), and perl
will not like this at all.

It will also swap "magicalness" - so when swapping a builtin perl variable
(such as C<$.>), it will lose it's magicalness, which, again, perl will
not like, so don't do it.

Lastly, the C<$swap_sv> itself will be used, not a copy, so make sure you
give each thread it's own C<$swap_sv> instance.

It is, however, quite safe to swap some normal variable with
another. For example, L<PApp::SQL> stores the default database handle in
C<$PApp::SQL::DBH>. To make this a per-thread variable, use this:

   my $private_dbh = ...;
   $coro->swap_sv (\$PApp::SQL::DBH, \$private_dbh);

This results in C<$PApp::SQL::DBH> having the value of C<$private_dbh>
while it executes, and whatever other value it had when it doesn't
execute.

You can also swap hashes and other values:

   my %private_hash;
   $coro->swap_sv (\%some_hash, \%private_hash);

=item $state->trace ($flags)

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

=item $bytes = $state->rss

Returns the memory allocated by the coro (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.

=item $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.

=item Coro::State::force_cctx

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

=item $ncctx = Coro::State::cctx_count

Returns the number of C-level thread contexts allocated. If this number is
very high (more than a dozen) it might be beneficial to identify points of
C-level recursion (perl calls C/XS, which calls perl again which switches
coros - this forces an allocation of a C-level thread context) in your
code and moving this into a separate coro.

=item $nidle = Coro::State::cctx_idle

Returns the number of allocated but idle (currently unused and free for
reuse) C level thread contexts.

=item $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 C<1>, with the
default being C<4>.

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

Returns the current C stack size and optionally sets the new I<minimum>
stack size to C<$new_stacksize> I<long>s. 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 coros 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.

=item @states = Coro::State::list

Returns a list of all states currently allocated.

=item $was_enabled = Coro::State::enable_times [$enable]

Enables/disables/queries the current state of per-thread real and
cpu-time gathering.

When enabled, the real time and the cpu time (user + system time)
spent in each thread is accumulated. If disabled, then the accumulated
times will stay as they are (they start at 0).

Currently, cpu time is only measured on GNU/Linux systems, all other
systems only gather real time.

Enabling time profiling slows down thread switching by a factor of 2 to
10, depending on platform on hardware.

The times will be displayed when running C<Coro::Debug::command "ps">, and
cna be queried by calling C<< $state->times >>.

=item ($real, $cpu) = $state->times

Returns the real time and cpu times spent in the given C<$state>. See
C<Coro::State::enable_times> for more info.

=item $clone = $state->clone

This exciting method takes a Coro::State object and clones it, i.e., it
creates a copy. This makes it possible to restore a state more than once,
and even return to states that have returned or have been terminated.

Since its only known purpose is for intellectual self-gratification, and
because it is a difficult piece of code, it is not enabled by default, and
not supported.

Here are a few little-known facts: First, coros *are* full/true/real
continuations. Secondly Coro::State objects (without clone) *are* first
class continuations. Thirdly, nobody has ever found a use for the full
power of call/cc that isn't better (faster, easier, more efficiently)
implemented differently, and nobody has yet found a useful control
construct that can't be implemented without it already, just much faster
and with fewer resources. And lastly, Scheme's call/cc doesn't support
using call/cc to implement threads.

Among the games you can play with this is implementing a scheme-like
call-with-current-continuation, as the following code does (well, with
small differences).

   # perl disassociates from local lexicals on frame exit,
   # so use a global variable for return values.
   my @ret;

   sub callcc($@) {
      my ($func, @arg) = @_;

      my $continuation = new Coro::State;
      $continuation->transfer (new Coro::State sub {
         my $escape = sub {
            @ret = @_;
            Coro::State->new->transfer ($continuation->clone);
         };
         $escape->($func->($escape, @arg));
      });

      my @ret_ = @ret; @ret = ();
      wantarray ? @ret_ : pop @ret_
   }

Which could be used to implement a loop like this:

   async {
      my $n; 
      my $l = callcc sub { $_[0] };
     
      $n++; 
      print "iteration $n\n";

      $l->($l) unless $n == 10;
   };  

If you find this confusing, then you already understand the coolness of
call/cc: It can turn anything into spaghetti code real fast.

Besides, call/cc is much less useful in a Perl-like dynamic language (with
references, and its scoping rules) then in, say, scheme.

Now, the known limitations of C<clone>:

It probably only works on perl 5.10; it cannot clone a coro inside
the substition operator (but windows perl can't fork from there either)
and some other contexts, and C<abort ()> is the preferred mechanism to
signal errors. It cannot clone a state that has a c context attached
(implementing clone on the C level is too hard for me to even try),
which rules out calling call/cc from the main coro. It cannot
clone a context that hasn't even been started yet. It doesn't work with
C<-DDEBUGGING> (but what does). It probably also leaks, and sometimes
triggers a few assertions inside Coro. Most of these limitations *are*
fixable with some effort, but that's pointless just to make a point that
it could be done.

The current implementation could without doubt be optimised to be a
constant-time operation by doing lazy stack copying, if somebody were
insane enough to invest the time.

=cut

# used by Coro::Debug only atm.
sub debug_desc {
   $_[0]{desc}
}

# for very deep reasons, we must initialise $Coro::main here.

{
   package Coro;

   our $main;    # main coro
   our $current; # current coro

   $main = Coro::new Coro::;

   $main->{desc} = "[main::]";

   # maybe some other module used Coro::Specific before...
   $main->{_specific} = $current->{_specific}
      if $current;

   _set_current $main;
}

# we also make sure we have Coro::AnyEvent when AnyEvent is used,
# without loading or initialising AnyEvent
if (defined $AnyEvent::MODEL) {
   require Coro::AnyEvent;
} else {
   push @AnyEvent::post_detect, sub { require Coro::AnyEvent };
}

1;

=back

=head1 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).

=head1 SEE ALSO

L<Coro>.

=head1 AUTHOR

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

=cut

Revision:	1.163
Committed:	Sat Feb 19 06:51:23 2011 UTC (13 years, 3 months ago) by root
Branch:	MAIN
CVS Tags:	rel-5_37
Changes since 1.162:	+1 -3 lines
Log Message:	5.37
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3	root	1.132	Coro::State - first class continuations
4	root	1.1
5			=head1 SYNOPSIS
6
7			use Coro::State;
8
9			$new = new Coro::State sub {
10	root	1.140	print "in coro (called with @_), switching back\n";
11	root	1.43	$new->transfer ($main);
12	root	1.140	print "in coro again, switching back\n";
13	root	1.43	$new->transfer ($main);
14	root	1.3	}, 5;
15	root	1.1
16			$main = new Coro::State;
17
18	root	1.140	print "in main, switching to coro\n";
19	root	1.43	$main->transfer ($new);
20	root	1.140	print "back in main, switch to coro again\n";
21	root	1.43	$main->transfer ($new);
22	root	1.1	print "back in main\n";
23
24			=head1 DESCRIPTION
25
26	root	1.140	This module implements coro. Coros, similar to threads and continuations,
27	root	1.1	allow you to run more than one "thread of execution" in parallel. Unlike
28	root	1.140	so-called "kernel" threads, there is no parallelism and only voluntary
29			switching is used so locking problems are greatly reduced. The latter is
30			called "cooperative" threading as opposed to "preemptive" threading.
31	root	1.42
32			This can be used to implement non-local jumps, exception handling,
33	root	1.140	continuation objects and more.
34	root	1.1
35			This module provides only low-level functionality. See L<Coro> and related
36	root	1.140	modules for a higher level threads abstraction including a scheduler.
37	root	1.1
38	root	1.86	=head2 MODEL
39
40	root	1.140	Coro::State implements two different thread models: Perl and C. The C
41			threads (called cctx's) are basically simplified perl interpreters
42			running/interpreting the Perl threads. A single interpreter can run any
43			number of Perl threads, so usually there are very few C threads.
44
45			When Perl code calls a C function (e.g. in an extension module) and that C
46			function then calls back into Perl or transfers control to another thread,
47			the C thread can no longer execute other Perl threads, so it stays tied to
48			the specific thread until it returns to the original Perl caller, after
49			which it is again available to run other Perl threads.
50	root	1.86
51	root	1.140	The main program always has its own "C thread" (which really is
52	root	1.86	the Perl interpreter running the whole program), so there will always
53	root	1.140	be at least one additional C thread. You can use the debugger (see
54			L<Coro::Debug>) to find out which threads are tied to their cctx and
55	root	1.86	which aren't.
56
57	root	1.9	=head2 MEMORY CONSUMPTION
58
59	root	1.140	A newly created Coro::State that has not been used only allocates a
60	root	1.84	relatively small (a hundred bytes) structure. Only on the first
61	root	1.94	C<transfer> will perl allocate stacks (a few kb, 64 bit architetcures
62	root	1.140	use twice as much, i.e. a few kb :) and optionally a C stack/thread
63			(cctx) for threads that recurse through C functions. All this is very
64	root	1.94	system-dependent. On my x86-pc-linux-gnu system this amounts to about 2k
65	root	1.140	per (non-trivial but simple) Coro::State.
66	root	1.94
67			You can view the actual memory consumption using Coro::Debug. Keep in mind
68			that a for loop or other block constructs can easily consume 100-200 bytes
69			per nesting level.
70	root	1.1
71			=cut
72
73			package Coro::State;
74
75	root	1.153	use common::sense;
76	root	1.47
77	root	1.84	use Carp;
78	root	1.87
79			our $DIEHOOK;
80			our $WARNHOOK;
81
82			BEGIN {
83			$DIEHOOK = sub { };
84			$WARNHOOK = sub { warn $_[0] };
85			}
86
87			sub diehook { &$DIEHOOK }
88			sub warnhook { &$WARNHOOK }
89	root	1.84
90	root	1.47	use XSLoader;
91	root	1.18
92	root	1.1	BEGIN {
93	root	1.163	our $VERSION = 5.37;
94	root	1.1
95	root	1.67	# must be done here because the xs part expects it to exist
96			# it might exist already because Coro::Specific created it.
97			$Coro::current \|\|= { };
98
99	root	1.101	{
100			# save/restore the handlers before/after overwriting %SIG magic
101			local $SIG{__DIE__};
102			local $SIG{__WARN__};
103
104			XSLoader::load __PACKAGE__, $VERSION;
105			}
106
107			# need to do it after overwriting the %SIG magic
108			$SIG{__DIE__} \|\|= \&diehook;
109			$SIG{__WARN__} \|\|= \&warnhook;
110	root	1.1	}
111
112	root	1.51	use Exporter;
113	root	1.47	use base Exporter::;
114	root	1.5
115	root	1.84	=head2 GLOBAL VARIABLES
116
117			=over 4
118
119			=item $Coro::State::DIEHOOK
120
121			This works similarly to C<$SIG{__DIE__}> and is used as the default die
122	root	1.140	hook for newly created Coro::States. This is useful if you want some generic
123			logging function that works for all threads that don't set their own
124	root	1.84	hook.
125
126			When Coro::State is first loaded it will install these handlers for the
127	root	1.101	main program, too, unless they have been overwritten already.
128	root	1.84
129	root	1.100	The default handlers provided will behave like the built-in ones (as if
130	root	1.84	they weren't there).
131
132	root	1.150	If you don't want to exit your program on uncaught exceptions, you must
133			not return from your die hook - call C<Coro::terminate> instead.
134	root	1.125
135	root	1.94	Note 1: You I<must> store a valid code reference in these variables,
136			C<undef> will I<not> do.
137	root	1.84
138	root	1.140	Note 2: The value of this variable will be shared among all threads, so
139			changing its value will change it in all threads that don't have their
140	root	1.100	own die handler.
141	root	1.84
142			=item $Coro::State::WARNHOOK
143
144			Similar to above die hook, but augments C<$SIG{__WARN__}>.
145
146			=back
147
148			=head2 FUNCTIONS
149
150			=over 4
151
152	root	1.65	=item $coro = new Coro::State [$coderef[, @args...]]
153	root	1.1
154	root	1.140	Create a new Coro::State thread object and return it. The first
155			C<transfer> call to this thread will start execution at the given
156			coderef, with the given arguments.
157	root	1.125
158			Note that the arguments will not be copied. Instead, as with normal
159	root	1.140	function calls, the thread receives passed arguments by reference, so
160	root	1.125	make sure you don't change them in unexpected ways.
161
162	root	1.140	Returning from such a thread is I<NOT> supported. Neither is calling
163	root	1.125	C<exit> or throwing an uncaught exception. The following paragraphs
164			describe what happens in current versions of Coro.
165	root	1.94
166			If the subroutine returns the program will be terminated as if execution
167			of the main program ended.
168
169			If it throws an exception the program will terminate unless the exception
170			is caught, exactly like in the main program.
171	root	1.74
172	root	1.140	Calling C<exit> in a thread does the same as calling it in the main
173	root	1.133	program, but due to libc bugs on many BSDs, this doesn't work reliable
174			everywhere.
175	root	1.1
176			If the coderef is omitted this function will create a new "empty"
177	root	1.140	thread, i.e. a thread that cannot be transfered to but can be used
178			to save the current thread state in (note that this is dangerous, as no
179			reference is taken to ensure that the "current thread state" survives,
180	root	1.104	the caller is responsible to ensure that the cloned state does not go
181			away).
182	root	1.1
183	root	1.55	The returned object is an empty hash which can be used for any purpose
184			whatsoever, for example when subclassing Coro::State.
185
186	root	1.140	Certain variables are "localised" to each thread, that is, certain
187			"global" variables are actually per thread. Not everything that would
188	root	1.79	sensibly be localised currently is, and not everything that is localised
189			makes sense for every application, and the future might bring changes.
190	root	1.1
191	root	1.140	The following global variables can have different values per thread,
192	root	1.84	and have the stated initial values:
193	root	1.5
194	root	1.83	Variable Initial Value
195			@_ whatever arguments were passed to the Coro
196			$_ undef
197			$@ undef
198			$/ "\n"
199	root	1.88	$SIG{__DIE__} aliased to $Coro::State::DIEHOOK(*)
200			$SIG{__WARN__} aliased to $Coro::State::WARNHOOK(*)
201	root	1.83	(default fh) *STDOUT
202	root	1.133	$^H, %^H zero/empty.
203	root	1.84	$1, $2... all regex results are initially undefined
204	root	1.2
205	root	1.88	(*) reading the value from %SIG is not supported, but local'ising is.
206
207	root	1.70	If you feel that something important is missing then tell me. Also
208	root	1.2	remember that every function call that might call C<transfer> (such
209			as C<Coro::Channel::put>) might clobber any global and/or special
210			variables. Yes, this is by design ;) You can always create your own
211			process abstraction model that saves these variables.
212	root	1.1
213	root	1.9	The easiest way to do this is to create your own scheduling primitive like
214	root	1.140	in the code below, and use it in your threads:
215	root	1.1
216	root	1.84	sub my_cede {
217	root	1.80	local ($;, ...);
218	root	1.84	Coro::cede;
219	root	1.1	}
220
221	root	1.140	Another way is to use dynamic winders, see C<Coro::on_enter> and
222			C<Coro::on_leave> for this.
223
224	root	1.160	Yet another way that works onyl for variables is C<< ->swap_sv >>.
225
226	root	1.140	=item $prev->transfer ($next)
227
228			Save the state of the current subroutine in C<$prev> and switch to the
229			thread saved in C<$next>.
230
231			The "state" of a subroutine includes the scope, i.e. lexical variables and
232			the current execution state (subroutine, stack).
233
234			=item $state->is_new
235
236			Returns true iff this Coro::State object is "new", i.e. has never been run
237			yet. Those states basically consist of only the code reference to call and
238			the arguments, but consumes very little other resources. New states will
239			automatically get assigned a perl interpreter when they are transfered to.
240
241			=item $state->is_destroyed
242
243			Returns true iff the Coro::State object has been destroyed (by
244			C<cancel>), i.e. it's resources freed because they were C<cancel>'d (or
245			C<terminate>'d).
246
247			=item $state->cancel
248
249			Forcefully destructs the given Coro::State. While you can keep the
250			reference, and some memory is still allocated, the Coro::State object is
251			effecticely dead, destructors have been freed, it cannot be transfered to
252			anymore.
253	root	1.79
254	root	1.119	=item $state->throw ([$scalar])
255
256			See L<< Coro->throw >>.
257
258	root	1.76	=item $state->call ($coderef)
259
260	root	1.94	Try to call the given C<$coderef> in the context of the given state. This
261	root	1.76	works even when the state is currently within an XS function, and can
262			be very dangerous. You can use it to acquire stack traces etc. (see the
263			Coro::Debug module for more details). The coderef MUST NOT EVER transfer
264			to another state.
265
266			=item $state->eval ($string)
267
268	root	1.94	Like C<call>, but eval's the string. Dangerous.
269	root	1.76
270	root	1.90	=item $state->swap_defsv
271
272			=item $state->swap_defav
273
274			Swap the current C<$_> (swap_defsv) or C<@_> (swap_defav) with the
275			equivalent in the saved state of C<$state>. This can be used to give the
276	root	1.140	coro a defined content for C<@_> and C<$_> before transfer'ing to it.
277	root	1.90
278	root	1.154	=item $state->swap_sv (\$sv, \$swap_sv)
279
280			This (very advanced) function can be used to make I<any> variable local to
281			a thread.
282
283			It works by swapping the contents of C<$sv> and C<$swap_sv> each time the
284	root	1.160	thread is entered and left again, i.e. it is similar to:
285	root	1.154
286			$tmp = $sv; $sv = $swap_sv; $swap_sv = $tmp;
287
288			Except that it doesn't make an copies and works on hashes and even more
289			exotic values (code references!).
290
291			Needless to say, this function can be very very dangerous: you can easily
292			swap a hash with a reference (i.e. C<%hash> I<becomes> a reference), and perl
293			will not like this at all.
294
295			It will also swap "magicalness" - so when swapping a builtin perl variable
296			(such as C<$.>), it will lose it's magicalness, which, again, perl will
297			not like, so don't do it.
298
299			Lastly, the C<$swap_sv> itself will be used, not a copy, so make sure you
300			give each thread it's own C<$swap_sv> instance.
301
302			It is, however, quite safe to swap some normal variable with
303			another. For example, L<PApp::SQL> stores the default database handle in
304			C<$PApp::SQL::DBH>. To make this a per-thread variable, use this:
305
306			my $private_dbh = ...;
307			$coro->swap_sv (\$PApp::SQL::DBH, \$private_dbh);
308
309			This results in C<$PApp::SQL::DBH> having the value of C<$private_dbh>
310			while it executes, and whatever other value it had when it doesn't
311			execute.
312
313			You can also swap hashes and other values:
314
315			my %private_hash;
316			$coro->swap_sv (\%some_hash, \%private_hash);
317
318	root	1.77	=item $state->trace ($flags)
319
320			Internal function to control tracing. I just mention this so you can stay
321	root	1.90	away from abusing it.
322	root	1.77
323	root	1.117	=item $bytes = $state->rss
324
325	root	1.140	Returns the memory allocated by the coro (which includes static
326	root	1.117	structures, various perl stacks but NOT local variables, arguments or any
327			C context data). This is a rough indication of how much memory it might
328			use.
329
330	root	1.94	=item $state->has_cctx
331
332	root	1.117	Returns whether the state currently uses a cctx/C context. An active
333	root	1.94	state always has a cctx, as well as the main program. Other states only
334			use a cctxts when needed.
335
336	root	1.117	=item Coro::State::force_cctx
337	root	1.94
338	root	1.140	Forces the allocation of a C context for the currently running coro
339	root	1.117	(if not already done). Apart from benchmarking there is little point
340			in doing so, however.
341	root	1.94
342	root	1.117	=item $ncctx = Coro::State::cctx_count
343	root	1.64
344	root	1.161	Returns the number of C-level thread contexts allocated. If this number is
345			very high (more than a dozen) it might be beneficial to identify points of
346			C-level recursion (perl calls C/XS, which calls perl again which switches
347			coros - this forces an allocation of a C-level thread context) in your
348			code and moving this into a separate coro.
349	root	1.64
350	root	1.117	=item $nidle = Coro::State::cctx_idle
351	root	1.64
352	root	1.161	Returns the number of allocated but idle (currently unused and free for
353			reuse) C level thread contexts.
354
355			=item $old = Coro::State::cctx_max_idle [$new_count]
356
357			Coro caches C contexts that are not in use currently, as creating them
358			from scratch has some overhead.
359
360			This function returns the current maximum number of idle C contexts and
361			optionally sets the new amount. The count must be at least C<1>, with the
362			default being C<4>.
363	root	1.64
364	root	1.117	=item $old = Coro::State::cctx_stacksize [$new_stacksize]
365	root	1.72
366			Returns the current C stack size and optionally sets the new I<minimum>
367			stack size to C<$new_stacksize> I<long>s. Existing stacks will not
368			be changed, but Coro will try to replace smaller stacks as soon as
369	root	1.91	possible. Any Coro::State that starts to use a stack after this call is
370	root	1.94	guaranteed this minimum stack size.
371
372	root	1.140	Please note that coros will only need to use a C-level stack if the
373	root	1.94	interpreter recurses or calls a function in a module that calls back into
374			the interpreter, so use of this feature is usually never needed.
375	root	1.72
376	root	1.76	=item @states = Coro::State::list
377
378			Returns a list of all states currently allocated.
379
380	root	1.144	=item $was_enabled = Coro::State::enable_times [$enable]
381
382			Enables/disables/queries the current state of per-thread real and
383			cpu-time gathering.
384
385			When enabled, the real time and the cpu time (user + system time)
386			spent in each thread is accumulated. If disabled, then the accumulated
387			times will stay as they are (they start at 0).
388
389			Currently, cpu time is only measured on GNU/Linux systems, all other
390			systems only gather real time.
391
392			Enabling time profiling slows down thread switching by a factor of 2 to
393			10, depending on platform on hardware.
394
395			The times will be displayed when running C<Coro::Debug::command "ps">, and
396			cna be queried by calling C<< $state->times >>.
397
398			=item ($real, $cpu) = $state->times
399
400			Returns the real time and cpu times spent in the given C<$state>. See
401			C<Coro::State::enable_times> for more info.
402
403	root	1.127	=item $clone = $state->clone
404
405	root	1.136	This exciting method takes a Coro::State object and clones it, i.e., it
406			creates a copy. This makes it possible to restore a state more than once,
407			and even return to states that have returned or have been terminated.
408	root	1.127
409	root	1.136	Since its only known purpose is for intellectual self-gratification, and
410	root	1.127	because it is a difficult piece of code, it is not enabled by default, and
411			not supported.
412
413	root	1.140	Here are a few little-known facts: First, coros are full/true/real
414	root	1.136	continuations. Secondly Coro::State objects (without clone) are first
415			class continuations. Thirdly, nobody has ever found a use for the full
416			power of call/cc that isn't better (faster, easier, more efficiently)
417			implemented differently, and nobody has yet found a useful control
418			construct that can't be implemented without it already, just much faster
419	root	1.138	and with fewer resources. And lastly, Scheme's call/cc doesn't support
420			using call/cc to implement threads.
421	root	1.136
422			Among the games you can play with this is implementing a scheme-like
423			call-with-current-continuation, as the following code does (well, with
424			small differences).
425
426			# perl disassociates from local lexicals on frame exit,
427			# so use a global variable for return values.
428			my @ret;
429	root	1.127
430	root	1.136	sub callcc($@) {
431	root	1.129	my ($func, @arg) = @_;
432	root	1.127
433	root	1.136	my $continuation = new Coro::State;
434			$continuation->transfer (new Coro::State sub {
435	root	1.129	my $escape = sub {
436	root	1.136	@ret = @_;
437			Coro::State->new->transfer ($continuation->clone);
438	root	1.129	};
439			$escape->($func->($escape, @arg));
440	root	1.136	});
441	root	1.127
442	root	1.136	my @ret_ = @ret; @ret = ();
443			wantarray ? @ret_ : pop @ret_
444	root	1.127	}
445
446	root	1.136	Which could be used to implement a loop like this:
447
448			async {
449			my $n;
450			my $l = callcc sub { $_[0] };
451
452			$n++;
453			print "iteration $n\n";
454
455			$l->($l) unless $n == 10;
456			};
457
458			If you find this confusing, then you already understand the coolness of
459			call/cc: It can turn anything into spaghetti code real fast.
460	root	1.127
461			Besides, call/cc is much less useful in a Perl-like dynamic language (with
462			references, and its scoping rules) then in, say, scheme.
463
464	root	1.130	Now, the known limitations of C<clone>:
465	root	1.127
466	root	1.140	It probably only works on perl 5.10; it cannot clone a coro inside
467	root	1.129	the substition operator (but windows perl can't fork from there either)
468			and some other contexts, and C<abort ()> is the preferred mechanism to
469			signal errors. It cannot clone a state that has a c context attached
470	root	1.131	(implementing clone on the C level is too hard for me to even try),
471	root	1.140	which rules out calling call/cc from the main coro. It cannot
472	root	1.131	clone a context that hasn't even been started yet. It doesn't work with
473	root	1.130	C<-DDEBUGGING> (but what does). It probably also leaks, and sometimes
474			triggers a few assertions inside Coro. Most of these limitations are
475			fixable with some effort, but that's pointless just to make a point that
476			it could be done.
477	root	1.127
478	root	1.136	The current implementation could without doubt be optimised to be a
479			constant-time operation by doing lazy stack copying, if somebody were
480			insane enough to invest the time.
481
482	root	1.1	=cut
483
484	root	1.115	# used by Coro::Debug only atm.
485	root	1.75	sub debug_desc {
486			$_[0]{desc}
487			}
488
489	root	1.122	# for very deep reasons, we must initialise $Coro::main here.
490
491			{
492			package Coro;
493
494	root	1.140	our $main; # main coro
495			our $current; # current coro
496	root	1.122
497	root	1.151	$main = Coro::new Coro::;
498	root	1.122
499			$main->{desc} = "[main::]";
500
501			# maybe some other module used Coro::Specific before...
502			$main->{_specific} = $current->{_specific}
503			if $current;
504
505			_set_current $main;
506			}
507
508	root	1.155	# we also make sure we have Coro::AnyEvent when AnyEvent is used,
509			# without loading or initialising AnyEvent
510			if (defined $AnyEvent::MODEL) {
511			require Coro::AnyEvent;
512			} else {
513			push @AnyEvent::post_detect, sub { require Coro::AnyEvent };
514			}
515
516	root	1.1	1;
517
518			=back
519
520			=head1 BUGS
521
522	root	1.5	This module is not thread-safe. You must only ever use this module from
523	root	1.94	the same thread (this requirement might be removed in the future).
524	root	1.1
525			=head1 SEE ALSO
526
527			L<Coro>.
528
529			=head1 AUTHOR
530
531	root	1.41	Marc Lehmann <schmorp@schmorp.de>
532	root	1.39	http://home.schmorp.de/
533	root	1.1
534			=cut
535