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

NAME

6       Coro - the only real threads in perl
7

SYNOPSIS

9         use Coro;
10
11         async {
12            # some asynchronous thread of execution
13            print "2\n";
14            cede; # yield back to main
15            print "4\n";
16         };
17         print "1\n";
18         cede; # yield to coro
19         print "3\n";
20         cede; # and again
21
22         # use locking
23         my $lock = new Coro::Semaphore;
24         my $locked;
25
26         $lock->down;
27         $locked = 1;
28         $lock->up;
29

DESCRIPTION

31       For a tutorial-style introduction, please read the Coro::Intro manpage.
32       This manpage mainly contains reference information.
33
34       This module collection manages continuations in general, most often in
35       the form of cooperative threads (also called coros, or simply "coro" in
36       the documentation). They are similar to kernel threads but don't (in
37       general) run in parallel at the same time even on SMP machines. The
38       specific flavor of thread offered by this module also guarantees you
39       that it will not switch between threads unless necessary, at easily-
40       identified points in your program, so locking and parallel access are
41       rarely an issue, making thread programming much safer and easier than
42       using other thread models.
43
44       Unlike the so-called "Perl threads" (which are not actually real
45       threads but only the windows process emulation (see section of same
46       name for more details) ported to UNIX, and as such act as processes),
47       Coro provides a full shared address space, which makes communication
48       between threads very easy. And coro threads are fast, too: disabling
49       the Windows process emulation code in your perl and using Coro can
50       easily result in a two to four times speed increase for your programs.
51       A parallel matrix multiplication benchmark (very communication-
52       intensive) runs over 300 times faster on a single core than perls
53       pseudo-threads on a quad core using all four cores.
54
55       Coro achieves that by supporting multiple running interpreters that
56       share data, which is especially useful to code pseudo-parallel
57       processes and for event-based programming, such as multiple HTTP-GET
58       requests running concurrently. See Coro::AnyEvent to learn more on how
59       to integrate Coro into an event-based environment.
60
61       In this module, a thread is defined as "callchain + lexical variables +
62       some package variables + C stack), that is, a thread has its own
63       callchain, its own set of lexicals and its own set of perls most
64       important global variables (see Coro::State for more configuration and
65       background info).
66
67       See also the "SEE ALSO" section at the end of this document - the Coro
68       module family is quite large.
69

CORO THREAD LIFE CYCLE

71       During the long and exciting (or not) life of a coro thread, it goes
72       through a number of states:
73
74       1. Creation
75           The first thing in the life of a coro thread is its creation -
76           obviously. The typical way to create a thread is to call the "async
77           BLOCK" function:
78
79              async {
80                 # thread code goes here
81              };
82
83           You can also pass arguments, which are put in @_:
84
85              async {
86                 print $_[1]; # prints 2
87              } 1, 2, 3;
88
89           This creates a new coro thread and puts it into the ready queue,
90           meaning it will run as soon as the CPU is free for it.
91
92           "async" will return a Coro object - you can store this for future
93           reference or ignore it - a thread that is running, ready to run or
94           waiting for some event is alive on its own.
95
96           Another way to create a thread is to call the "new" constructor
97           with a code-reference:
98
99              new Coro sub {
100                 # thread code goes here
101              }, @optional_arguments;
102
103           This is quite similar to calling "async", but the important
104           difference is that the new thread is not put into the ready queue,
105           so the thread will not run until somebody puts it there. "async"
106           is, therefore, identical to this sequence:
107
108              my $coro = new Coro sub {
109                 # thread code goes here
110              };
111              $coro->ready;
112              return $coro;
113
114       2. Startup
115           When a new coro thread is created, only a copy of the code
116           reference and the arguments are stored, no extra memory for stacks
117           and so on is allocated, keeping the coro thread in a low-memory
118           state.
119
120           Only when it actually starts executing will all the resources be
121           finally allocated.
122
123           The optional arguments specified at coro creation are available in
124           @_, similar to function calls.
125
126       3. Running / Blocking
127           A lot can happen after the coro thread has started running. Quite
128           usually, it will not run to the end in one go (because you could
129           use a function instead), but it will give up the CPU regularly
130           because it waits for external events.
131
132           As long as a coro thread runs, its Coro object is available in the
133           global variable $Coro::current.
134
135           The low-level way to give up the CPU is to call the scheduler,
136           which selects a new coro thread to run:
137
138              Coro::schedule;
139
140           Since running threads are not in the ready queue, calling the
141           scheduler without doing anything else will block the coro thread
142           forever - you need to arrange either for the coro to put woken up
143           (readied) by some other event or some other thread, or you can put
144           it into the ready queue before scheduling:
145
146              # this is exactly what Coro::cede does
147              $Coro::current->ready;
148              Coro::schedule;
149
150           All the higher-level synchronisation methods (Coro::Semaphore,
151           Coro::rouse_*...) are actually implemented via "->ready" and
152           "Coro::schedule".
153
154           While the coro thread is running it also might get assigned a
155           C-level thread, or the C-level thread might be unassigned from it,
156           as the Coro runtime wishes. A C-level thread needs to be assigned
157           when your perl thread calls into some C-level function and that
158           function in turn calls perl and perl then wants to switch
159           coroutines. This happens most often when you run an event loop and
160           block in the callback, or when perl itself calls some function such
161           as "AUTOLOAD" or methods via the "tie" mechanism.
162
163       4. Termination
164           Many threads actually terminate after some time. There are a number
165           of ways to terminate a coro thread, the simplest is returning from
166           the top-level code reference:
167
168              async {
169                 # after returning from here, the coro thread is terminated
170              };
171
172              async {
173                 return if 0.5 <  rand; # terminate a little earlier, maybe
174                 print "got a chance to print this\n";
175                 # or here
176              };
177
178           Any values returned from the coroutine can be recovered using
179           "->join":
180
181              my $coro = async {
182                 "hello, world\n" # return a string
183              };
184
185              my $hello_world = $coro->join;
186
187              print $hello_world;
188
189           Another way to terminate is to call "Coro::terminate", which at any
190           subroutine call nesting level:
191
192              async {
193                 Coro::terminate "return value 1", "return value 2";
194              };
195
196           Yet another way is to "->cancel" (or "->safe_cancel") the coro
197           thread from another thread:
198
199              my $coro = async {
200                 exit 1;
201              };
202
203              $coro->cancel; # also accepts values for ->join to retrieve
204
205           Cancellation can be dangerous - it's a bit like calling "exit"
206           without actually exiting, and might leave C libraries and XS
207           modules in a weird state. Unlike other thread implementations,
208           however, Coro is exceptionally safe with regards to cancellation,
209           as perl will always be in a consistent state, and for those cases
210           where you want to do truly marvellous things with your coro while
211           it is being cancelled - that is, make sure all cleanup code is
212           executed from the thread being cancelled - there is even a
213           "->safe_cancel" method.
214
215           So, cancelling a thread that runs in an XS event loop might not be
216           the best idea, but any other combination that deals with perl only
217           (cancelling when a thread is in a "tie" method or an "AUTOLOAD" for
218           example) is safe.
219
220           Last not least, a coro thread object that isn't referenced is
221           "->cancel"'ed automatically - just like other objects in Perl. This
222           is not such a common case, however - a running thread is
223           referencedy by $Coro::current, a thread ready to run is referenced
224           by the ready queue, a thread waiting on a lock or semaphore is
225           referenced by being in some wait list and so on. But a thread that
226           isn't in any of those queues gets cancelled:
227
228              async {
229                 schedule; # cede to other coros, don't go into the ready queue
230              };
231
232              cede;
233              # now the async above is destroyed, as it is not referenced by anything.
234
235           A slightly embellished example might make it clearer:
236
237              async {
238                 my $guard = Guard::guard { print "destroyed\n" };
239                 schedule while 1;
240              };
241
242              cede;
243
244           Superficially one might not expect any output - since the "async"
245           implements an endless loop, the $guard will not be cleaned up.
246           However, since the thread object returned by "async" is not stored
247           anywhere, the thread is initially referenced because it is in the
248           ready queue, when it runs it is referenced by $Coro::current, but
249           when it calls "schedule", it gets "cancel"ed causing the guard
250           object to be destroyed (see the next section), and printing its
251           message.
252
253           If this seems a bit drastic, remember that this only happens when
254           nothing references the thread anymore, which means there is no way
255           to further execute it, ever. The only options at this point are
256           leaking the thread, or cleaning it up, which brings us to...
257
258       5. Cleanup
259           Threads will allocate various resources. Most but not all will be
260           returned when a thread terminates, during clean-up.
261
262           Cleanup is quite similar to throwing an uncaught exception: perl
263           will work its way up through all subroutine calls and blocks. On
264           its way, it will release all "my" variables, undo all "local"'s and
265           free any other resources truly local to the thread.
266
267           So, a common way to free resources is to keep them referenced only
268           by my variables:
269
270              async {
271                 my $big_cache = new Cache ...;
272              };
273
274           If there are no other references, then the $big_cache object will
275           be freed when the thread terminates, regardless of how it does so.
276
277           What it does "NOT" do is unlock any Coro::Semaphores or similar
278           resources, but that's where the "guard" methods come in handy:
279
280              my $sem = new Coro::Semaphore;
281
282              async {
283                 my $lock_guard = $sem->guard;
284                 # if we return, or die or get cancelled, here,
285                 # then the semaphore will be "up"ed.
286              };
287
288           The "Guard::guard" function comes in handy for any custom cleanup
289           you might want to do (but you cannot switch to other coroutines
290           from those code blocks):
291
292              async {
293                 my $window = new Gtk2::Window "toplevel";
294                 # The window will not be cleaned up automatically, even when $window
295                 # gets freed, so use a guard to ensure its destruction
296                 # in case of an error:
297                 my $window_guard = Guard::guard { $window->destroy };
298
299                 # we are safe here
300              };
301
302           Last not least, "local" can often be handy, too, e.g. when
303           temporarily replacing the coro thread description:
304
305              sub myfunction {
306                 local $Coro::current->{desc} = "inside myfunction(@_)";
307
308                 # if we return or die here, the description will be restored
309              }
310
311       6. Viva La Zombie Muerte
312           Even after a thread has terminated and cleaned up its resources,
313           the Coro object still is there and stores the return values of the
314           thread.
315
316           When there are no other references, it will simply be cleaned up
317           and freed.
318
319           If there areany references, the Coro object will stay around, and
320           you can call "->join" as many times as you wish to retrieve the
321           result values:
322
323              async {
324                 print "hi\n";
325                 1
326              };
327
328              # run the async above, and free everything before returning
329              # from Coro::cede:
330              Coro::cede;
331
332              {
333                 my $coro = async {
334                    print "hi\n";
335                    1
336                 };
337
338                 # run the async above, and clean up, but do not free the coro
339                 # object:
340                 Coro::cede;
341
342                 # optionally retrieve the result values
343                 my @results = $coro->join;
344
345                 # now $coro goes out of scope, and presumably gets freed
346              };
347

GLOBAL VARIABLES

349       $Coro::main
350           This variable stores the Coro object that represents the main
351           program. While you can "ready" it and do most other things you can
352           do to coro, it is mainly useful to compare again $Coro::current, to
353           see whether you are running in the main program or not.
354
355       $Coro::current
356           The Coro object representing the current coro (the last coro that
357           the Coro scheduler switched to). The initial value is $Coro::main
358           (of course).
359
360           This variable is strictly read-only. You can take copies of the
361           value stored in it and use it as any other Coro object, but you
362           must not otherwise modify the variable itself.
363
364       $Coro::idle
365           This variable is mainly useful to integrate Coro into event loops.
366           It is usually better to rely on Coro::AnyEvent or Coro::EV, as this
367           is pretty low-level functionality.
368
369           This variable stores a Coro object that is put into the ready queue
370           when there are no other ready threads (without invoking any ready
371           hooks).
372
373           The default implementation dies with "FATAL: deadlock detected.",
374           followed by a thread listing, because the program has no other way
375           to continue.
376
377           This hook is overwritten by modules such as "Coro::EV" and
378           "Coro::AnyEvent" to wait on an external event that hopefully wakes
379           up a coro so the scheduler can run it.
380
381           See Coro::EV or Coro::AnyEvent for examples of using this
382           technique.
383

SIMPLE CORO CREATION

385       async { ... } [@args...]
386           Create a new coro and return its Coro object (usually unused). The
387           coro will be put into the ready queue, so it will start running
388           automatically on the next scheduler run.
389
390           The first argument is a codeblock/closure that should be executed
391           in the coro. When it returns argument returns the coro is
392           automatically terminated.
393
394           The remaining arguments are passed as arguments to the closure.
395
396           See the "Coro::State::new" constructor for info about the coro
397           environment in which coro are executed.
398
399           Calling "exit" in a coro will do the same as calling exit outside
400           the coro. Likewise, when the coro dies, the program will exit, just
401           as it would in the main program.
402
403           If you do not want that, you can provide a default "die" handler,
404           or simply avoid dieing (by use of "eval").
405
406           Example: Create a new coro that just prints its arguments.
407
408              async {
409                 print "@_\n";
410              } 1,2,3,4;
411
412       async_pool { ... } [@args...]
413           Similar to "async", but uses a coro pool, so you should not call
414           terminate or join on it (although you are allowed to), and you get
415           a coro that might have executed other code already (which can be
416           good or bad :).
417
418           On the plus side, this function is about twice as fast as creating
419           (and destroying) a completely new coro, so if you need a lot of
420           generic coros in quick successsion, use "async_pool", not "async".
421
422           The code block is executed in an "eval" context and a warning will
423           be issued in case of an exception instead of terminating the
424           program, as "async" does. As the coro is being reused, stuff like
425           "on_destroy" will not work in the expected way, unless you call
426           terminate or cancel, which somehow defeats the purpose of pooling
427           (but is fine in the exceptional case).
428
429           The priority will be reset to 0 after each run, all "swap_sv" calls
430           will be undone, tracing will be disabled, the description will be
431           reset and the default output filehandle gets restored, so you can
432           change all these. Otherwise the coro will be re-used "as-is": most
433           notably if you change other per-coro global stuff such as $/ you
434           must needs revert that change, which is most simply done by using
435           local as in: "local $/".
436
437           The idle pool size is limited to 8 idle coros (this can be adjusted
438           by changing $Coro::POOL_SIZE), but there can be as many non-idle
439           coros as required.
440
441           If you are concerned about pooled coros growing a lot because a
442           single "async_pool" used a lot of stackspace you can e.g.
443           "async_pool { terminate }" once per second or so to slowly
444           replenish the pool. In addition to that, when the stacks used by a
445           handler grows larger than 32kb (adjustable via $Coro::POOL_RSS) it
446           will also be destroyed.
447

STATIC METHODS

449       Static methods are actually functions that implicitly operate on the
450       current coro.
451
452       schedule
453           Calls the scheduler. The scheduler will find the next coro that is
454           to be run from the ready queue and switches to it. The next coro to
455           be run is simply the one with the highest priority that is longest
456           in its ready queue. If there is no coro ready, it will call the
457           $Coro::idle hook.
458
459           Please note that the current coro will not be put into the ready
460           queue, so calling this function usually means you will never be
461           called again unless something else (e.g. an event handler) calls
462           "->ready", thus waking you up.
463
464           This makes "schedule" the generic method to use to block the
465           current coro and wait for events: first you remember the current
466           coro in a variable, then arrange for some callback of yours to call
467           "->ready" on that once some event happens, and last you call
468           "schedule" to put yourself to sleep. Note that a lot of things can
469           wake your coro up, so you need to check whether the event indeed
470           happened, e.g. by storing the status in a variable.
471
472           See HOW TO WAIT FOR A CALLBACK, below, for some ways to wait for
473           callbacks.
474
475       cede
476           "Cede" to other coros. This function puts the current coro into the
477           ready queue and calls "schedule", which has the effect of giving up
478           the current "timeslice" to other coros of the same or higher
479           priority. Once your coro gets its turn again it will automatically
480           be resumed.
481
482           This function is often called "yield" in other languages.
483
484       Coro::cede_notself
485           Works like cede, but is not exported by default and will cede to
486           any coro, regardless of priority. This is useful sometimes to
487           ensure progress is made.
488
489       terminate [arg...]
490           Terminates the current coro with the given status values (see
491           cancel). The values will not be copied, but referenced directly.
492
493       Coro::on_enter BLOCK, Coro::on_leave BLOCK
494           These function install enter and leave winders in the current
495           scope. The enter block will be executed when on_enter is called and
496           whenever the current coro is re-entered by the scheduler, while the
497           leave block is executed whenever the current coro is blocked by the
498           scheduler, and also when the containing scope is exited (by
499           whatever means, be it exit, die, last etc.).
500
501           Neither invoking the scheduler, nor exceptions, are allowed within
502           those BLOCKs. That means: do not even think about calling "die"
503           without an eval, and do not even think of entering the scheduler in
504           any way.
505
506           Since both BLOCKs are tied to the current scope, they will
507           automatically be removed when the current scope exits.
508
509           These functions implement the same concept as "dynamic-wind" in
510           scheme does, and are useful when you want to localise some resource
511           to a specific coro.
512
513           They slow down thread switching considerably for coros that use
514           them (about 40% for a BLOCK with a single assignment, so thread
515           switching is still reasonably fast if the handlers are fast).
516
517           These functions are best understood by an example: The following
518           function will change the current timezone to
519           "Antarctica/South_Pole", which requires a call to "tzset", but by
520           using "on_enter" and "on_leave", which remember/change the current
521           timezone and restore the previous value, respectively, the timezone
522           is only changed for the coro that installed those handlers.
523
524              use POSIX qw(tzset);
525
526              async {
527                 my $old_tz; # store outside TZ value here
528
529                 Coro::on_enter {
530                    $old_tz = $ENV{TZ}; # remember the old value
531
532                    $ENV{TZ} = "Antarctica/South_Pole";
533                    tzset; # enable new value
534                 };
535
536                 Coro::on_leave {
537                    $ENV{TZ} = $old_tz;
538                    tzset; # restore old value
539                 };
540
541                 # at this place, the timezone is Antarctica/South_Pole,
542                 # without disturbing the TZ of any other coro.
543              };
544
545           This can be used to localise about any resource (locale, uid,
546           current working directory etc.) to a block, despite the existence
547           of other coros.
548
549           Another interesting example implements time-sliced multitasking
550           using interval timers (this could obviously be optimised, but does
551           the job):
552
553              # "timeslice" the given block
554              sub timeslice(&) {
555                 use Time::HiRes ();
556
557                 Coro::on_enter {
558                    # on entering the thread, we set an VTALRM handler to cede
559                    $SIG{VTALRM} = sub { cede };
560                    # and then start the interval timer
561                    Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
562                 };
563                 Coro::on_leave {
564                    # on leaving the thread, we stop the interval timer again
565                    Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
566                 };
567
568                 &{+shift};
569              }
570
571              # use like this:
572              timeslice {
573                 # The following is an endless loop that would normally
574                 # monopolise the process. Since it runs in a timesliced
575                 # environment, it will regularly cede to other threads.
576                 while () { }
577              };
578
579       killall
580           Kills/terminates/cancels all coros except the currently running
581           one.
582
583           Note that while this will try to free some of the main interpreter
584           resources if the calling coro isn't the main coro, but one cannot
585           free all of them, so if a coro that is not the main coro calls this
586           function, there will be some one-time resource leak.
587

CORO OBJECT METHODS

589       These are the methods you can call on coro objects (or to create them).
590
591       new Coro \&sub [, @args...]
592           Create a new coro and return it. When the sub returns, the coro
593           automatically terminates as if "terminate" with the returned values
594           were called. To make the coro run you must first put it into the
595           ready queue by calling the ready method.
596
597           See "async" and "Coro::State::new" for additional info about the
598           coro environment.
599
600       $success = $coro->ready
601           Put the given coro into the end of its ready queue (there is one
602           queue for each priority) and return true. If the coro is already in
603           the ready queue, do nothing and return false.
604
605           This ensures that the scheduler will resume this coro automatically
606           once all the coro of higher priority and all coro of the same
607           priority that were put into the ready queue earlier have been
608           resumed.
609
610       $coro->suspend
611           Suspends the specified coro. A suspended coro works just like any
612           other coro, except that the scheduler will not select a suspended
613           coro for execution.
614
615           Suspending a coro can be useful when you want to keep the coro from
616           running, but you don't want to destroy it, or when you want to
617           temporarily freeze a coro (e.g. for debugging) to resume it later.
618
619           A scenario for the former would be to suspend all (other) coros
620           after a fork and keep them alive, so their destructors aren't
621           called, but new coros can be created.
622
623       $coro->resume
624           If the specified coro was suspended, it will be resumed. Note that
625           when the coro was in the ready queue when it was suspended, it
626           might have been unreadied by the scheduler, so an activation might
627           have been lost.
628
629           To avoid this, it is best to put a suspended coro into the ready
630           queue unconditionally, as every synchronisation mechanism must
631           protect itself against spurious wakeups, and the one in the Coro
632           family certainly do that.
633
634       $state->is_new
635           Returns true iff this Coro object is "new", i.e. has never been run
636           yet. Those states basically consist of only the code reference to
637           call and the arguments, but consumes very little other resources.
638           New states will automatically get assigned a perl interpreter when
639           they are transferred to.
640
641       $state->is_zombie
642           Returns true iff the Coro object has been cancelled, i.e.  its
643           resources freed because they were "cancel"'ed, "terminate"'d,
644           "safe_cancel"'ed or simply went out of scope.
645
646           The name "zombie" stems from UNIX culture, where a process that has
647           exited and only stores and exit status and no other resources is
648           called a "zombie".
649
650       $is_ready = $coro->is_ready
651           Returns true iff the Coro object is in the ready queue. Unless the
652           Coro object gets destroyed, it will eventually be scheduled by the
653           scheduler.
654
655       $is_running = $coro->is_running
656           Returns true iff the Coro object is currently running. Only one
657           Coro object can ever be in the running state (but it currently is
658           possible to have multiple running Coro::States).
659
660       $is_suspended = $coro->is_suspended
661           Returns true iff this Coro object has been suspended. Suspended
662           Coros will not ever be scheduled.
663
664       $coro->cancel ($arg...)
665           Terminate the given Coro thread and make it return the given
666           arguments as status (default: an empty list). Never returns if the
667           Coro is the current Coro.
668
669           This is a rather brutal way to free a coro, with some limitations -
670           if the thread is inside a C callback that doesn't expect to be
671           canceled, bad things can happen, or if the cancelled thread insists
672           on running complicated cleanup handlers that rely on its thread
673           context, things will not work.
674
675           Any cleanup code being run (e.g. from "guard" blocks, destructors
676           and so on) will be run without a thread context, and is not allowed
677           to switch to other threads. A common mistake is to call "->cancel"
678           from a destructor called by die'ing inside the thread to be
679           cancelled for example.
680
681           On the plus side, "->cancel" will always clean up the thread, no
682           matter what.  If your cleanup code is complex or you want to avoid
683           cancelling a C-thread that doesn't know how to clean up itself, it
684           can be better to "->throw" an exception, or use "->safe_cancel".
685
686           The arguments to "->cancel" are not copied, but instead will be
687           referenced directly (e.g. if you pass $var and after the call
688           change that variable, then you might change the return values
689           passed to e.g. "join", so don't do that).
690
691           The resources of the Coro are usually freed (or destructed) before
692           this call returns, but this can be delayed for an indefinite amount
693           of time, as in some cases the manager thread has to run first to
694           actually destruct the Coro object.
695
696       $coro->safe_cancel ($arg...)
697           Works mostly like "->cancel", but is inherently "safer", and
698           consequently, can fail with an exception in cases the thread is not
699           in a cancellable state. Essentially, "->safe_cancel" is a
700           "->cancel" with extra checks before canceling.
701
702           It works a bit like throwing an exception that cannot be caught -
703           specifically, it will clean up the thread from within itself, so
704           all cleanup handlers (e.g. "guard" blocks) are run with full thread
705           context and can block if they wish. The downside is that there is
706           no guarantee that the thread can be cancelled when you call this
707           method, and therefore, it might fail. It is also considerably
708           slower than "cancel" or "terminate".
709
710           A thread is in a safe-cancellable state if it either has never been
711           run yet, has already been canceled/terminated or otherwise
712           destroyed, or has no C context attached and is inside an SLF
713           function.
714
715           The first two states are trivial - a thread that hasnot started or
716           has already finished is safe to cancel.
717
718           The last state basically means that the thread isn't currently
719           inside a perl callback called from some C function (usually via
720           some XS modules) and isn't currently executing inside some C
721           function itself (via Coro's XS API).
722
723           This call returns true when it could cancel the thread, or croaks
724           with an error otherwise (i.e. it either returns true or doesn't
725           return at all).
726
727           Why the weird interface? Well, there are two common models on how
728           and when to cancel things. In the first, you have the expectation
729           that your coro thread can be cancelled when you want to cancel it -
730           if the thread isn't cancellable, this would be a bug somewhere, so
731           "->safe_cancel" croaks to notify of the bug.
732
733           In the second model you sometimes want to ask nicely to cancel a
734           thread, but if it's not a good time, well, then don't cancel. This
735           can be done relatively easy like this:
736
737              if (! eval { $coro->safe_cancel }) {
738                 warn "unable to cancel thread: $@";
739              }
740
741           However, what you never should do is first try to cancel "safely"
742           and if that fails, cancel the "hard" way with "->cancel". That
743           makes no sense: either you rely on being able to execute cleanup
744           code in your thread context, or you don't. If you do, then
745           "->safe_cancel" is the only way, and if you don't, then "->cancel"
746           is always faster and more direct.
747
748       $coro->schedule_to
749           Puts the current coro to sleep (like "Coro::schedule"), but instead
750           of continuing with the next coro from the ready queue, always
751           switch to the given coro object (regardless of priority etc.). The
752           readyness state of that coro isn't changed.
753
754           This is an advanced method for special cases - I'd love to hear
755           about any uses for this one.
756
757       $coro->cede_to
758           Like "schedule_to", but puts the current coro into the ready queue.
759           This has the effect of temporarily switching to the given coro, and
760           continuing some time later.
761
762           This is an advanced method for special cases - I'd love to hear
763           about any uses for this one.
764
765       $coro->throw ([$scalar])
766           If $throw is specified and defined, it will be thrown as an
767           exception inside the coro at the next convenient point in time.
768           Otherwise clears the exception object.
769
770           Coro will check for the exception each time a schedule-like-
771           function returns, i.e. after each "schedule", "cede",
772           "Coro::Semaphore->down", "Coro::Handle->readable" and so on. Most
773           of those functions (all that are part of Coro itself) detect this
774           case and return early in case an exception is pending.
775
776           The exception object will be thrown "as is" with the specified
777           scalar in $@, i.e. if it is a string, no line number or newline
778           will be appended (unlike with "die").
779
780           This can be used as a softer means than either "cancel" or
781           "safe_cancel "to ask a coro to end itself, although there is no
782           guarantee that the exception will lead to termination, and if the
783           exception isn't caught it might well end the whole program.
784
785           You might also think of "throw" as being the moral equivalent of
786           "kill"ing a coro with a signal (in this case, a scalar).
787
788       $coro->join
789           Wait until the coro terminates and return any values given to the
790           "terminate" or "cancel" functions. "join" can be called
791           concurrently from multiple threads, and all will be resumed and
792           given the status return once the $coro terminates.
793
794       $coro->on_destroy (\&cb)
795           Registers a callback that is called when this coro thread gets
796           destroyed, that is, after its resources have been freed but before
797           it is joined. The callback gets passed the terminate/cancel
798           arguments, if any, and must not die, under any circumstances.
799
800           There can be any number of "on_destroy" callbacks per coro, and
801           there is currently no way to remove a callback once added.
802
803       $oldprio = $coro->prio ($newprio)
804           Sets (or gets, if the argument is missing) the priority of the coro
805           thread. Higher priority coro get run before lower priority coros.
806           Priorities are small signed integers (currently -4 .. +3), that you
807           can refer to using PRIO_xxx constants (use the import tag :prio to
808           get then):
809
810              PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
811                  3    >     1     >      0      >    -1    >    -3     >    -4
812
813              # set priority to HIGH
814              current->prio (PRIO_HIGH);
815
816           The idle coro thread ($Coro::idle) always has a lower priority than
817           any existing coro.
818
819           Changing the priority of the current coro will take effect
820           immediately, but changing the priority of a coro in the ready queue
821           (but not running) will only take effect after the next schedule (of
822           that coro). This is a bug that will be fixed in some future
823           version.
824
825       $newprio = $coro->nice ($change)
826           Similar to "prio", but subtract the given value from the priority
827           (i.e.  higher values mean lower priority, just as in UNIX's nice
828           command).
829
830       $olddesc = $coro->desc ($newdesc)
831           Sets (or gets in case the argument is missing) the description for
832           this coro thread. This is just a free-form string you can associate
833           with a coro.
834
835           This method simply sets the "$coro->{desc}" member to the given
836           string. You can modify this member directly if you wish, and in
837           fact, this is often preferred to indicate major processing states
838           that can then be seen for example in a Coro::Debug session:
839
840              sub my_long_function {
841                 local $Coro::current->{desc} = "now in my_long_function";
842                 ...
843                 $Coro::current->{desc} = "my_long_function: phase 1";
844                 ...
845                 $Coro::current->{desc} = "my_long_function: phase 2";
846                 ...
847              }
848

GLOBAL FUNCTIONS

850       Coro::nready
851           Returns the number of coro that are currently in the ready state,
852           i.e. that can be switched to by calling "schedule" directory or
853           indirectly. The value 0 means that the only runnable coro is the
854           currently running one, so "cede" would have no effect, and
855           "schedule" would cause a deadlock unless there is an idle handler
856           that wakes up some coro.
857
858       my $guard = Coro::guard { ... }
859           This function still exists, but is deprecated. Please use the
860           "Guard::guard" function instead.
861
862       unblock_sub { ... }
863           This utility function takes a BLOCK or code reference and
864           "unblocks" it, returning a new coderef. Unblocking means that
865           calling the new coderef will return immediately without blocking,
866           returning nothing, while the original code ref will be called (with
867           parameters) from within another coro.
868
869           The reason this function exists is that many event libraries (such
870           as the venerable Event module) are not thread-safe (a weaker form
871           of reentrancy). This means you must not block within event
872           callbacks, otherwise you might suffer from crashes or worse. The
873           only event library currently known that is safe to use without
874           "unblock_sub" is EV (but you might still run into deadlocks if all
875           event loops are blocked).
876
877           Coro will try to catch you when you block in the event loop
878           ("FATAL: $Coro::idle blocked itself"), but this is just best effort
879           and only works when you do not run your own event loop.
880
881           This function allows your callbacks to block by executing them in
882           another coro where it is safe to block. One example where blocking
883           is handy is when you use the Coro::AIO functions to save results to
884           disk, for example.
885
886           In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
887           when creating event callbacks that want to block.
888
889           If your handler does not plan to block (e.g. simply sends a message
890           to another coro, or puts some other coro into the ready queue),
891           there is no reason to use "unblock_sub".
892
893           Note that you also need to use "unblock_sub" for any other
894           callbacks that are indirectly executed by any C-based event loop.
895           For example, when you use a module that uses AnyEvent (and you use
896           Coro::AnyEvent) and it provides callbacks that are the result of
897           some event callback, then you must not block either, or use
898           "unblock_sub".
899
900       $cb = rouse_cb
901           Create and return a "rouse callback". That's a code reference that,
902           when called, will remember a copy of its arguments and notify the
903           owner coro of the callback.
904
905           Only the first invocation will store agruments and signal any
906           waiter - further calls will effectively be ignored, but it is ok to
907           try.
908
909           Also see the next function.
910
911       @args = rouse_wait [$cb]
912           Wait for the specified rouse callback to be invoked (or if the
913           argument is missing, use the most recently created callback in the
914           current coro).
915
916           As soon as the callback is invoked (or when the callback was
917           invoked before "rouse_wait"), it will return the arguments
918           originally passed to the rouse callback. In scalar context, that
919           means you get the last argument, just as if "rouse_wait" had a
920           "return ($a1, $a2, $a3...)"  statement at the end.
921
922           You are only allowed to wait once for a given rouse callback.
923
924           See the section HOW TO WAIT FOR A CALLBACK for an actual usage
925           example.
926
927           As of Coro 6.57, you can reliably wait for a rouse callback in a
928           different thread than from where it was created.
929

HOW TO WAIT FOR A CALLBACK

931       It is very common for a coro to wait for some callback to be called.
932       This occurs naturally when you use coro in an otherwise event-based
933       program, or when you use event-based libraries.
934
935       These typically register a callback for some event, and call that
936       callback when the event occurred. In a coro, however, you typically
937       want to just wait for the event, simplyifying things.
938
939       For example "AnyEvent->child" registers a callback to be called when a
940       specific child has exited:
941
942          my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
943
944       But from within a coro, you often just want to write this:
945
946          my $status = wait_for_child $pid;
947
948       Coro offers two functions specifically designed to make this easy,
949       "rouse_cb" and "rouse_wait".
950
951       The first function, "rouse_cb", generates and returns a callback that,
952       when invoked, will save its arguments and notify the coro that created
953       the callback.
954
955       The second function, "rouse_wait", waits for the callback to be called
956       (by calling "schedule" to go to sleep) and returns the arguments
957       originally passed to the callback.
958
959       Using these functions, it becomes easy to write the "wait_for_child"
960       function mentioned above:
961
962          sub wait_for_child($) {
963             my ($pid) = @_;
964
965             my $watcher = AnyEvent->child (pid => $pid, cb => rouse_cb);
966
967             my ($rpid, $rstatus) = rouse_wait;
968             $rstatus
969          }
970
971       In the case where "rouse_cb" and "rouse_wait" are not flexible enough,
972       you can roll your own, using "schedule" and "ready":
973
974          sub wait_for_child($) {
975             my ($pid) = @_;
976
977             # store the current coro in $current,
978             # and provide result variables for the closure passed to ->child
979             my $current = $Coro::current;
980             my ($done, $rstatus);
981
982             # pass a closure to ->child
983             my $watcher = AnyEvent->child (pid => $pid, cb => sub {
984                $rstatus = $_[1]; # remember rstatus
985                $done = 1;        # mark $rstatus as valid
986                $current->ready;  # wake up the waiting thread
987             });
988
989             # wait until the closure has been called
990             schedule while !$done;
991
992             $rstatus
993          }
994

BUGS/LIMITATIONS

996       fork with pthread backend
997           When Coro is compiled using the pthread backend (which isn't
998           recommended but required on many BSDs as their libcs are completely
999           broken), then coro will not survive a fork. There is no known
1000           workaround except to fix your libc and use a saner backend.
1001
1002       perl process emulation ("threads")
1003           This module is not perl-pseudo-thread-safe. You should only ever
1004           use this module from the first thread (this requirement might be
1005           removed in the future to allow per-thread schedulers, but
1006           Coro::State does not yet allow this). I recommend disabling thread
1007           support and using processes, as having the windows process
1008           emulation enabled under unix roughly halves perl performance, even
1009           when not used.
1010
1011           Attempts to use threads created in another emulated process will
1012           crash ("cleanly", with a null pointer exception).
1013
1014       coro switching is not signal safe
1015           You must not switch to another coro from within a signal handler
1016           (only relevant with %SIG - most event libraries provide safe
1017           signals), unless you are sure you are not interrupting a Coro
1018           function.
1019
1020           That means you MUST NOT call any function that might "block" the
1021           current coro - "cede", "schedule" "Coro::Semaphore->down" or
1022           anything that calls those. Everything else, including calling
1023           "ready", works.
1024

WINDOWS PROCESS EMULATION

1026       A great many people seem to be confused about ithreads (for example,
1027       Chip Salzenberg called me unintelligent, incapable, stupid and
1028       gullible, while in the same mail making rather confused statements
1029       about perl ithreads (for example, that memory or files would be
1030       shared), showing his lack of understanding of this area - if it is hard
1031       to understand for Chip, it is probably not obvious to everybody).
1032
1033       What follows is an ultra-condensed version of my talk about threads in
1034       scripting languages given on the perl workshop 2009:
1035
1036       The so-called "ithreads" were originally implemented for two reasons:
1037       first, to (badly) emulate unix processes on native win32 perls, and
1038       secondly, to replace the older, real thread model ("5.005-threads").
1039
1040       It does that by using threads instead of OS processes. The difference
1041       between processes and threads is that threads share memory (and other
1042       state, such as files) between threads within a single process, while
1043       processes do not share anything (at least not semantically). That means
1044       that modifications done by one thread are seen by others, while
1045       modifications by one process are not seen by other processes.
1046
1047       The "ithreads" work exactly like that: when creating a new ithreads
1048       process, all state is copied (memory is copied physically, files and
1049       code is copied logically). Afterwards, it isolates all modifications.
1050       On UNIX, the same behaviour can be achieved by using operating system
1051       processes, except that UNIX typically uses hardware built into the
1052       system to do this efficiently, while the windows process emulation
1053       emulates this hardware in software (rather efficiently, but of course
1054       it is still much slower than dedicated hardware).
1055
1056       As mentioned before, loading code, modifying code, modifying data
1057       structures and so on is only visible in the ithreads process doing the
1058       modification, not in other ithread processes within the same OS
1059       process.
1060
1061       This is why "ithreads" do not implement threads for perl at all, only
1062       processes. What makes it so bad is that on non-windows platforms, you
1063       can actually take advantage of custom hardware for this purpose (as
1064       evidenced by the forks module, which gives you the (i-) threads API,
1065       just much faster).
1066
1067       Sharing data is in the i-threads model is done by transferring data
1068       structures between threads using copying semantics, which is very slow
1069       - shared data simply does not exist. Benchmarks using i-threads which
1070       are communication-intensive show extremely bad behaviour with i-threads
1071       (in fact, so bad that Coro, which cannot take direct advantage of
1072       multiple CPUs, is often orders of magnitude faster because it shares
1073       data using real threads, refer to my talk for details).
1074
1075       As summary, i-threads *use* threads to implement processes, while the
1076       compatible forks module *uses* processes to emulate, uhm, processes.
1077       I-threads slow down every perl program when enabled, and outside of
1078       windows, serve no (or little) practical purpose, but disadvantages
1079       every single-threaded Perl program.
1080
1081       This is the reason that I try to avoid the name "ithreads", as it is
1082       misleading as it implies that it implements some kind of thread model
1083       for perl, and prefer the name "windows process emulation", which
1084       describes the actual use and behaviour of it much better.
1085

SEE ALSO

1087       Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event.
1088
1089       Debugging: Coro::Debug.
1090
1091       Support/Utility: Coro::Specific, Coro::Util.
1092
1093       Locking and IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,
1094       Coro::SemaphoreSet, Coro::RWLock.
1095
1096       I/O and Timers: Coro::Timer, Coro::Handle, Coro::Socket, Coro::AIO.
1097
1098       Compatibility with other modules: Coro::LWP (but see also
1099       AnyEvent::HTTP for a better-working alternative), Coro::BDB,
1100       Coro::Storable, Coro::Select.
1101
1102       XS API: Coro::MakeMaker.
1103
1104       Low level Configuration, Thread Environment, Continuations:
1105       Coro::State.
1106

AUTHOR/SUPPORT/CONTACT

1108          Marc A. Lehmann <schmorp@schmorp.de>
1109          http://software.schmorp.de/pkg/Coro.html
1110
1111
1112
1113perl v5.32.0                      2020-08-03                           Coro(3)
Impressum