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);

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

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 $@ if $@;
   _exit 254;
}

=item $prev->transfer ($next, $flags)

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). The C<$flags> value can
be used to specify that additional state to be saved (and later restored), by
oring the following constants together:

   Constant    Effect
   SAVE_DEFAV  save/restore @_
   SAVE_DEFSV  save/restore $_
   SAVE_ERRSV  save/restore $@

These constants are not exported by default. If you don't need any extra
additional state 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 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.69
Committed:	Mon Dec 4 03:48:16 2006 UTC (17 years, 6 months ago) by root
Branch:	MAIN
Changes since 1.68:	+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.9	=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	root	1.67	C<transfer> will perl stacks (a few k) and optionally C stack. All this
42	root	1.66	is very system-dependent. On my x86_64-pc-linux-gnu system this amounts
43	root	1.67	to about 8k per (non-trivial) coroutine.
44	root	1.9
45	root	1.42	=head2 FUNCTIONS
46
47	root	1.1	=over 4
48
49			=cut
50
51			package Coro::State;
52
53	root	1.47	use strict;
54			no warnings "uninitialized";
55
56			use XSLoader;
57	root	1.18
58	root	1.1	BEGIN {
59	root	1.58	our $VERSION = '3.0';
60	root	1.1
61	root	1.67	# 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	root	1.47	XSLoader::load __PACKAGE__, $VERSION;
66	root	1.1	}
67
68	root	1.51	use Exporter;
69	root	1.47	use base Exporter::;
70	root	1.5
71	root	1.60	our @EXPORT_OK = qw(SAVE_DEFAV SAVE_DEFSV SAVE_ERRSV);
72	root	1.5
73	root	1.65	=item $coro = new Coro::State [$coderef[, @args...]]
74	root	1.1
75			Create a new coroutine and return it. The first C<transfer> call to this
76	root	1.10	coroutine will start execution at the given coderef. If the subroutine
77	root	1.53	returns it will be executed again. If it throws an exception the program
78			will terminate.
79	root	1.1
80	root	1.62	Calling C<exit> in a coroutine will not work correctly, so do not do that.
81
82	root	1.1	If the coderef is omitted this function will create a new "empty"
83			coroutine, i.e. a coroutine that cannot be transfered to but can be used
84			to save the current coroutine in.
85
86	root	1.55	The returned object is an empty hash which can be used for any purpose
87			whatsoever, for example when subclassing Coro::State.
88
89	root	1.1	=cut
90
91	root	1.60	# this is called for each newly created C coroutine,
92	root	1.68	# and is being artificially injected into the opcode flow.
93			# its sole purpose is to call transfer() once so it knows
94			# the stop level stack frame for stack sharing.
95	root	1.64	sub _cctx_init {
96	root	1.68	_set_stacklevel $_[0];
97	root	1.57	}
98
99	root	1.12	# this is called (or rather: goto'ed) for each and every
100	root	1.44	# new coroutine. IT MUST NEVER RETURN!
101	root	1.64	sub _coro_init {
102	root	1.13	eval {
103	root	1.68	my $coro = shift;
104			$coro or die "transfer() to empty coroutine $coro";
105			&$coro;
106	root	1.13	};
107	root	1.53	print STDERR $@ if $@;
108	root	1.69	_exit 254;
109	root	1.3	}
110
111	root	1.43	=item $prev->transfer ($next, $flags)
112	root	1.1
113			Save the state of the current subroutine in C<$prev> and switch to the
114			coroutine saved in C<$next>.
115
116	root	1.5	The "state" of a subroutine includes the scope, i.e. lexical variables and
117	root	1.23	the current execution state (subroutine, stack). The C<$flags> value can
118	root	1.44	be used to specify that additional state to be saved (and later restored), by
119			oring the following constants together:
120	root	1.5
121	root	1.9	Constant Effect
122			SAVE_DEFAV save/restore @_
123			SAVE_DEFSV save/restore $_
124			SAVE_ERRSV save/restore $@
125	root	1.5
126	root	1.15	These constants are not exported by default. If you don't need any extra
127	root	1.44	additional state saved, use C<0> as the flags value.
128	root	1.2
129	root	1.5	If you feel that something important is missing then tell me. Also
130	root	1.2	remember that every function call that might call C<transfer> (such
131			as C<Coro::Channel::put>) might clobber any global and/or special
132			variables. Yes, this is by design ;) You can always create your own
133			process abstraction model that saves these variables.
134	root	1.1
135	root	1.9	The easiest way to do this is to create your own scheduling primitive like
136			this:
137	root	1.1
138			sub schedule {
139			local ($_, $@, ...);
140	root	1.42	$old->transfer ($new);
141	root	1.1	}
142
143	root	1.64	=item Coro::State::cctx_count
144
145			Returns the number of C-level coroutines allocated. If this number is
146			very high (more than a dozen) it might help to identify points of C-level
147			recursion in your code and moving this into a separate coroutine.
148
149			=item Coro::State::cctx_idle
150
151			Returns the number of allocated but idle (free for reuse) C level
152			coroutines. As C level coroutines are curretly rarely being deallocated, a
153			high number means that you used many C coroutines in the past.
154
155	root	1.1	=cut
156
157			1;
158
159			=back
160
161			=head1 BUGS
162
163	root	1.5	This module is not thread-safe. You must only ever use this module from
164	root	1.42	the same thread (this requirement might be loosened in the future).
165	root	1.1
166			=head1 SEE ALSO
167
168			L<Coro>.
169
170			=head1 AUTHOR
171
172	root	1.41	Marc Lehmann <schmorp@schmorp.de>
173	root	1.39	http://home.schmorp.de/
174	root	1.1
175			=cut
176