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 this, only voluntary switching is used so locking problems are
greatly reduced.

This module provides only low-level functionality. See L<Coro> and related
modules for a more useful 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 (4-16k) be
allocated. On systems supporting mmap a 128k stack is allocated, on the
assumption that the OS has on-demand virtual memory. 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.

=over 4

=cut

package Coro::State;

BEGIN {
   $VERSION = 0.13;

   require XSLoader;
   XSLoader::load Coro::State, $VERSION;
}

use base 'Exporter';

@EXPORT_OK = qw(SAVE_DEFAV SAVE_DEFSV SAVE_ERRSV SAVE_CCTXT);

=item $coro = new [$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 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.

=cut

sub initialize {
   my $proc = shift;
   &$proc while 1;
}

sub new {
   my $class = shift;
   my $proc = shift || sub { die "tried to transfer to an empty coroutine" };
   bless _newprocess [$proc, @_], $class;
}

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

   Constant    Effect
   SAVE_DEFAV  save/restore @_
   SAVE_DEFSV  save/restore $_
   SAVE_ERRSV  save/restore $@
   SAVE_CCTXT  save/restore C-stack (you usually want this)

These constants are not exported by default.

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

IMPLEMENTORS NOTE: all Coro::State functions/methods expect either the
usual Coro::State object or a hashref with a key named "_coro_state" that
contains the real Coro::State object. That is, you can do:

  $obj->{_coro_state} = new Coro::State ...;
  Coro::State::transfer(..., $obj);

This exists mainly to ease subclassing (wether through @ISA or not).

=cut

=item $error->($error_coro, $error_msg)

This function will be called on fatal errors. C<$error_msg> and
C<$error_coro> return the error message and the error-causing coroutine
(NOT an object) respectively. This API might change.

=cut

$error = sub {
   print STDERR "FATAL: $_[1]\n";
   exit 51;
};

=item Coro::State::flush

To be efficient (actually, to not be abysmaly slow), this module does
some fair amount of caching (a possibly complex structure for every
subroutine in use). If you don't use coroutines anymore or you want to
reclaim some memory then you can call this function which will flush all
internal caches. The caches will be rebuilt when needed so this is a safe
operation.

=cut

1;

=back

=head1 BUGS

This module has not yet been extensively tested. Expect segfaults and
specially memleaks.

This module is not thread-safe. You must only ever use this module from
the same thread (this requirenmnt might be loosened in the future).

=head1 SEE ALSO

L<Coro>.

=head1 AUTHOR

 Marc Lehmann <pcg@goof.com>
 http://www.goof.com/pcg/marc/

=cut

Revision:	1.11
Committed:	Sat Jul 28 01:41:58 2001 UTC (22 years, 10 months ago) by root
Branch:	MAIN
Changes since 1.10:	+2 -2 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.1	$new->transfer($main);
12			print "in coroutine again, switching back\n";
13			$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			$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 this, only voluntary switching is used so locking problems are
29			greatly reduced.
30
31			This module provides only low-level functionality. See L<Coro> and related
32			modules for a more useful process abstraction including scheduling.
33
34	root	1.9	=head2 MEMORY CONSUMPTION
35
36			A newly created coroutine that has not been used only allocates a
37			relatively small (a few hundred bytes) structure. Only on the first
38			C<transfer> will perl stacks (a few k) and optionally C stack (4-16k) be
39			allocated. On systems supporting mmap a 128k stack is allocated, on the
40			assumption that the OS has on-demand virtual memory. All this is very
41			system-dependent. On my i686-pc-linux-gnu system this amounts to about 10k
42	root	1.11	per coroutine, 5k when the experimental context sharing is enabled.
43	root	1.9
44	root	1.1	=over 4
45
46			=cut
47
48			package Coro::State;
49
50			BEGIN {
51	root	1.11	$VERSION = 0.13;
52	root	1.1
53			require XSLoader;
54			XSLoader::load Coro::State, $VERSION;
55			}
56
57	root	1.5	use base 'Exporter';
58
59	root	1.9	@EXPORT_OK = qw(SAVE_DEFAV SAVE_DEFSV SAVE_ERRSV SAVE_CCTXT);
60	root	1.5
61	root	1.3	=item $coro = new [$coderef] [, @args...]
62	root	1.1
63			Create a new coroutine and return it. The first C<transfer> call to this
64	root	1.10	coroutine will start execution at the given coderef. If the subroutine
65	root	1.1	returns it will be executed again.
66
67			If the coderef is omitted this function will create a new "empty"
68			coroutine, i.e. a coroutine that cannot be transfered to but can be used
69			to save the current coroutine in.
70
71			=cut
72
73	root	1.8	sub initialize {
74	root	1.3	my $proc = shift;
75	root	1.10	&$proc while 1;
76	root	1.3	}
77
78	root	1.1	sub new {
79	root	1.3	my $class = shift;
80	root	1.4	my $proc = shift \|\| sub { die "tried to transfer to an empty coroutine" };
81	root	1.3	bless _newprocess [$proc, @_], $class;
82	root	1.1	}
83
84	root	1.10	=item $prev->transfer($next,$flags)
85	root	1.1
86			Save the state of the current subroutine in C<$prev> and switch to the
87			coroutine saved in C<$next>.
88
89	root	1.5	The "state" of a subroutine includes the scope, i.e. lexical variables and
90			the current execution state. The C<$flags> value can be used to specify
91	root	1.8	that additional state be saved (and later restored), by C<\|\|>-ing the
92			following constants together:
93	root	1.5
94	root	1.9	Constant Effect
95			SAVE_DEFAV save/restore @_
96			SAVE_DEFSV save/restore $_
97			SAVE_ERRSV save/restore $@
98			SAVE_CCTXT save/restore C-stack (you usually want this)
99	root	1.5
100	root	1.10	These constants are not exported by default.
101	root	1.2
102	root	1.5	If you feel that something important is missing then tell me. Also
103	root	1.2	remember that every function call that might call C<transfer> (such
104			as C<Coro::Channel::put>) might clobber any global and/or special
105			variables. Yes, this is by design ;) You can always create your own
106			process abstraction model that saves these variables.
107	root	1.1
108	root	1.9	The easiest way to do this is to create your own scheduling primitive like
109			this:
110	root	1.1
111			sub schedule {
112			local ($_, $@, ...);
113			$old->transfer($new);
114			}
115
116			IMPLEMENTORS NOTE: all Coro::State functions/methods expect either the
117			usual Coro::State object or a hashref with a key named "_coro_state" that
118			contains the real Coro::State object. That is, you can do:
119
120			$obj->{_coro_state} = new Coro::State ...;
121			Coro::State::transfer(..., $obj);
122
123			This exists mainly to ease subclassing (wether through @ISA or not).
124
125			=cut
126
127			=item $error->($error_coro, $error_msg)
128
129			This function will be called on fatal errors. C<$error_msg> and
130			C<$error_coro> return the error message and the error-causing coroutine
131			(NOT an object) respectively. This API might change.
132
133			=cut
134
135			$error = sub {
136	root	1.8	print STDERR "FATAL: $_[1]\n";
137			exit 51;
138	root	1.1	};
139
140	root	1.5	=item Coro::State::flush
141
142			To be efficient (actually, to not be abysmaly slow), this module does
143			some fair amount of caching (a possibly complex structure for every
144			subroutine in use). If you don't use coroutines anymore or you want to
145			reclaim some memory then you can call this function which will flush all
146			internal caches. The caches will be rebuilt when needed so this is a safe
147			operation.
148
149			=cut
150
151	root	1.1	1;
152
153			=back
154
155			=head1 BUGS
156
157			This module has not yet been extensively tested. Expect segfaults and
158			specially memleaks.
159	root	1.5
160			This module is not thread-safe. You must only ever use this module from
161			the same thread (this requirenmnt might be loosened in the future).
162	root	1.1
163			=head1 SEE ALSO
164
165			L<Coro>.
166
167			=head1 AUTHOR
168
169			Marc Lehmann <pcg@goof.com>
170			http://www.goof.com/pcg/marc/
171
172			=cut
173