Coro/Coro/State.pm

=head1 NAME

Coro::State - first class continuations

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

=head1 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 L<Coro> and related
modules for a higher level process abstraction including scheduling.

=head2 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 available 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
L<Coro::Debug>) to find out which coroutines are tied to their cctx and
which aren't.

=head2 MEMORY CONSUMPTION

A newly created coroutine 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/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.

=cut

package Coro::State;

use strict;
no warnings "uninitialized";

use Carp;

use Time::HiRes (); # currently only used for PerlIO::cede

our $DIEHOOK;
our $WARNHOOK;

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

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

use XSLoader;

BEGIN {
   our $VERSION = 5.1;

   # 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 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).

If you don't want to exit your program on uncaught exceptions, you can
must not return from your die hook - 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 coroutines, so
changing its value will change it in all coroutines 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 coroutine and return it. The first C<transfer> call to this
coroutine 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 coroutine receives passed arguments by reference, so
make sure you don't change them in unexpected ways.

Returning from such a coroutine 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 coroutine 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"
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
   $^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 coroutines:

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

=cut

=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
coroutine a defined content for C<@_> and C<$_> before transfer'ing to it.

=item $state->trace ($flags)

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

=item $prev->transfer ($next)

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

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

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

=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 coroutine
(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 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.

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

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

=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 @states = Coro::State::list

Returns a list of all states currently allocated.

=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, coroutines *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.

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 coroutine 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 coroutine. 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 coroutine
   our $current; # current coroutine

   $main = Coro::State::new Coro::;

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

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

   _set_current $main;
}

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