File Coverage

blib/lib/Coro/State.pm
Criterion Covered Total %
statement 24 26 92.3
branch n/a
condition 4 6 66.6
subroutine 9 10 90.0
pod 0 3 0.0
total 37 45 82.2


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             Coro::State - first class continuations
4              
5             =head1 SYNOPSIS
6              
7             use Coro::State;
8              
9             $new = new Coro::State sub {
10             print "in coro (called with @_), switching back\n";
11             $new->transfer ($main);
12             print "in coro again, switching back\n";
13             $new->transfer ($main);
14             }, 5;
15              
16             $main = new Coro::State;
17              
18             print "in main, switching to coro\n";
19             $main->transfer ($new);
20             print "back in main, switch to coro again\n";
21             $main->transfer ($new);
22             print "back in main\n";
23              
24             =head1 DESCRIPTION
25              
26             This module implements coro objects. Coros, similar to threads and
27             continuations, allow you to run more than one "thread of execution" in
28             parallel. Unlike so-called "kernel" threads, there is no parallelism
29             and only voluntary switching is used so locking problems are greatly
30             reduced. The latter is called "cooperative" threading as opposed to
31             "preemptive" threading.
32              
33             This can be used to implement non-local jumps, exception handling,
34             continuation objects and more.
35              
36             This module provides only low-level functionality useful to build other
37             abstractions, such as threads, generators or coroutines. See L
38             and related modules for a higher level threads abstraction including a
39             scheduler.
40              
41             =head2 MODEL
42              
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              
48             When Perl code calls a C function (e.g. in an extension module) and that C
49             function then calls back into Perl or transfers control to another thread,
50             the C thread can no longer execute other Perl threads, so it stays tied to
51             the specific thread until it returns to the original Perl caller, after
52             which it is again available to run other Perl threads.
53              
54             The main program always has its own "C thread" (which really is
55             *the* Perl interpreter running the whole program), so there will always
56             be at least one additional C thread. You can use the debugger (see
57             L) to find out which threads are tied to their cctx and
58             which aren't.
59              
60             =head2 MEMORY CONSUMPTION
61              
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             C 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 2k
68             per (non-trivial but simple) Coro::State.
69              
70             You can view the actual memory consumption using Coro::Debug. Keep in mind
71             that a for loop or other block constructs can easily consume 100-200 bytes
72             per nesting level.
73              
74             =cut
75              
76             package Coro::State;
77              
78 21     21   2050 use common::sense;
  21         65  
  21         100  
79              
80 21     21   990 use Carp;
  21         37  
  21         3044  
81              
82             our $DIEHOOK;
83             our $WARNHOOK;
84              
85             BEGIN {
86 21     21   123 $DIEHOOK = sub { };
87 21         1503 $WARNHOOK = sub { warn $_[0] };
  0         0  
88             }
89              
90 7     7 0 1274 sub diehook { &$DIEHOOK }
91 2     2 0 46 sub warnhook { &$WARNHOOK }
92              
93 21     21   124 use XSLoader;
  21         42  
  21         2140  
94              
95             BEGIN {
96 21     21   67 our $VERSION = 6.514;
97              
98             # must be done here because the xs part expects it to exist
99             # it might exist already because Coro::Specific created it.
100 21   100     137 $Coro::current ||= { };
101              
102 21         16875 XSLoader::load __PACKAGE__, $VERSION;
103              
104             # major complication:
105             # perl stores a PVMG with sigelem magic in warnhook, and retrieves the
106             # value from the hash, even while PL_warnhook is zero.
107             # Coro can't do that because the value in the hash might be stale.
108             # Therefore, Coro stores a copy, and returns PL_warnhook itself, so we
109             # need to manually copy the existing handlers to remove their magic.
110             # I chose to use "delete", to hopefuly get rid of the remnants,
111             # but (my $v = $SIG{...}) would also work.
112 21   50     2523 $SIG{__DIE__} = (delete $SIG{__DIE__} ) || \&diehook;
113 21   50     731 $SIG{__WARN__} = (delete $SIG{__WARN__}) || \&warnhook;
114             }
115              
116 21     21   137 use Exporter;
  21         39  
  21         744  
117 21     21   102 use base Exporter::;
  21         41  
  21         7453  
118              
119             =head2 GLOBAL VARIABLES
120              
121             =over 4
122              
123             =item $Coro::State::DIEHOOK
124              
125             This works similarly to C<$SIG{__DIE__}> and is used as the default die
126             hook for newly created Coro::States. This is useful if you want some generic
127             logging function that works for all threads that don't set their own
128             hook.
129              
130             When Coro::State is first loaded it will install these handlers for the
131             main program, too, unless they have been overwritten already.
132              
133             The default handlers provided will behave like the built-in ones (as if
134             they weren't there).
135              
136             If you don't want to exit your program on uncaught exceptions, you must
137             not return from your die hook - call C instead.
138              
139             Note 1: You I store a valid code reference in these variables,
140             C will I do.
141              
142             Note 2: The value of this variable will be shared among all threads, so
143             changing its value will change it in all threads that don't have their
144             own die handler.
145              
146             =item $Coro::State::WARNHOOK
147              
148             Similar to above die hook, but augments C<$SIG{__WARN__}>.
149              
150             =back
151              
152             =head2 Coro::State METHODS
153              
154             =over 4
155              
156             =item $coro = new Coro::State [$coderef[, @args...]]
157              
158             Create a new Coro::State thread object and return it. The first
159             C call to this thread will start execution at the given
160             coderef, with the given arguments.
161              
162             Note that the arguments will not be copied. Instead, as with normal
163             function calls, the thread receives passed arguments by reference, so
164             make sure you don't change them in unexpected ways.
165              
166             Returning from such a thread is I supported. Neither is calling
167             C or throwing an uncaught exception. The following paragraphs
168             describe what happens in current versions of Coro.
169              
170             If the subroutine returns the program will be terminated as if execution
171             of the main program ended.
172              
173             If it throws an exception the program will terminate unless the exception
174             is caught, exactly like in the main program.
175              
176             Calling C in a thread does the same as calling it in the main
177             program, but due to libc bugs on many BSDs, this doesn't work reliable
178             everywhere.
179              
180             If the coderef is omitted this function will create a new "empty"
181             thread, i.e. a thread that cannot be transferred to but can be used
182             to save the current thread state in (note that this is dangerous, as no
183             reference is taken to ensure that the "current thread state" survives,
184             the caller is responsible to ensure that the cloned state does not go
185             away).
186              
187             The returned object is an empty hash which can be used for any purpose
188             whatsoever, for example when subclassing Coro::State.
189              
190             Certain variables are "localised" to each thread, that is, certain
191             "global" variables are actually per thread. Not everything that would
192             sensibly be localised currently is, and not everything that is localised
193             makes sense for every application, and the future might bring changes.
194              
195             The following global variables can have different values per thread,
196             and have the stated initial values:
197              
198             Variable Initial Value
199             @_ whatever arguments were passed to the Coro
200             $_ undef
201             $@ undef
202             $/ "\n"
203             $SIG{__DIE__} aliased to $Coro::State::DIEHOOK(*)
204             $SIG{__WARN__} aliased to $Coro::State::WARNHOOK(*)
205             (default fh) *STDOUT
206             $^H, %^H zero/empty.
207             $1, $2... all regex results are initially undefined
208              
209             (*) reading the value from %SIG is not supported, but local'ising is.
210              
211             If you feel that something important is missing then tell me. Also
212             remember that every function call that might call C (such
213             as C) might clobber any global and/or special
214             variables. Yes, this is by design ;) You can always create your own
215             process abstraction model that saves these variables.
216              
217             The easiest way to do this is to create your own scheduling primitive like
218             in the code below, and use it in your threads:
219              
220             sub my_cede {
221             local ($;, ...);
222             Coro::cede;
223             }
224              
225             Another way is to use dynamic winders, see C and
226             C for this.
227              
228             Yet another way that works only for variables is C<< ->swap_sv >>.
229              
230             =item $prev->transfer ($next)
231              
232             Save the state of the current subroutine in C<$prev> and switch to the
233             thread saved in C<$next>.
234              
235             The "state" of a subroutine includes the scope, i.e. lexical variables and
236             the current execution state (subroutine, stack).
237              
238             =item $state->throw ([$scalar])
239              
240             =item $state->is_new
241              
242             =item $state->is_zombie
243              
244             See the corresponding method(s) for L objects.
245              
246             =item $state->cancel
247              
248             Forcefully destructs the given Coro::State. While you can keep the
249             reference, and some memory is still allocated, the Coro::State object is
250             effectively dead, destructors have been freed, it cannot be transferred to
251             anymore, it's pushing up the daisies.
252              
253             =item $state->call ($coderef)
254              
255             Try to call the given C<$coderef> in the context of the given state. This
256             works even when the state is currently within an XS function, and can
257             be very dangerous. You can use it to acquire stack traces etc. (see the
258             Coro::Debug module for more details). The coderef MUST NOT EVER transfer
259             to another state.
260              
261             =item $state->eval ($string)
262              
263             Like C, but eval's the string. Dangerous.
264              
265             =item $state->swap_defsv
266              
267             =item $state->swap_defav
268              
269             Swap the current C<$_> (swap_defsv) or C<@_> (swap_defav) with the
270             equivalent in the saved state of C<$state>. This can be used to give the
271             coro a defined content for C<@_> and C<$_> before transfer'ing to it.
272              
273             =item $state->swap_sv (\$sv, \$swap_sv)
274              
275             This (very advanced) function can be used to make I variable local to
276             a thread.
277              
278             It works by swapping the contents of C<$sv> and C<$swap_sv> each time the
279             thread is entered and left again, i.e. it is similar to:
280              
281             $tmp = $sv; $sv = $swap_sv; $swap_sv = $tmp;
282              
283             Except that it doesn't make an copies and works on hashes and even more
284             exotic values (code references!).
285              
286             When called on the current thread (i.e. from within the thread that will
287             receive the swap_sv), then this method acts as if it was called from
288             another thread, i.e. after adding the two SV's to the threads swap list
289             their values will be swapped.
290              
291             Needless to say, this function can be very very dangerous: you can easily
292             swap a hash with a reference (i.e. C<%hash> I a reference), and perl
293             will not like this at all.
294              
295             It will also swap "magicalness" - so when swapping a builtin perl variable
296             (such as C<$.>), it will lose it's magicalness, which, again, perl will
297             not like, so don't do it.
298              
299             Lastly, the C<$swap_sv> itself will be used, not a copy, so make sure you
300             give each thread it's own C<$swap_sv> instance.
301              
302             It is, however, quite safe to swap some normal variable with
303             another. For example, L stores the default database handle in
304             C<$PApp::SQL::DBH>. To make this a per-thread variable, use this:
305              
306             my $private_dbh = ...;
307             $coro->swap_sv (\$PApp::SQL::DBH, \$private_dbh);
308              
309             This results in C<$PApp::SQL::DBH> having the value of C<$private_dbh>
310             while it executes, and whatever other value it had when it doesn't
311             execute.
312              
313             You can also swap hashes and other values:
314              
315             my %private_hash;
316             $coro->swap_sv (\%some_hash, \%private_hash);
317              
318             To undo an earlier C call you must call C with exactly
319             the same two variables in the same order (the references can be different,
320             it's the variables that they point to that count). For example, the
321             following sequence will remove the swap of C<$x> and C<$y>, while keeping
322             the swap of C<$x> and C<$z>:
323              
324             $coro->swap_sv (\$x, \$y);
325             $coro->swap_sv (\$x, \$z);
326             $coro->swap_sv (\$x, \$y);
327              
328             =item $bytes = $state->rss
329              
330             Returns the memory allocated by the coro (which includes static
331             structures, various perl stacks but NOT local variables, arguments or any
332             C context data). This is a rough indication of how much memory it might
333             use.
334              
335             =item ($real, $cpu) = $state->times
336              
337             Returns the real time and cpu times spent in the given C<$state>. See
338             C for more info.
339              
340             =item $state->trace ($flags)
341              
342             Internal function to control tracing. I just mention this so you can stay
343             away from abusing it.
344              
345             =back
346              
347             =head3 METHODS FOR C CONTEXTS
348              
349             Most coros only consist of some Perl data structures - transferring to a
350             coro just reconfigures the interpreter to continue somewhere else.
351              
352             However. this is not always possible: For example, when Perl calls a C/XS function
353             (such as an event loop), and C then invokes a Perl callback, reconfiguring
354             the interpreter is not enough. Coro::State detects these cases automatically, and
355             attaches a C-level thread to each such Coro::State object, for as long as necessary.
356              
357             The C-level thread structure is called "C context" (or cctxt for short),
358             and can be quite big, which is why Coro::State only creates them as needed
359             and can run many Coro::State's on a single cctxt.
360              
361             This is mostly transparent, so the following methods are rarely needed.
362              
363             =over 4
364              
365             =item $state->has_cctx
366              
367             Returns whether the state currently uses a cctx/C context. An active
368             state always has a cctx, as well as the main program. Other states only
369             use a cctxts when needed.
370              
371             =item Coro::State::force_cctx
372              
373             Forces the allocation of a private cctxt for the currently executing
374             Coro::State even though it would not normally ned one. Apart from
375             benchmarking or testing Coro itself, there is little point in doing so,
376             however.
377              
378             =item $ncctx = Coro::State::cctx_count
379              
380             Returns the number of C contexts allocated. If this number is very high
381             (more than a dozen) it might be beneficial to identify points of C-level
382             recursion (Perl calls C/XS, which calls Perl again which switches coros
383             - this forces an allocation of a C context) in your code and moving this
384             into a separate coro.
385              
386             =item $nidle = Coro::State::cctx_idle
387              
388             Returns the number of allocated but idle (currently unused and free for
389             reuse) C contexts.
390              
391             =item $old = Coro::State::cctx_max_idle [$new_count]
392              
393             Coro caches C contexts that are not in use currently, as creating them
394             from scratch has some overhead.
395              
396             This function returns the current maximum number of idle C contexts and
397             optionally sets the new amount. The count must be at least C<1>, with the
398             default being C<4>.
399              
400             =item $old = Coro::State::cctx_stacksize [$new_stacksize]
401              
402             Returns the current C stack size and optionally sets the new I
403             stack size to C<$new_stacksize> (in units of pointer sizes, i.e. typically
404             4 on 32 bit and 8 on 64 bit hosts). Existing stacks will not be changed,
405             but Coro will try to replace smaller stacks as soon as possible. Any
406             Coro::State that starts to use a stack after this call is guaranteed this
407             minimum stack size.
408              
409             Please note that coros will only need to use a C-level stack if the
410             interpreter recurses or calls a function in a module that calls back into
411             the interpreter, so use of this feature is usually never needed.
412              
413             =back
414              
415             =head2 FUNCTIONS
416              
417             =over 4
418              
419             =item @states = Coro::State::list
420              
421             Returns a list of all Coro::State objects currently allocated. This
422             includes all derived objects (such as L threads).
423              
424             =item $was_enabled = Coro::State::enable_times [$enable]
425              
426             Enables/disables/queries the current state of per-thread real and
427             cpu-time gathering.
428              
429             When enabled, the real time and the cpu time (user + system time)
430             spent in each thread is accumulated. If disabled, then the accumulated
431             times will stay as they are (they start at 0).
432              
433             Currently, cpu time is only measured on GNU/Linux systems, all other
434             systems only gather real time.
435              
436             Enabling time profiling slows down thread switching by a factor of 2 to
437             10, depending on platform on hardware.
438              
439             The times will be displayed when running C, and
440             can be queried by calling C<< $state->times >>.
441              
442             =back
443              
444             =head3 CLONING
445              
446             =over 4
447              
448             =item $clone = $state->clone
449              
450             This exciting method takes a Coro::State object and clones it, i.e., it
451             creates a copy. This makes it possible to restore a state more than once,
452             and even return to states that have returned or have been terminated.
453              
454             Since its only known purpose is for intellectual self-gratification, and
455             because it is a difficult piece of code, it is not enabled by default, and
456             not supported.
457              
458             Here are a few little-known facts: First, coros *are* full/true/real
459             continuations. Secondly Coro::State objects (without clone) *are* first
460             class continuations. Thirdly, nobody has ever found a use for the full
461             power of call/cc that isn't better (faster, easier, more efficiently)
462             implemented differently, and nobody has yet found a useful control
463             construct that can't be implemented without it already, just much faster
464             and with fewer resources. And lastly, Scheme's call/cc doesn't support
465             using call/cc to implement threads.
466              
467             Among the games you can play with this is implementing a scheme-like
468             call-with-current-continuation, as the following code does (well, with
469             small differences).
470              
471             # perl disassociates from local lexicals on frame exit,
472             # so use a global variable for return values.
473             my @ret;
474              
475             sub callcc($@) {
476             my ($func, @arg) = @_;
477              
478             my $continuation = new Coro::State;
479             $continuation->transfer (new Coro::State sub {
480             my $escape = sub {
481             @ret = @_;
482             Coro::State->new->transfer ($continuation->clone);
483             };
484             $escape->($func->($escape, @arg));
485             });
486              
487             my @ret_ = @ret; @ret = ();
488             wantarray ? @ret_ : pop @ret_
489             }
490              
491             Which could be used to implement a loop like this:
492              
493             async {
494             my $n;
495             my $l = callcc sub { $_[0] };
496            
497             $n++;
498             print "iteration $n\n";
499              
500             $l->($l) unless $n == 10;
501             };
502              
503             If you find this confusing, then you already understand the coolness of
504             call/cc: It can turn anything into spaghetti code real fast.
505              
506             Besides, call/cc is much less useful in a Perl-like dynamic language (with
507             references, and its scoping rules) then in, say, scheme.
508              
509             Now, the known limitations of C:
510              
511             It probably only works on perl 5.10; it cannot clone a coro inside
512             the substition operator (but windows perl can't fork from there either)
513             and some other contexts, and C is the preferred mechanism to
514             signal errors. It cannot clone a state that has a c context attached
515             (implementing clone on the C level is too hard for me to even try),
516             which rules out calling call/cc from the main coro. It cannot
517             clone a context that hasn't even been started yet. It doesn't work with
518             C<-DDEBUGGING> (but what does). It probably also leaks, and sometimes
519             triggers a few assertions inside Coro. Most of these limitations *are*
520             fixable with some effort, but that's pointless just to make a point that
521             it could be done.
522              
523             The current implementation could without doubt be optimised to be a
524             constant-time operation by doing lazy stack copying, if somebody were
525             insane enough to invest the time.
526              
527             =cut
528              
529             # used by Coro::Debug only atm.
530             sub debug_desc {
531             $_[0]{desc}
532 0     0 0   }
533              
534             # for very deep reasons, we must initialise $Coro::main here.
535              
536             {
537             package Coro;
538              
539             our $main; # main coro
540             our $current; # current coro
541              
542             $main = Coro::new Coro::;
543              
544             $main->{desc} = "[main::]";
545              
546             # maybe some other module used Coro::Specific before...
547             $main->{_specific} = $current->{_specific}
548             if $current;
549              
550             _set_current $main;
551             }
552              
553             # we also make sure we have Coro::AnyEvent when AnyEvent is used,
554             # without loading or initialising AnyEvent
555             if (defined $AnyEvent::MODEL) {
556             require Coro::AnyEvent;
557             } else {
558             push @AnyEvent::post_detect, sub { require Coro::AnyEvent };
559             }
560              
561             1;
562              
563             =back
564              
565             =head1 BUGS
566              
567             This module is not thread-safe. You must only ever use this module from
568             the same thread (this requirement might be removed in the future).
569              
570             =head1 SEE ALSO
571              
572             L.
573              
574             =head1 AUTHOR/SUPPORT/CONTACT
575              
576             Marc A. Lehmann
577             http://software.schmorp.de/pkg/Coro.html
578              
579             =cut
580