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 i686-pc-linux-gnu system this amounts
to about 10k per coroutine, 5k when the experimental context sharing is
enabled.

=head2 FUNCTIONS

=over 4

=cut

package Coro::State;

use strict;
no warnings "uninitialized";

use XSLoader;

BEGIN {
   our $VERSION = '3.0';

   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

our $_cctx; # holds the coro_cctx pointer

# this is called for each newly created C coroutine,
# and is being artificially injected into the opcode flow
sub _cctx_init {
   _set_stacklevel $_cctx;
}

# this is called (or rather: goto'ed) for each and every
# new coroutine. IT MUST NEVER RETURN!
sub _coro_init {
   eval {
      $_[0] or die "transfer() to empty coroutine $_[0]";
      &{$_[0]} while 1;
   };
   print STDERR $@ if $@;
   _exit 55;
}

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