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 stacks (a few k) and optionally C stack. All this
is very system-dependent. On my x86_64-pc-linux-gnu system this amounts
to about 8k per (non-trivial) coroutine.

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

our @EXPORT_OK = qw(SAVE_DEFAV SAVE_DEFSV SAVE_ERRSV SAVE_IRSSV SAVE_ALL);

=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 it will be executed again. If it throws an exception the program
will terminate.

The initial save flags for a new state is C<SAVE_ALL>, which can be
changed using the C<save> method.

Calling C<exit> in a coroutine will not work correctly, so do not do that.

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];
}

# this is called (or rather: goto'ed) for each and every
# new coroutine. IT MUST NEVER RETURN!
sub _coro_init {
   eval {
      my $coro = shift;
      $coro or die "transfer() to empty coroutine $coro";
      &$coro;
   };
   print STDERR $@ || "FATAL: Coro::State callback returned unexpectedly, exiting.\n";
   _exit 254;
}

=item $old_save_flags = $state->save ([$new_save_flags])

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_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 $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. As C level coroutines are curretly rarely being deallocated, a
high number means that you used many C coroutines in the past.

=cut

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.71
Committed:	Mon Dec 4 21:56:00 2006 UTC (17 years, 6 months ago) by root
Branch:	MAIN
CVS Tags:	rel-3_41, rel-3_51, rel-3_4, rel-3_1, rel-3_5, rel-3_3, rel-3_2, rel-3_11, rel-3_501
Changes since 1.70:	+2 -2 lines
Log Message:	* empty log message *
#	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 stacks (a few k) and optionally C stack. All this
42	is very system-dependent. On my x86_64-pc-linux-gnu system this amounts
43	to about 8k per (non-trivial) coroutine.
44
45	=head2 FUNCTIONS
46
47	=over 4
48
49	=cut
50
51	package Coro::State;
52
53	use strict;
54	no warnings "uninitialized";
55
56	use XSLoader;
57
58	BEGIN {
59	our $VERSION = '3.0';
60
61	# must be done here because the xs part expects it to exist
62	# it might exist already because Coro::Specific created it.
63	$Coro::current \|\|= { };
64
65	XSLoader::load __PACKAGE__, $VERSION;
66	}
67
68	use Exporter;
69	use base Exporter::;
70
71	our @EXPORT_OK = qw(SAVE_DEFAV SAVE_DEFSV SAVE_ERRSV SAVE_IRSSV SAVE_ALL);
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 it will be executed again. If it throws an exception the program
78	will terminate.
79
80	The initial save flags for a new state is C<SAVE_ALL>, which can be
81	changed using the C<save> method.
82
83	Calling C<exit> in a coroutine will not work correctly, so do not do that.
84
85	If the coderef is omitted this function will create a new "empty"
86	coroutine, i.e. a coroutine that cannot be transfered to but can be used
87	to save the current coroutine in.
88
89	The returned object is an empty hash which can be used for any purpose
90	whatsoever, for example when subclassing Coro::State.
91
92	=cut
93
94	# this is called for each newly created C coroutine,
95	# and is being artificially injected into the opcode flow.
96	# its sole purpose is to call transfer() once so it knows
97	# the stop level stack frame for stack sharing.
98	sub _cctx_init {
99	_set_stacklevel $_[0];
100	}
101
102	# this is called (or rather: goto'ed) for each and every
103	# new coroutine. IT MUST NEVER RETURN!
104	sub _coro_init {
105	eval {
106	my $coro = shift;
107	$coro or die "transfer() to empty coroutine $coro";
108	&$coro;
109	};
110	print STDERR $@ \|\| "FATAL: Coro::State callback returned unexpectedly, exiting.\n";
111	_exit 254;
112	}
113
114	=item $old_save_flags = $state->save ([$new_save_flags])
115
116	It is possible to "localise" certain global variables for each state:
117	for example, it would be awkward if @_ or $_ would suddenly change just
118	because you temporarily switched to another coroutine, so Coro::State can
119	save those variables in the state object on transfers.
120
121	The C<$new_save_flags> value can be used to specify which variables (and
122	other things) are to be saved (and later restored) on each transfer, by
123	ORing the following constants together:
124
125	Constant Effect
126	SAVE_DEFAV save/restore @_
127	SAVE_DEFSV save/restore $_
128	SAVE_ERRSV save/restore $@
129	SAVE_IRSSV save/restore $/ (the Input Record Separator, slow)
130	SAVE_ALL everything that can be saved
131
132	These constants are not exported by default. If you don't need any extra
133	additional variables saved, use C<0> as the flags value.
134
135	If you feel that something important is missing then tell me. Also
136	remember that every function call that might call C<transfer> (such
137	as C<Coro::Channel::put>) might clobber any global and/or special
138	variables. Yes, this is by design ;) You can always create your own
139	process abstraction model that saves these variables.
140
141	The easiest way to do this is to create your own scheduling primitive like
142	this:
143
144	sub schedule {
145	local ($_, $@, ...);
146	$old->transfer ($new);
147	}
148
149	=item $prev->transfer ($next)
150
151	Save the state of the current subroutine in C<$prev> and switch to the
152	coroutine saved in C<$next>.
153
154	The "state" of a subroutine includes the scope, i.e. lexical variables and
155	the current execution state (subroutine, stack).
156
157	=item Coro::State::cctx_count
158
159	Returns the number of C-level coroutines allocated. If this number is
160	very high (more than a dozen) it might help to identify points of C-level
161	recursion in your code and moving this into a separate coroutine.
162
163	=item Coro::State::cctx_idle
164
165	Returns the number of allocated but idle (free for reuse) C level
166	coroutines. As C level coroutines are curretly rarely being deallocated, a
167	high number means that you used many C coroutines in the past.
168
169	=cut
170
171	1;
172
173	=back
174
175	=head1 BUGS
176
177	This module is not thread-safe. You must only ever use this module from
178	the same thread (this requirement might be loosened in the future).
179
180	=head1 SEE ALSO
181
182	L<Coro>.
183
184	=head1 AUTHOR
185
186	Marc Lehmann <schmorp@schmorp.de>
187	http://home.schmorp.de/
188
189	=cut
190