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;

no warnings qw(uninitialized);

BEGIN {
   $VERSION = 0.651;

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

use base 'Exporter';

@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 and should not call
# anything that changes the stacklevel (like eval).
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 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 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

=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.30
Committed:	Sat Mar 29 14:09:17 2003 UTC (21 years, 2 months ago) by root
Branch:	MAIN
Changes since 1.29:	+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 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	=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	per coroutine, 5k when the experimental context sharing is enabled.
43
44	=over 4
45
46	=cut
47
48	package Coro::State;
49
50	no warnings qw(uninitialized);
51
52	BEGIN {
53	$VERSION = 0.651;
54
55	require XSLoader;
56	XSLoader::load Coro::State, $VERSION;
57	}
58
59	use base 'Exporter';
60
61	@EXPORT_OK = qw(SAVE_DEFAV SAVE_DEFSV SAVE_ERRSV SAVE_CURPM SAVE_CCTXT);
62
63	=item $coro = new [$coderef] [, @args...]
64
65	Create a new coroutine and return it. The first C<transfer> call to this
66	coroutine will start execution at the given coderef. If the subroutine
67	returns it will be executed again.
68
69	If the coderef is omitted this function will create a new "empty"
70	coroutine, i.e. a coroutine that cannot be transfered to but can be used
71	to save the current coroutine in.
72
73	=cut
74
75	# this is called (or rather: goto'ed) for each and every
76	# new coroutine. IT MUST NEVER RETURN and should not call
77	# anything that changes the stacklevel (like eval).
78	sub initialize {
79	my $proc = shift;
80	eval {
81	&$proc while 1;
82	};
83	if ($@) {
84	print STDERR "FATAL: uncaught exception\n$@";
85	}
86	_exit 255;
87	}
88
89	sub new {
90	my $class = shift;
91	my $proc = shift \|\| sub { die "tried to transfer to an empty coroutine" };
92	bless _newprocess [$proc, @_], $class;
93	}
94
95	=item $prev->transfer($next,$flags)
96
97	Save the state of the current subroutine in C<$prev> and switch to the
98	coroutine saved in C<$next>.
99
100	The "state" of a subroutine includes the scope, i.e. lexical variables and
101	the current execution state (subroutine, stack). The C<$flags> value can
102	be used to specify that additional state be saved (and later restored), by
103	C<\|\|>-ing the following constants together:
104
105	Constant Effect
106	SAVE_DEFAV save/restore @_
107	SAVE_DEFSV save/restore $_
108	SAVE_ERRSV save/restore $@
109	SAVE_CCTXT save/restore C-stack (you usually want this)
110
111	These constants are not exported by default. If you don't need any extra
112	additional state saved use C<0> as the flags value.
113
114	If you feel that something important is missing then tell me. Also
115	remember that every function call that might call C<transfer> (such
116	as C<Coro::Channel::put>) might clobber any global and/or special
117	variables. Yes, this is by design ;) You can always create your own
118	process abstraction model that saves these variables.
119
120	The easiest way to do this is to create your own scheduling primitive like
121	this:
122
123	sub schedule {
124	local ($_, $@, ...);
125	$old->transfer($new);
126	}
127
128	IMPLEMENTORS NOTE: all Coro::State functions/methods expect either the
129	usual Coro::State object or a hashref with a key named "_coro_state" that
130	contains the real Coro::State object. That is, you can do:
131
132	$obj->{_coro_state} = new Coro::State ...;
133	Coro::State::transfer(..., $obj);
134
135	This exists mainly to ease subclassing (wether through @ISA or not).
136
137	=cut
138
139	=item Coro::State::flush
140
141	To be efficient (actually, to not be abysmaly slow), this module does
142	some fair amount of caching (a possibly complex structure for every
143	subroutine in use). If you don't use coroutines anymore or you want to
144	reclaim some memory then you can call this function which will flush all
145	internal caches. The caches will be rebuilt when needed so this is a safe
146	operation.
147
148	=cut
149
150	1;
151
152	=back
153
154	=head1 BUGS
155
156	This module has not yet been extensively tested. Expect segfaults and
157	specially memleaks.
158
159	This module is not thread-safe. You must only ever use this module from
160	the same thread (this requirenmnt might be loosened in the future).
161
162	=head1 SEE ALSO
163
164	L<Coro>.
165
166	=head1 AUTHOR
167
168	Marc Lehmann <pcg@goof.com>
169	http://www.goof.com/pcg/marc/
170
171	=cut
172