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

=head2 FUNCTIONS

=over 4

=cut

package Coro::State;

use strict;
no warnings "uninitialized";

use XSLoader;

BEGIN {
   our $VERSION = 1.9;

   XSLoader::load __PACKAGE__, $VERSION;
}

use Exporter;
use base Exporter::;

our @EXPORT_OK = qw(SAVE_DEFAV SAVE_DEFSV SAVE_ERRSV SAVE_CURPM 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

# this is called (or rather: goto'ed) for each and every
# new coroutine. IT MUST NEVER RETURN!
sub initialize {
   my $proc = shift;
   eval {
      &$proc while 1;
   };
   if ($@) {
      print STDERR "FATAL: uncaught exception\n$@";
   }
   _exit 255;
}

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 (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 $@
   SAVE_CCTXT  save/restore C-stack (you usually want this for coroutines)

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

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

1;

=back

=head1 BUGS

This module has not yet been extensively tested, but works on most
platforms. Expect segfaults and memleaks (but please don't be surprised if
it works...)

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.52
Committed:	Wed Feb 1 23:59:41 2006 UTC (18 years, 11 months ago) by root
Branch:	MAIN
CVS Tags:	rel-2_0, rel-2_1, rel-1_9
Changes since 1.51:	+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 (4-16k) be
42	allocated. On systems supporting mmap a 128k stack is allocated, on the
43	assumption that the OS has on-demand virtual memory. All this is very
44	system-dependent. On my i686-pc-linux-gnu system this amounts to about 10k
45	per coroutine, 5k when the experimental context sharing is enabled.
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 = 1.9;
62
63	XSLoader::load __PACKAGE__, $VERSION;
64	}
65
66	use Exporter;
67	use base Exporter::;
68
69	our @EXPORT_OK = qw(SAVE_DEFAV SAVE_DEFSV SAVE_ERRSV SAVE_CURPM SAVE_CCTXT);
70
71	=item $coro = new [$coderef] [, @args...]
72
73	Create a new coroutine and return it. The first C<transfer> call to this
74	coroutine will start execution at the given coderef. If the subroutine
75	returns it will be executed again.
76
77	If the coderef is omitted this function will create a new "empty"
78	coroutine, i.e. a coroutine that cannot be transfered to but can be used
79	to save the current coroutine in.
80
81	=cut
82
83	# this is called (or rather: goto'ed) for each and every
84	# new coroutine. IT MUST NEVER RETURN!
85	sub initialize {
86	my $proc = shift;
87	eval {
88	&$proc while 1;
89	};
90	if ($@) {
91	print STDERR "FATAL: uncaught exception\n$@";
92	}
93	_exit 255;
94	}
95
96	sub new {
97	my $class = shift;
98	my $proc = shift \|\| sub { die "tried to transfer to an empty coroutine" };
99	bless _newprocess [$proc, @_], $class;
100	}
101
102	=item $prev->transfer ($next, $flags)
103
104	Save the state of the current subroutine in C<$prev> and switch to the
105	coroutine saved in C<$next>.
106
107	The "state" of a subroutine includes the scope, i.e. lexical variables and
108	the current execution state (subroutine, stack). The C<$flags> value can
109	be used to specify that additional state to be saved (and later restored), 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_CCTXT save/restore C-stack (you usually want this for coroutines)
117
118	These constants are not exported by default. If you don't need any extra
119	additional state saved, use C<0> as the flags value.
120
121	If you feel that something important is missing then tell me. Also
122	remember that every function call that might call C<transfer> (such
123	as C<Coro::Channel::put>) might clobber any global and/or special
124	variables. Yes, this is by design ;) You can always create your own
125	process abstraction model that saves these variables.
126
127	The easiest way to do this is to create your own scheduling primitive like
128	this:
129
130	sub schedule {
131	local ($_, $@, ...);
132	$old->transfer ($new);
133	}
134
135	IMPLEMENTORS NOTE: all Coro::State functions/methods expect either the
136	usual Coro::State object or a hashref with a key named "_coro_state" that
137	contains the real Coro::State object. That is, you can do:
138
139	$obj->{_coro_state} = new Coro::State ...;
140	Coro::State::transfer (..., $obj);
141
142	This exists mainly to ease subclassing (wether through @ISA or not).
143
144	=cut
145
146	1;
147
148	=back
149
150	=head1 BUGS
151
152	This module has not yet been extensively tested, but works on most
153	platforms. Expect segfaults and memleaks (but please don't be surprised if
154	it works...)
155
156	This module is not thread-safe. You must only ever use this module from
157	the same thread (this requirement might be loosened in the future).
158
159	=head1 SEE ALSO
160
161	L<Coro>.
162
163	=head1 AUTHOR
164
165	Marc Lehmann <schmorp@schmorp.de>
166	http://home.schmorp.de/
167
168	=cut
169