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 = 6.0;

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

   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->throw ([$scalar])

=item $state->is_new

=item $state->is_zombie

See the corresponding method for L<Coro> objects. 

=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
effectively dead, destructors have been freed, it cannot be transfered to
anymore, it's pushing up the daisies.

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