Coro/Coro/State.pm

=head1 NAME

Coro::State - create and manage simple coroutines

=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,
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 avaikable 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 cna 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) 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;

our $DIEHOOK;
our $WARNHOOK;

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

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

use XSLoader;

BEGIN {
   our $VERSION = 4.6;

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

   $SIG{__DIE__}  = \&diehook;
   $SIG{__WARN__} = \&warnhook;

   XSLoader::load __PACKAGE__, $VERSION;
}

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 overriden already.

The default handlers provided will behave like the inbuilt ones (as if
they weren't there).

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 using them.

=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. If the subroutine
returns the program will be terminated as if execution of the main program
ended. If it throws an exception the program will terminate.

Calling C<exit> in a coroutine does the same as calling it in the main
program.

If the coderef is omitted this function will create a new "empty"
coroutine, i.e. a coroutine that cannot be transfered to but can be used
to save the current coroutine in.

The returned object is an empty hash which can be used for any purpose
whatsoever, for example when subclassing Coro::State.

Certain variables are "localised" to each coroutine, that is, certain
"global" variables are actually per coroutine. Not everything that would
sensibly be localised currently is, and not everything that is localised
makes sense for every application, and the future might bring changes.

The following global variables can have different values 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
   $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
below, and use it in your coroutines:

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

=cut

# this is called for each newly created C coroutine,
# and is being artificially injected into the opcode flow.
# its sole purpose is to call transfer() once so it knows
# the stop level stack frame for stack sharing.
sub _cctx_init {
   _set_stacklevel $_[0];
}

=item $state->has_stack

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

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

=item $state->call ($coderef)

Try to call the given $coderef in the context of the given state.  This
works even when the state is currently within an XS function, and can
be very dangerous. You can use it to acquire stack traces etc. (see the
Coro::Debug module for more details). The coderef MUST NOT EVER transfer
to another state.

=item $state->eval ($string)

Like C<call>, but eval's the string. Dangerous. Do not
use. Untested. Unused. Biohazard.

=item $state->throw ($exception)

Makes the coroutine throw the given exception as soon as it regains
control. Untested. Unused. Biohazard.

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

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

Returns a list of all states currently allocated.

=cut

sub debug_desc {
   $_[0]{desc}
}

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

=head1 SEE ALSO

L<Coro>.

=head1 AUTHOR

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

=cut

Revision:	1.93
Committed:	Fri Apr 25 04:28:50 2008 UTC (16 years, 1 month ago) by root
Branch:	MAIN
Changes since 1.92:	+1 -1 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			Coro::State - create and manage simple coroutines
4
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			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			which it is again avaikable to run other Perl coroutines.
49
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			be at least one additional C coroutine. You cna use the debugger (see
53			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			C<transfer> will perl allocate stacks (a few kb, 64 bit architetcures use
61			twice as much) and optionally a C stack/coroutine (cctx) for coroutines
62			that recurse through C functions. All this is very system-dependent. On
63			my x86-pc-linux-gnu system this amounts to about 2k per (non-trivial
64			but simple) coroutine. You can view the actual memory consumption using
65			Coro::Debug. Keep in mind that a for loop or other block constructs can
66			easily consume 100-200 bytes per nesting level.
67	root	1.1
68			=cut
69
70			package Coro::State;
71
72	root	1.47	use strict;
73			no warnings "uninitialized";
74
75	root	1.84	use Carp;
76	root	1.87
77			our $DIEHOOK;
78			our $WARNHOOK;
79
80			BEGIN {
81			$DIEHOOK = sub { };
82			$WARNHOOK = sub { warn $_[0] };
83			}
84
85			sub diehook { &$DIEHOOK }
86			sub warnhook { &$WARNHOOK }
87	root	1.84
88	root	1.47	use XSLoader;
89	root	1.18
90	root	1.1	BEGIN {
91	root	1.93	our $VERSION = 4.6;
92	root	1.1
93	root	1.67	# must be done here because the xs part expects it to exist
94			# it might exist already because Coro::Specific created it.
95			$Coro::current \|\|= { };
96
97	root	1.87	$SIG{__DIE__} = \&diehook;
98			$SIG{__WARN__} = \&warnhook;
99
100	root	1.47	XSLoader::load __PACKAGE__, $VERSION;
101	root	1.1	}
102
103	root	1.51	use Exporter;
104	root	1.47	use base Exporter::;
105	root	1.5
106	root	1.84	=head2 GLOBAL VARIABLES
107
108			=over 4
109
110			=item $Coro::State::DIEHOOK
111
112			This works similarly to C<$SIG{__DIE__}> and is used as the default die
113			hook for newly created coroutines. This is useful if you want some generic
114			logging function that works for all coroutines that don't set their own
115			hook.
116
117			When Coro::State is first loaded it will install these handlers for the
118			main program, too, unless they have been overriden already.
119
120			The default handlers provided will behave like the inbuilt ones (as if
121			they weren't there).
122
123	root	1.89	Note 1: You I<must> store a valid code reference in these variables, C<undef> will I<not> do.
124	root	1.84
125	root	1.89	Note 2: The value of this variable will be shared among all coroutines, so
126	root	1.84	changing its value will change it in all coroutines using them.
127
128			=item $Coro::State::WARNHOOK
129
130			Similar to above die hook, but augments C<$SIG{__WARN__}>.
131
132			=back
133
134			=head2 FUNCTIONS
135
136			=over 4
137
138	root	1.65	=item $coro = new Coro::State [$coderef[, @args...]]
139	root	1.1
140			Create a new coroutine and return it. The first C<transfer> call to this
141	root	1.10	coroutine will start execution at the given coderef. If the subroutine
142	root	1.74	returns the program will be terminated as if execution of the main program
143			ended. If it throws an exception the program will terminate.
144
145			Calling C<exit> in a coroutine does the same as calling it in the main
146			program.
147	root	1.1
148			If the coderef is omitted this function will create a new "empty"
149			coroutine, i.e. a coroutine that cannot be transfered to but can be used
150			to save the current coroutine in.
151
152	root	1.55	The returned object is an empty hash which can be used for any purpose
153			whatsoever, for example when subclassing Coro::State.
154
155	root	1.79	Certain variables are "localised" to each coroutine, that is, certain
156			"global" variables are actually per coroutine. Not everything that would
157			sensibly be localised currently is, and not everything that is localised
158			makes sense for every application, and the future might bring changes.
159	root	1.1
160	root	1.84	The following global variables can have different values per coroutine,
161			and have the stated initial values:
162	root	1.5
163	root	1.83	Variable Initial Value
164			@_ whatever arguments were passed to the Coro
165			$_ undef
166			$@ undef
167			$/ "\n"
168	root	1.88	$SIG{__DIE__} aliased to $Coro::State::DIEHOOK(*)
169			$SIG{__WARN__} aliased to $Coro::State::WARNHOOK(*)
170	root	1.83	(default fh) *STDOUT
171	root	1.84	$1, $2... all regex results are initially undefined
172	root	1.2
173	root	1.88	(*) reading the value from %SIG is not supported, but local'ising is.
174
175	root	1.70	If you feel that something important is missing then tell me. Also
176	root	1.2	remember that every function call that might call C<transfer> (such
177			as C<Coro::Channel::put>) might clobber any global and/or special
178			variables. Yes, this is by design ;) You can always create your own
179			process abstraction model that saves these variables.
180	root	1.1
181	root	1.9	The easiest way to do this is to create your own scheduling primitive like
182	root	1.84	below, and use it in your coroutines:
183	root	1.1
184	root	1.84	sub my_cede {
185	root	1.80	local ($;, ...);
186	root	1.84	Coro::cede;
187	root	1.1	}
188
189	root	1.79	=cut
190
191			# this is called for each newly created C coroutine,
192			# and is being artificially injected into the opcode flow.
193			# its sole purpose is to call transfer() once so it knows
194			# the stop level stack frame for stack sharing.
195			sub _cctx_init {
196			_set_stacklevel $_[0];
197			}
198
199	root	1.76	=item $state->has_stack
200
201			Returns wether the state currently uses a cctx/C stack. An active state
202			always has a cctx, as well as the main program. Other states only use a
203			cctx when needed.
204
205			=item $bytes = $state->rss
206
207			Returns the memory allocated by the coroutine (which includes
208			static structures, various perl stacks but NOT local variables,
209			arguments or any C stack).
210
211			=item $state->call ($coderef)
212
213			Try to call the given $coderef in the context of the given state. This
214			works even when the state is currently within an XS function, and can
215			be very dangerous. You can use it to acquire stack traces etc. (see the
216			Coro::Debug module for more details). The coderef MUST NOT EVER transfer
217			to another state.
218
219			=item $state->eval ($string)
220
221			Like C<call>, but eval's the string. Dangerous. Do not
222			use. Untested. Unused. Biohazard.
223
224	root	1.90	=item $state->throw ($exception)
225
226			Makes the coroutine throw the given exception as soon as it regains
227			control. Untested. Unused. Biohazard.
228
229			=item $state->swap_defsv
230
231			=item $state->swap_defav
232
233			Swap the current C<$_> (swap_defsv) or C<@_> (swap_defav) with the
234			equivalent in the saved state of C<$state>. This can be used to give the
235			coroutine a defined content for C<@_> and C<$_> before transfer'ing to it.
236
237	root	1.77	=item $state->trace ($flags)
238
239			Internal function to control tracing. I just mention this so you can stay
240	root	1.90	away from abusing it.
241	root	1.77
242	root	1.70	=item $prev->transfer ($next)
243
244			Save the state of the current subroutine in C<$prev> and switch to the
245			coroutine saved in C<$next>.
246
247			The "state" of a subroutine includes the scope, i.e. lexical variables and
248			the current execution state (subroutine, stack).
249
250	root	1.64	=item Coro::State::cctx_count
251
252			Returns the number of C-level coroutines allocated. If this number is
253			very high (more than a dozen) it might help to identify points of C-level
254			recursion in your code and moving this into a separate coroutine.
255
256			=item Coro::State::cctx_idle
257
258			Returns the number of allocated but idle (free for reuse) C level
259	root	1.76	coroutines. Currently, Coro will limit the number of idle/unused cctxs to
260			8.
261	root	1.64
262	root	1.72	=item Coro::State::cctx_stacksize [$new_stacksize]
263
264			Returns the current C stack size and optionally sets the new I<minimum>
265			stack size to C<$new_stacksize> I<long>s. Existing stacks will not
266			be changed, but Coro will try to replace smaller stacks as soon as
267	root	1.91	possible. Any Coro::State that starts to use a stack after this call is
268			guaranteed this minimum stack size. Please note that Coroutines will
269			only need to use a C-level stack if the interpreter recurses or calls a
270			function in a module that calls back into the interpreter.
271	root	1.72
272	root	1.92	=item Coro::State::force_cctx
273
274			Forces the allocation of a C context for the currently running coroutine
275			(if not already done). Apart from benchmarking there is little point
276			in doing so, however.
277
278	root	1.76	=item @states = Coro::State::list
279
280			Returns a list of all states currently allocated.
281
282	root	1.1	=cut
283
284	root	1.75	sub debug_desc {
285			$_[0]{desc}
286			}
287
288	root	1.1	1;
289
290			=back
291
292			=head1 BUGS
293
294	root	1.5	This module is not thread-safe. You must only ever use this module from
295	root	1.42	the same thread (this requirement might be loosened in the future).
296	root	1.1
297			=head1 SEE ALSO
298
299			L<Coro>.
300
301			=head1 AUTHOR
302
303	root	1.41	Marc Lehmann <schmorp@schmorp.de>
304	root	1.39	http://home.schmorp.de/
305	root	1.1
306			=cut
307