ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Coro/Coro/State.pm
Revision: 1.121
Committed: Fri Nov 14 02:42:26 2008 UTC (15 years, 6 months ago) by root
Branch: MAIN
Changes since 1.120: +1 -1 lines
Log Message:
*** empty log message ***

File Contents

# 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 (non-clonable) 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 MODEL
38
39 Coro::State implements two different coroutine models: Perl and C. The
40 C coroutines (called cctx's) are basically simplified perl interpreters
41 running/interpreting the Perl coroutines. A single interpreter can run any
42 number of Perl coroutines, so usually there are very few C coroutines.
43
44 When Perl code calls a C function (e.g. in an extension module) and that
45 C function then calls back into Perl or does a coroutine switch the C
46 coroutine can no longer execute other Perl coroutines, so it stays tied to
47 the specific coroutine until it returns to the original Perl caller, after
48 which it is again avaikable to run other Perl coroutines.
49
50 The main program always has its own "C coroutine" (which really is
51 *the* Perl interpreter running the whole program), so there will always
52 be at least one additional C coroutine. You can use the debugger (see
53 L<Coro::Debug>) to find out which coroutines are tied to their cctx and
54 which aren't.
55
56 =head2 MEMORY CONSUMPTION
57
58 A newly created coroutine that has not been used only allocates a
59 relatively small (a hundred bytes) structure. Only on the first
60 C<transfer> will perl allocate stacks (a few kb, 64 bit architetcures
61 use twice as much, i.e. a few kb :) and optionally a C stack/coroutine
62 (cctx) for coroutines that recurse through C functions. All this is very
63 system-dependent. On my x86-pc-linux-gnu system this amounts to about 2k
64 per (non-trivial but simple) coroutine.
65
66 You can view the actual memory consumption using Coro::Debug. Keep in mind
67 that a for loop or other block constructs can easily consume 100-200 bytes
68 per nesting level.
69
70 =cut
71
72 package Coro::State;
73
74 use strict;
75 no warnings "uninitialized";
76
77 use Carp;
78
79 use Time::HiRes (); # currently only used for PerlIO::cede
80
81 our $DIEHOOK;
82 our $WARNHOOK;
83
84 BEGIN {
85 $DIEHOOK = sub { };
86 $WARNHOOK = sub { warn $_[0] };
87 }
88
89 sub diehook { &$DIEHOOK }
90 sub warnhook { &$WARNHOOK }
91
92 use XSLoader;
93
94 BEGIN {
95 our $VERSION = 5.0;
96
97 # must be done here because the xs part expects it to exist
98 # it might exist already because Coro::Specific created it.
99 $Coro::current ||= { };
100
101 {
102 # save/restore the handlers before/after overwriting %SIG magic
103 local $SIG{__DIE__};
104 local $SIG{__WARN__};
105
106 XSLoader::load __PACKAGE__, $VERSION;
107 }
108
109 # need to do it after overwriting the %SIG magic
110 $SIG{__DIE__} ||= \&diehook;
111 $SIG{__WARN__} ||= \&warnhook;
112 }
113
114 use Exporter;
115 use base Exporter::;
116
117 =head2 GLOBAL VARIABLES
118
119 =over 4
120
121 =item $Coro::State::DIEHOOK
122
123 This works similarly to C<$SIG{__DIE__}> and is used as the default die
124 hook for newly created coroutines. This is useful if you want some generic
125 logging function that works for all coroutines that don't set their own
126 hook.
127
128 When Coro::State is first loaded it will install these handlers for the
129 main program, too, unless they have been overwritten already.
130
131 The default handlers provided will behave like the built-in ones (as if
132 they weren't there).
133
134 Note 1: You I<must> store a valid code reference in these variables,
135 C<undef> will I<not> do.
136
137 Note 2: The value of this variable will be shared among all coroutines, so
138 changing its value will change it in all coroutines that don't have their
139 own die handler.
140
141 =item $Coro::State::WARNHOOK
142
143 Similar to above die hook, but augments C<$SIG{__WARN__}>.
144
145 =back
146
147 =head2 FUNCTIONS
148
149 =over 4
150
151 =item $coro = new Coro::State [$coderef[, @args...]]
152
153 Create a new coroutine and return it. The first C<transfer> call to this
154 coroutine will start execution at the given coderef.
155
156 If the subroutine returns the program will be terminated as if execution
157 of the main program ended.
158
159 If it throws an exception the program will terminate unless the exception
160 is caught, exactly like in the main program.
161
162 Calling C<exit> in a coroutine does the same as calling it in the main
163 program.
164
165 If the coderef is omitted this function will create a new "empty"
166 coroutine, i.e. a coroutine that cannot be transfered to but can be used
167 to save the current coroutine state in (note that this is dangerous, as no
168 reference is taken to ensure that the "current coroutine state" survives,
169 the caller is responsible to ensure that the cloned state does not go
170 away).
171
172 The returned object is an empty hash which can be used for any purpose
173 whatsoever, for example when subclassing Coro::State.
174
175 Certain variables are "localised" to each coroutine, that is, certain
176 "global" variables are actually per coroutine. Not everything that would
177 sensibly be localised currently is, and not everything that is localised
178 makes sense for every application, and the future might bring changes.
179
180 The following global variables can have different values per coroutine,
181 and have the stated initial values:
182
183 Variable Initial Value
184 @_ whatever arguments were passed to the Coro
185 $_ undef
186 $@ undef
187 $/ "\n"
188 $SIG{__DIE__} aliased to $Coro::State::DIEHOOK(*)
189 $SIG{__WARN__} aliased to $Coro::State::WARNHOOK(*)
190 (default fh) *STDOUT
191 $1, $2... all regex results are initially undefined
192
193 (*) reading the value from %SIG is not supported, but local'ising is.
194
195 If you feel that something important is missing then tell me. Also
196 remember that every function call that might call C<transfer> (such
197 as C<Coro::Channel::put>) might clobber any global and/or special
198 variables. Yes, this is by design ;) You can always create your own
199 process abstraction model that saves these variables.
200
201 The easiest way to do this is to create your own scheduling primitive like
202 in the code below, and use it in your coroutines:
203
204 sub my_cede {
205 local ($;, ...);
206 Coro::cede;
207 }
208
209 =cut
210
211 # this is called for each newly created C coroutine,
212 # and is being artificially injected into the opcode flow.
213 # its sole purpose is to call transfer() once so it knows
214 # the top level stack frame for stack sharing.
215 sub _cctx_init {
216 &_set_stacklevel;
217 }
218
219 =item $state->throw ([$scalar])
220
221 See L<< Coro->throw >>.
222
223 =item $state->call ($coderef)
224
225 Try to call the given C<$coderef> in the context of the given state. This
226 works even when the state is currently within an XS function, and can
227 be very dangerous. You can use it to acquire stack traces etc. (see the
228 Coro::Debug module for more details). The coderef MUST NOT EVER transfer
229 to another state.
230
231 =item $state->eval ($string)
232
233 Like C<call>, but eval's the string. Dangerous.
234
235 =item $state->swap_defsv
236
237 =item $state->swap_defav
238
239 Swap the current C<$_> (swap_defsv) or C<@_> (swap_defav) with the
240 equivalent in the saved state of C<$state>. This can be used to give the
241 coroutine a defined content for C<@_> and C<$_> before transfer'ing to it.
242
243 =item $state->trace ($flags)
244
245 Internal function to control tracing. I just mention this so you can stay
246 away from abusing it.
247
248 =item $prev->transfer ($next)
249
250 Save the state of the current subroutine in C<$prev> and switch to the
251 coroutine saved in C<$next>.
252
253 The "state" of a subroutine includes the scope, i.e. lexical variables and
254 the current execution state (subroutine, stack).
255
256 =item $bytes = $state->rss
257
258 Returns the memory allocated by the coroutine (which includes static
259 structures, various perl stacks but NOT local variables, arguments or any
260 C context data). This is a rough indication of how much memory it might
261 use.
262
263 =item $state->has_cctx
264
265 Returns whether the state currently uses a cctx/C context. An active
266 state always has a cctx, as well as the main program. Other states only
267 use a cctxts when needed.
268
269 =item Coro::State::force_cctx
270
271 Forces the allocation of a C context for the currently running coroutine
272 (if not already done). Apart from benchmarking there is little point
273 in doing so, however.
274
275 =item $ncctx = Coro::State::cctx_count
276
277 Returns the number of C-level coroutines allocated. If this number is
278 very high (more than a dozen) it might help to identify points of C-level
279 recursion in your code and moving this into a separate coroutine.
280
281 =item $nidle = Coro::State::cctx_idle
282
283 Returns the number of allocated but idle (free for reuse) C level
284 coroutines. Currently, Coro will limit the number of idle/unused cctxs to
285 8.
286
287 =item $old = Coro::State::cctx_stacksize [$new_stacksize]
288
289 Returns the current C stack size and optionally sets the new I<minimum>
290 stack size to C<$new_stacksize> I<long>s. Existing stacks will not
291 be changed, but Coro will try to replace smaller stacks as soon as
292 possible. Any Coro::State that starts to use a stack after this call is
293 guaranteed this minimum stack size.
294
295 Please note that Coroutines will only need to use a C-level stack if the
296 interpreter recurses or calls a function in a module that calls back into
297 the interpreter, so use of this feature is usually never needed.
298
299 =item $old = Coro::State::cctx_max_idle [$new_count]
300
301 Coro caches C contexts that are not in use currently, as creating them
302 from scratch has some overhead.
303
304 This function returns the current maximum number of idle C contexts and
305 optionally sets the new amount. The count must be at least C<1>, with the
306 default being C<4>.
307
308 =item @states = Coro::State::list
309
310 Returns a list of all states currently allocated.
311
312 =cut
313
314 # used by Coro::Debug only atm.
315 sub debug_desc {
316 $_[0]{desc}
317 }
318
319 1;
320
321 =back
322
323 =head1 BUGS
324
325 This module is not thread-safe. You must only ever use this module from
326 the same thread (this requirement might be removed in the future).
327
328 =head1 SEE ALSO
329
330 L<Coro>.
331
332 =head1 AUTHOR
333
334 Marc Lehmann <schmorp@schmorp.de>
335 http://home.schmorp.de/
336
337 =cut
338