1State(3)              User Contributed Perl Documentation             State(3)
2
3
4

NAME

6       Coro::State - first class continuations
7

SYNOPSIS

9        use Coro::State;
10
11        $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
18        $main = new Coro::State;
19
20        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

DESCRIPTION

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
34       This can be used to implement non-local jumps, exception handling,
35       continuation objects and more.
36
37       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
42   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
48       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
55       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
61   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
70       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
74   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
81           When Coro::State is first loaded it will install these handlers for
82           the main program, too, unless they have been overwritten already.
83
84           The default handlers provided will behave like the built-in ones
85           (as if they weren't there).
86
87           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
91           Note 1: You must store a valid code reference in these variables,
92           "undef" will not do.
93
94           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
98       $Coro::State::WARNHOOK
99           Similar to above die hook, but augments $SIG{__WARN__}.
100
101   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
107           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
111           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
115           If the subroutine returns the program will be terminated as if
116           execution of the main program ended.
117
118           If it throws an exception the program will terminate unless the
119           exception is caught, exactly like in the main program.
120
121           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
125           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
132           The returned object is an empty hash which can be used for any
133           purpose whatsoever, for example when subclassing Coro::State.
134
135           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
141           The following global variables can have different values per
142           thread, and have the stated initial values:
143
144              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
155              (*) reading the value from %SIG is not supported, but local'ising is.
156
157           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
163           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
166             sub my_cede {
167                local ($;, ...);
168                Coro::cede;
169             }
170
171           Another way is to use dynamic winders, see "Coro::on_enter" and
172           "Coro::on_leave" for this.
173
174           Yet another way that works only for variables is "->swap_sv".
175
176       $prev->transfer ($next)
177           Save the state of the current subroutine in $prev and switch to the
178           thread saved in $next.
179
180           The "state" of a subroutine includes the scope, i.e. lexical
181           variables and the current execution state (subroutine, stack).
182
183       $state->throw ([$scalar])
184       $state->is_new
185       $state->is_zombie
186           See the corresponding method(s) for Coro objects.
187
188       $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
194       $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
201       $state->eval ($string)
202           Like "call", but eval's the string. Dangerous.
203
204       $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
210       $state->swap_sv (\$sv, \$swap_sv)
211           This (very advanced) function can be used to make any variable
212           local to a thread.
213
214           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
217              $tmp = $sv; $sv = $swap_sv; $swap_sv = $tmp;
218
219           Except that it doesn't make an copies and works on hashes and even
220           more exotic values (code references!).
221
222           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
227           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
231           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
235           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
238           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
242              my $private_dbh = ...;
243              $coro->swap_sv (\$PApp::SQL::DBH, \$private_dbh);
244
245           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
249           You can also swap hashes and other values:
250
251              my %private_hash;
252              $coro->swap_sv (\%some_hash, \%private_hash);
253
254           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
260              $coro->swap_sv (\$x, \$y);
261              $coro->swap_sv (\$x, \$z);
262              $coro->swap_sv (\$x, \$y);
263
264       $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
270       ($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
274       $state->trace ($flags)
275           Internal function to control tracing. I just mention this so you
276           can stay away from abusing it.
277
278       METHODS FOR C CONTEXTS
279
280       Most coros only consist of some Perl data structures - transferring to
281       a coro just reconfigures the interpreter to continue somewhere else.
282
283       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
289       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
293       This is mostly transparent, so the following methods are rarely needed.
294
295       $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
300       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
306       $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
313       $nidle = Coro::State::cctx_idle
314           Returns the number of allocated but idle (currently unused and free
315           for reuse) C contexts.
316
317       $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
321           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
325       $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
333           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
338   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
343       $was_enabled = Coro::State::enable_times [$enable]
344           Enables/disables/queries the current state of per-thread real and
345           cpu-time gathering.
346
347           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
351           Currently, cpu time is only measured on GNU/Linux systems, all
352           other systems only gather real time.
353
354           Enabling time profiling slows down thread switching by a factor of
355           2 to 10, depending on platform on hardware.
356
357           The times will be displayed when running "Coro::Debug::command
358           "ps"", and can be queried by calling "$state->times".
359
360       CLONING
361
362       $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
368           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
372           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
382           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
386              # perl disassociates from local lexicals on frame exit,
387              # so use a global variable for return values.
388              my @ret;
389
390              sub callcc($@) {
391                 my ($func, @arg) = @_;
392
393                 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
402                 my @ret_ = @ret; @ret = ();
403                 wantarray ? @ret_ : pop @ret_
404              }
405
406           Which could be used to implement a loop like this:
407
408              async {
409                 my $n;
410                 my $l = callcc sub { $_[0] };
411
412                 $n++;
413                 print "iteration $n\n";
414
415                 $l->($l) unless $n == 10;
416              };
417
418           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
422           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
426           Now, the known limitations of "clone":
427
428           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
440           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

BUGS

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

SEE ALSO

449       Coro.
450

AUTHOR/SUPPORT/CONTACT

452          Marc A. Lehmann <schmorp@schmorp.de>
453          http://software.schmorp.de/pkg/Coro.html
454
455
456
457perl v5.34.0                      2021-07-22                          State(3)
Impressum