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