1State(3) User Contributed Perl Documentation State(3)
2
6 Coro::State - first class continuations
7
9 use Coro::State;
10 $new = new Coro::State sub {
12 print "in coro (called with @_), switching back\n";
13 $new->transfer ($main);
14 print "in coro again, switching back\n";
15 $new->transfer ($main);
16 }, 5;
17 $main = new Coro::State;
19 print "in main, switching to coro\n";
21 $main->transfer ($new);
22 print "back in main, switch to coro again\n";
23 $main->transfer ($new);
24 print "back in main\n";
25
27 This module implements coro objects. Coros, similar to threads and
28 continuations, allow you to run more than one "thread of execution" in
29 parallel. Unlike so-called "kernel" threads, there is no parallelism
30 and only voluntary switching is used so locking problems are greatly
31 reduced. The latter is called "cooperative" threading as opposed to
32 "preemptive" threading.
33 This can be used to implement non-local jumps, exception handling,
35 continuation objects and more.
36 This module provides only low-level functionality useful to build other
38 abstractions, such as threads, generators or coroutines. See Coro and
39 related modules for a higher level threads abstraction including a
40 scheduler.
41 MODEL
43 Coro::State implements two different thread models: Perl and C. The C
44 threads (called cctx's) are basically simplified perl interpreters
45 running/interpreting the Perl threads. A single interpreter can run any
46 number of Perl threads, so usually there are very few C threads.
47 When Perl code calls a C function (e.g. in an extension module) and
49 that C function then calls back into Perl or transfers control to
50 another thread, the C thread can no longer execute other Perl threads,
51 so it stays tied to the specific thread until it returns to the
52 original Perl caller, after which it is again available to run other
53 Perl threads.
54 The main program always has its own "C thread" (which really is *the*
56 Perl interpreter running the whole program), so there will always be at
57 least one additional C thread. You can use the debugger (see
58 Coro::Debug) to find out which threads are tied to their cctx and which
59 aren't.
60 MEMORY CONSUMPTION
62 A newly created Coro::State that has not been used only allocates a
63 relatively small (a hundred bytes) structure. Only on the first
64 "transfer" will perl allocate stacks (a few kb, 64 bit architectures
65 use twice as much, i.e. a few kb :) and optionally a C stack/thread
66 (cctx) for threads that recurse through C functions. All this is very
67 system-dependent. On my x86-pc-linux-gnu system this amounts to about
68 2k per (non-trivial but simple) Coro::State.
69 You can view the actual memory consumption using Coro::Debug. Keep in
71 mind that a for loop or other block constructs can easily consume
72 100-200 bytes per nesting level.
73 GLOBAL VARIABLES
75 $Coro::State::DIEHOOK
76 This works similarly to $SIG{__DIE__} and is used as the default
77 die hook for newly created Coro::States. This is useful if you want
78 some generic logging function that works for all threads that don't
79 set their own hook.
80 When Coro::State is first loaded it will install these handlers for
82 the main program, too, unless they have been overwritten already.
83 The default handlers provided will behave like the built-in ones
85 (as if they weren't there).
86 If you don't want to exit your program on uncaught exceptions, you
88 must not return from your die hook - call "Coro::terminate"
89 instead.
90 Note 1: You must store a valid code reference in these variables,
92 "undef" will not do.
93 Note 2: The value of this variable will be shared among all
95 threads, so changing its value will change it in all threads that
96 don't have their own die handler.
97 $Coro::State::WARNHOOK
99 Similar to above die hook, but augments $SIG{__WARN__}.
100 Coro::State METHODS
102 $coro = new Coro::State [$coderef[, @args...]]
103 Create a new Coro::State thread object and return it. The first
104 "transfer" call to this thread will start execution at the given
105 coderef, with the given arguments.
106 Note that the arguments will not be copied. Instead, as with normal
108 function calls, the thread receives passed arguments by reference,
109 so make sure you don't change them in unexpected ways.
110 Returning from such a thread is NOT supported. Neither is calling
112 "exit" or throwing an uncaught exception. The following paragraphs
113 describe what happens in current versions of Coro.
114 If the subroutine returns the program will be terminated as if
116 execution of the main program ended.
117 If it throws an exception the program will terminate unless the
119 exception is caught, exactly like in the main program.
120 Calling "exit" in a thread does the same as calling it in the main
122 program, but due to libc bugs on many BSDs, this doesn't work
123 reliable everywhere.
124 If the coderef is omitted this function will create a new "empty"
126 thread, i.e. a thread that cannot be transferred to but can be used
127 to save the current thread state in (note that this is dangerous,
128 as no reference is taken to ensure that the "current thread state"
129 survives, the caller is responsible to ensure that the cloned state
130 does not go away).
131 The returned object is an empty hash which can be used for any
133 purpose whatsoever, for example when subclassing Coro::State.
134 Certain variables are "localised" to each thread, that is, certain
136 "global" variables are actually per thread. Not everything that
137 would sensibly be localised currently is, and not everything that
138 is localised makes sense for every application, and the future
139 might bring changes.
140 The following global variables can have different values per
142 thread, and have the stated initial values:
143 Variable Initial Value
145 @_ whatever arguments were passed to the Coro
146 $_ undef
147 $@ undef
148 $/ "\n"
149 $SIG{__DIE__} aliased to $Coro::State::DIEHOOK(*)
150 $SIG{__WARN__} aliased to $Coro::State::WARNHOOK(*)
151 (default fh) *STDOUT
152 $^H, %^H zero/empty.
153 $1, $2... all regex results are initially undefined
154 (*) reading the value from %SIG is not supported, but local'ising is.
156 If you feel that something important is missing then tell me. Also
158 remember that every function call that might call "transfer" (such
159 as "Coro::Channel::put") might clobber any global and/or special
160 variables. Yes, this is by design ;) You can always create your own
161 process abstraction model that saves these variables.
162 The easiest way to do this is to create your own scheduling
164 primitive like in the code below, and use it in your threads:
165 sub my_cede {
167 local ($;, ...);
168 Coro::cede;
169 }
170 Another way is to use dynamic winders, see "Coro::on_enter" and
172 "Coro::on_leave" for this.
173 Yet another way that works only for variables is "->swap_sv".
175 $prev->transfer ($next)
177 Save the state of the current subroutine in $prev and switch to the
178 thread saved in $next.
179 The "state" of a subroutine includes the scope, i.e. lexical
181 variables and the current execution state (subroutine, stack).
182 $state->throw ([$scalar])
184 $state->is_new
185 $state->is_zombie
186 See the corresponding method(s) for Coro objects.
187 $state->cancel
189 Forcefully destructs the given Coro::State. While you can keep the
190 reference, and some memory is still allocated, the Coro::State
191 object is effectively dead, destructors have been freed, it cannot
192 be transferred to anymore, it's pushing up the daisies.
193 $state->call ($coderef)
195 Try to call the given $coderef in the context of the given state.
196 This works even when the state is currently within an XS function,
197 and can be very dangerous. You can use it to acquire stack traces
198 etc. (see the Coro::Debug module for more details). The coderef
199 MUST NOT EVER transfer to another state.
200 $state->eval ($string)
202 Like "call", but eval's the string. Dangerous.
203 $state->swap_defsv
205 $state->swap_defav
206 Swap the current $_ (swap_defsv) or @_ (swap_defav) with the
207 equivalent in the saved state of $state. This can be used to give
208 the coro a defined content for @_ and $_ before transfer'ing to it.
209 $state->swap_sv (\$sv, \$swap_sv)
211 This (very advanced) function can be used to make any variable
212 local to a thread.
213 It works by swapping the contents of $sv and $swap_sv each time the
215 thread is entered and left again, i.e. it is similar to:
216 $tmp = $sv; $sv = $swap_sv; $swap_sv = $tmp;
218 Except that it doesn't make an copies and works on hashes and even
220 more exotic values (code references!).
221 When called on the current thread (i.e. from within the thread that
223 will receive the swap_sv), then this method acts as if it was
224 called from another thread, i.e. after adding the two SV's to the
225 threads swap list their values will be swapped.
226 Needless to say, this function can be very very dangerous: you can
228 easily swap a hash with a reference (i.e. %hash becomes a
229 reference), and perl will not like this at all.
230 It will also swap "magicalness" - so when swapping a builtin perl
232 variable (such as $.), it will lose its magicalness, which, again,
233 perl will not like, so don't do it.
234 Lastly, the $swap_sv itself will be used, not a copy, so make sure
236 you give each thread its own $swap_sv instance.
237 It is, however, quite safe to swap some normal variable with
239 another. For example, PApp::SQL stores the default database handle
240 in $PApp::SQL::DBH. To make this a per-thread variable, use this:
241 my $private_dbh = ...;
243 $coro->swap_sv (\$PApp::SQL::DBH, \$private_dbh);
244 This results in $PApp::SQL::DBH having the value of $private_dbh
246 while it executes, and whatever other value it had when it doesn't
247 execute.
248 You can also swap hashes and other values:
250 my %private_hash;
252 $coro->swap_sv (\%some_hash, \%private_hash);
253 To undo an earlier "swap_sv" call you must call "swap_sv" with
255 exactly the same two variables in the same order (the references
256 can be different, it's the variables that they point to that
257 count). For example, the following sequence will remove the swap of
258 $x and $y, while keeping the swap of $x and $z:
259 $coro->swap_sv (\$x, \$y);
261 $coro->swap_sv (\$x, \$z);
262 $coro->swap_sv (\$x, \$y);
263 $bytes = $state->rss
265 Returns the memory allocated by the coro (which includes static
266 structures, various perl stacks but NOT local variables, arguments
267 or any C context data). This is a rough indication of how much
268 memory it might use.
269 ($real, $cpu) = $state->times
271 Returns the real time and cpu times spent in the given $state. See
272 "Coro::State::enable_times" for more info.
273 $state->trace ($flags)
275 Internal function to control tracing. I just mention this so you
276 can stay away from abusing it.
277 METHODS FOR C CONTEXTS
279 Most coros only consist of some Perl data structures - transferring to
281 a coro just reconfigures the interpreter to continue somewhere else.
282 However. this is not always possible: For example, when Perl calls a
284 C/XS function (such as an event loop), and C then invokes a Perl
285 callback, reconfiguring the interpreter is not enough. Coro::State
286 detects these cases automatically, and attaches a C-level thread to
287 each such Coro::State object, for as long as necessary.
288 The C-level thread structure is called "C context" (or cctxt for
290 short), and can be quite big, which is why Coro::State only creates
291 them as needed and can run many Coro::State's on a single cctxt.
292 This is mostly transparent, so the following methods are rarely needed.
294 $state->has_cctx
296 Returns whether the state currently uses a cctx/C context. An
297 active state always has a cctx, as well as the main program. Other
298 states only use a cctxts when needed.
299 Coro::State::force_cctx
301 Forces the allocation of a private cctxt for the currently
302 executing Coro::State even though it would not normally ned one.
303 Apart from benchmarking or testing Coro itself, there is little
304 point in doing so, however.
305 $ncctx = Coro::State::cctx_count
307 Returns the number of C contexts allocated. If this number is very
308 high (more than a dozen) it might be beneficial to identify points
309 of C-level recursion (Perl calls C/XS, which calls Perl again which
310 switches coros - this forces an allocation of a C context) in your
311 code and moving this into a separate coro.
312 $nidle = Coro::State::cctx_idle
314 Returns the number of allocated but idle (currently unused and free
315 for reuse) C contexts.
316 $old = Coro::State::cctx_max_idle [$new_count]
318 Coro caches C contexts that are not in use currently, as creating
319 them from scratch has some overhead.
320 This function returns the current maximum number of idle C contexts
322 and optionally sets the new amount. The count must be at least 1,
323 with the default being 4.
324 $old = Coro::State::cctx_stacksize [$new_stacksize]
326 Returns the current C stack size and optionally sets the new
327 minimum stack size to $new_stacksize (in units of pointer sizes,
328 i.e. typically 4 on 32 bit and 8 on 64 bit hosts). Existing stacks
329 will not be changed, but Coro will try to replace smaller stacks as
330 soon as possible. Any Coro::State that starts to use a stack after
331 this call is guaranteed this minimum stack size.
332 Please note that coros will only need to use a C-level stack if the
334 interpreter recurses or calls a function in a module that calls
335 back into the interpreter, so use of this feature is usually never
336 needed.
337 FUNCTIONS
339 @states = Coro::State::list
340 Returns a list of all Coro::State objects currently allocated. This
341 includes all derived objects (such as Coro threads).
342 $was_enabled = Coro::State::enable_times [$enable]
344 Enables/disables/queries the current state of per-thread real and
345 cpu-time gathering.
346 When enabled, the real time and the cpu time (user + system time)
348 spent in each thread is accumulated. If disabled, then the
349 accumulated times will stay as they are (they start at 0).
350 Currently, cpu time is only measured on GNU/Linux systems, all
352 other systems only gather real time.
353 Enabling time profiling slows down thread switching by a factor of
355 2 to 10, depending on platform on hardware.
356 The times will be displayed when running "Coro::Debug::command
358 "ps"", and can be queried by calling "$state->times".
359 CLONING
361 $clone = $state->clone
363 This exciting method takes a Coro::State object and clones it,
364 i.e., it creates a copy. This makes it possible to restore a state
365 more than once, and even return to states that have returned or
366 have been terminated.
367 Since its only known purpose is for intellectual self-
369 gratification, and because it is a difficult piece of code, it is
370 not enabled by default, and not supported.
371 Here are a few little-known facts: First, coros *are*
373 full/true/real continuations. Secondly Coro::State objects (without
374 clone) *are* first class continuations. Thirdly, nobody has ever
375 found a use for the full power of call/cc that isn't better
376 (faster, easier, more efficiently) implemented differently, and
377 nobody has yet found a useful control construct that can't be
378 implemented without it already, just much faster and with fewer
379 resources. And lastly, Scheme's call/cc doesn't support using
380 call/cc to implement threads.
381 Among the games you can play with this is implementing a scheme-
383 like call-with-current-continuation, as the following code does
384 (well, with small differences).
385 # perl disassociates from local lexicals on frame exit,
387 # so use a global variable for return values.
388 my @ret;
389 sub callcc($@) {
391 my ($func, @arg) = @_;
392 my $continuation = new Coro::State;
394 $continuation->transfer (new Coro::State sub {
395 my $escape = sub {
396 @ret = @_;
397 Coro::State->new->transfer ($continuation->clone);
398 };
399 $escape->($func->($escape, @arg));
400 });
401 my @ret_ = @ret; @ret = ();
403 wantarray ? @ret_ : pop @ret_
404 }
405 Which could be used to implement a loop like this:
407 async {
409 my $n;
410 my $l = callcc sub { $_[0] };
411 $n++;
413 print "iteration $n\n";
414 $l->($l) unless $n == 10;
416 };
417 If you find this confusing, then you already understand the
419 coolness of call/cc: It can turn anything into spaghetti code real
420 fast.
421 Besides, call/cc is much less useful in a Perl-like dynamic
423 language (with references, and its scoping rules) then in, say,
424 scheme.
425 Now, the known limitations of "clone":
427 It probably only works on perl 5.10; it cannot clone a coro inside
429 the substition operator (but windows perl can't fork from there
430 either) and some other contexts, and "abort ()" is the preferred
431 mechanism to signal errors. It cannot clone a state that has a c
432 context attached (implementing clone on the C level is too hard for
433 me to even try), which rules out calling call/cc from the main
434 coro. It cannot clone a context that hasn't even been started yet.
435 It doesn't work with "-DDEBUGGING" (but what does). It probably
436 also leaks, and sometimes triggers a few assertions inside Coro.
437 Most of these limitations *are* fixable with some effort, but
438 that's pointless just to make a point that it could be done.
439 The current implementation could without doubt be optimised to be a
441 constant-time operation by doing lazy stack copying, if somebody
442 were insane enough to invest the time.
443
445 This module is not thread-safe. You must only ever use this module from
446 the same thread (this requirement might be removed in the future).
447
449 Coro.
450
452 Marc A. Lehmann <schmorp@schmorp.de>
453 http://software.schmorp.de/pkg/Coro.html
454perl v5.36.0 2023-01-20 State(3)