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 MEMORY CONSUMPTION

A newly created coroutine that has not been used only allocates a
relatively small (a few hundred bytes) structure. Only on the first
C<transfer> will perl allocate stacks (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_64-pc-linux-gnu
system this amounts to about 8k per (non-trivial) coroutine. You can view
the actual memory consumption using Coro::Debug.

=head2 FUNCTIONS

=over 4

=cut

package Coro::State;

use strict;
no warnings "uninitialized";

use XSLoader;

BEGIN {
   our $VERSION = '3.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;
}

use Exporter;
use base Exporter::;

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

=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 $old_save_flags = $state->save ([$new_save_flags])

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

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

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

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

If you feel that something important is missing then tell me. Also
remember that every function call that might call 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
this:

  sub schedule {
     local ($_, $@, ...);
     $old->transfer ($new);
  }

=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->trace ($flags)

Internal function to control tracing. I just mention this so you can stay
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's that starts to use a stack after this call is
guarenteed this minimum size. Please note that Coroutines will only need
to use a C-level stack if the interpreter recurses or calls a function in
a module that calls back into the interpreter.

=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.78
Committed:	Wed Oct 3 01:48:06 2007 UTC (16 years, 8 months ago) by root
Branch:	MAIN
Changes since 1.77:	+1 -29 lines
Log Message:	temporary check-in, non-working version
#	Content
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	print "in coroutine (called with @_), switching back\n";
11	$new->transfer ($main);
12	print "in coroutine again, switching back\n";
13	$new->transfer ($main);
14	}, 5;
15
16	$main = new Coro::State;
17
18	print "in main, switching to coroutine\n";
19	$main->transfer ($new);
20	print "back in main, switch to coroutine again\n";
21	$main->transfer ($new);
22	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	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
34	This module provides only low-level functionality. See L<Coro> and related
35	modules for a higher level process abstraction including scheduling.
36
37	=head2 MEMORY CONSUMPTION
38
39	A newly created coroutine that has not been used only allocates a
40	relatively small (a few hundred bytes) structure. Only on the first
41	C<transfer> will perl allocate stacks (a few kb) and optionally
42	a C stack/coroutine (cctx) for coroutines that recurse through C
43	functions. All this is very system-dependent. On my x86_64-pc-linux-gnu
44	system this amounts to about 8k per (non-trivial) coroutine. You can view
45	the actual memory consumption using Coro::Debug.
46
47	=head2 FUNCTIONS
48
49	=over 4
50
51	=cut
52
53	package Coro::State;
54
55	use strict;
56	no warnings "uninitialized";
57
58	use XSLoader;
59
60	BEGIN {
61	our $VERSION = '3.0';
62
63	# must be done here because the xs part expects it to exist
64	# it might exist already because Coro::Specific created it.
65	$Coro::current \|\|= { };
66
67	XSLoader::load __PACKAGE__, $VERSION;
68	}
69
70	use Exporter;
71	use base Exporter::;
72
73	=item $coro = new Coro::State [$coderef[, @args...]]
74
75	Create a new coroutine and return it. The first C<transfer> call to this
76	coroutine will start execution at the given coderef. If the subroutine
77	returns the program will be terminated as if execution of the main program
78	ended. If it throws an exception the program will terminate.
79
80	Calling C<exit> in a coroutine does the same as calling it in the main
81	program.
82
83	If the coderef is omitted this function will create a new "empty"
84	coroutine, i.e. a coroutine that cannot be transfered to but can be used
85	to save the current coroutine in.
86
87	The returned object is an empty hash which can be used for any purpose
88	whatsoever, for example when subclassing Coro::State.
89
90	=cut
91
92	# this is called for each newly created C coroutine,
93	# and is being artificially injected into the opcode flow.
94	# its sole purpose is to call transfer() once so it knows
95	# the stop level stack frame for stack sharing.
96	sub _cctx_init {
97	_set_stacklevel $_[0];
98	}
99
100	=item $old_save_flags = $state->save ([$new_save_flags])
101
102	TODO
103	It is possible to "localise" certain global variables for each state:
104	for example, it would be awkward if @_ or $_ would suddenly change just
105	because you temporarily switched to another coroutine, so Coro::State can
106	save those variables in the state object on transfers.
107
108	The C<$new_save_flags> value can be used to specify which variables (and
109	other things) are to be saved (and later restored) on each transfer, by
110	ORing the following constants together:
111
112	Constant Effect
113	SAVE_DEFAV save/restore @_
114	SAVE_DEFSV save/restore $_
115	SAVE_ERRSV save/restore $@
116	SAVE_IRSSV save/restore $/ (the Input Record Separator, slow)
117	SAVE_DEFFH save/restore default filehandle (select)
118	SAVE_DEF the default set of saves
119	SAVE_ALL everything that can be saved
120
121	These constants are not exported by default. If you don't need any extra
122	additional variables saved, use C<0> as the flags value.
123
124	If you feel that something important is missing then tell me. Also
125	remember that every function call that might call C<transfer> (such
126	as C<Coro::Channel::put>) might clobber any global and/or special
127	variables. Yes, this is by design ;) You can always create your own
128	process abstraction model that saves these variables.
129
130	The easiest way to do this is to create your own scheduling primitive like
131	this:
132
133	sub schedule {
134	local ($_, $@, ...);
135	$old->transfer ($new);
136	}
137
138	=item $state->has_stack
139
140	Returns wether the state currently uses a cctx/C stack. An active state
141	always has a cctx, as well as the main program. Other states only use a
142	cctx when needed.
143
144	=item $bytes = $state->rss
145
146	Returns the memory allocated by the coroutine (which includes
147	static structures, various perl stacks but NOT local variables,
148	arguments or any C stack).
149
150	=item $state->call ($coderef)
151
152	Try to call the given $coderef in the context of the given state. This
153	works even when the state is currently within an XS function, and can
154	be very dangerous. You can use it to acquire stack traces etc. (see the
155	Coro::Debug module for more details). The coderef MUST NOT EVER transfer
156	to another state.
157
158	=item $state->eval ($string)
159
160	Like C<call>, but eval's the string. Dangerous. Do not
161	use. Untested. Unused. Biohazard.
162
163	=item $state->trace ($flags)
164
165	Internal function to control tracing. I just mention this so you can stay
166	from abusing it.
167
168	=item $prev->transfer ($next)
169
170	Save the state of the current subroutine in C<$prev> and switch to the
171	coroutine saved in C<$next>.
172
173	The "state" of a subroutine includes the scope, i.e. lexical variables and
174	the current execution state (subroutine, stack).
175
176	=item Coro::State::cctx_count
177
178	Returns the number of C-level coroutines allocated. If this number is
179	very high (more than a dozen) it might help to identify points of C-level
180	recursion in your code and moving this into a separate coroutine.
181
182	=item Coro::State::cctx_idle
183
184	Returns the number of allocated but idle (free for reuse) C level
185	coroutines. Currently, Coro will limit the number of idle/unused cctxs to
186	8.
187
188	=item Coro::State::cctx_stacksize [$new_stacksize]
189
190	Returns the current C stack size and optionally sets the new I<minimum>
191	stack size to C<$new_stacksize> I<long>s. Existing stacks will not
192	be changed, but Coro will try to replace smaller stacks as soon as
193	possible. Any Coro::State's that starts to use a stack after this call is
194	guarenteed this minimum size. Please note that Coroutines will only need
195	to use a C-level stack if the interpreter recurses or calls a function in
196	a module that calls back into the interpreter.
197
198	=item @states = Coro::State::list
199
200	Returns a list of all states currently allocated.
201
202	=cut
203
204	sub debug_desc {
205	$_[0]{desc}
206	}
207
208	1;
209
210	=back
211
212	=head1 BUGS
213
214	This module is not thread-safe. You must only ever use this module from
215	the same thread (this requirement might be loosened in the future).
216
217	=head1 SEE ALSO
218
219	L<Coro>.
220
221	=head1 AUTHOR
222
223	Marc Lehmann <schmorp@schmorp.de>
224	http://home.schmorp.de/
225
226	=cut
227