ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Coro/README
Revision: 1.36
Committed: Sun Jun 7 02:01:04 2015 UTC (8 years, 11 months ago) by root
Branch: MAIN
CVS Tags: rel-6_43
Changes since 1.35: +3 -3 lines
Log Message:
*** empty log message ***

File Contents

# Content
1 NAME
2 Coro - the only real threads in perl
3
4 SYNOPSIS
5 use Coro;
6
7 async {
8 # some asynchronous thread of execution
9 print "2\n";
10 cede; # yield back to main
11 print "4\n";
12 };
13 print "1\n";
14 cede; # yield to coro
15 print "3\n";
16 cede; # and again
17
18 # use locking
19 my $lock = new Coro::Semaphore;
20 my $locked;
21
22 $lock->down;
23 $locked = 1;
24 $lock->up;
25
26 DESCRIPTION
27 For a tutorial-style introduction, please read the Coro::Intro manpage.
28 This manpage mainly contains reference information.
29
30 This module collection manages continuations in general, most often in
31 the form of cooperative threads (also called coros, or simply "coro" in
32 the documentation). They are similar to kernel threads but don't (in
33 general) run in parallel at the same time even on SMP machines. The
34 specific flavor of thread offered by this module also guarantees you
35 that it will not switch between threads unless necessary, at
36 easily-identified points in your program, so locking and parallel access
37 are rarely an issue, making thread programming much safer and easier
38 than using other thread models.
39
40 Unlike the so-called "Perl threads" (which are not actually real threads
41 but only the windows process emulation (see section of same name for
42 more details) ported to UNIX, and as such act as processes), Coro
43 provides a full shared address space, which makes communication between
44 threads very easy. And coro threads are fast, too: disabling the Windows
45 process emulation code in your perl and using Coro can easily result in
46 a two to four times speed increase for your programs. A parallel matrix
47 multiplication benchmark (very communication-intensive) runs over 300
48 times faster on a single core than perls pseudo-threads on a quad core
49 using all four cores.
50
51 Coro achieves that by supporting multiple running interpreters that
52 share data, which is especially useful to code pseudo-parallel processes
53 and for event-based programming, such as multiple HTTP-GET requests
54 running concurrently. See Coro::AnyEvent to learn more on how to
55 integrate Coro into an event-based environment.
56
57 In this module, a thread is defined as "callchain + lexical variables +
58 some package variables + C stack), that is, a thread has its own
59 callchain, its own set of lexicals and its own set of perls most
60 important global variables (see Coro::State for more configuration and
61 background info).
62
63 See also the "SEE ALSO" section at the end of this document - the Coro
64 module family is quite large.
65
66 CORO THREAD LIFE CYCLE
67 During the long and exciting (or not) life of a coro thread, it goes
68 through a number of states:
69
70 1. Creation
71 The first thing in the life of a coro thread is it's creation -
72 obviously. The typical way to create a thread is to call the "async
73 BLOCK" function:
74
75 async {
76 # thread code goes here
77 };
78
79 You can also pass arguments, which are put in @_:
80
81 async {
82 print $_[1]; # prints 2
83 } 1, 2, 3;
84
85 This creates a new coro thread and puts it into the ready queue,
86 meaning it will run as soon as the CPU is free for it.
87
88 "async" will return a Coro object - you can store this for future
89 reference or ignore it - a thread that is running, ready to run or
90 waiting for some event is alive on it's own.
91
92 Another way to create a thread is to call the "new" constructor with
93 a code-reference:
94
95 new Coro sub {
96 # thread code goes here
97 }, @optional_arguments;
98
99 This is quite similar to calling "async", but the important
100 difference is that the new thread is not put into the ready queue,
101 so the thread will not run until somebody puts it there. "async" is,
102 therefore, identical to this sequence:
103
104 my $coro = new Coro sub {
105 # thread code goes here
106 };
107 $coro->ready;
108 return $coro;
109
110 2. Startup
111 When a new coro thread is created, only a copy of the code reference
112 and the arguments are stored, no extra memory for stacks and so on
113 is allocated, keeping the coro thread in a low-memory state.
114
115 Only when it actually starts executing will all the resources be
116 finally allocated.
117
118 The optional arguments specified at coro creation are available in
119 @_, similar to function calls.
120
121 3. Running / Blocking
122 A lot can happen after the coro thread has started running. Quite
123 usually, it will not run to the end in one go (because you could use
124 a function instead), but it will give up the CPU regularly because
125 it waits for external events.
126
127 As long as a coro thread runs, its Coro object is available in the
128 global variable $Coro::current.
129
130 The low-level way to give up the CPU is to call the scheduler, which
131 selects a new coro thread to run:
132
133 Coro::schedule;
134
135 Since running threads are not in the ready queue, calling the
136 scheduler without doing anything else will block the coro thread
137 forever - you need to arrange either for the coro to put woken up
138 (readied) by some other event or some other thread, or you can put
139 it into the ready queue before scheduling:
140
141 # this is exactly what Coro::cede does
142 $Coro::current->ready;
143 Coro::schedule;
144
145 All the higher-level synchronisation methods (Coro::Semaphore,
146 Coro::rouse_*...) are actually implemented via "->ready" and
147 "Coro::schedule".
148
149 While the coro thread is running it also might get assigned a
150 C-level thread, or the C-level thread might be unassigned from it,
151 as the Coro runtime wishes. A C-level thread needs to be assigned
152 when your perl thread calls into some C-level function and that
153 function in turn calls perl and perl then wants to switch
154 coroutines. This happens most often when you run an event loop and
155 block in the callback, or when perl itself calls some function such
156 as "AUTOLOAD" or methods via the "tie" mechanism.
157
158 4. Termination
159 Many threads actually terminate after some time. There are a number
160 of ways to terminate a coro thread, the simplest is returning from
161 the top-level code reference:
162
163 async {
164 # after returning from here, the coro thread is terminated
165 };
166
167 async {
168 return if 0.5 < rand; # terminate a little earlier, maybe
169 print "got a chance to print this\n";
170 # or here
171 };
172
173 Any values returned from the coroutine can be recovered using
174 "->join":
175
176 my $coro = async {
177 "hello, world\n" # return a string
178 };
179
180 my $hello_world = $coro->join;
181
182 print $hello_world;
183
184 Another way to terminate is to call "Coro::terminate", which at any
185 subroutine call nesting level:
186
187 async {
188 Coro::terminate "return value 1", "return value 2";
189 };
190
191 Yet another way is to "->cancel" (or "->safe_cancel") the coro
192 thread from another thread:
193
194 my $coro = async {
195 exit 1;
196 };
197
198 $coro->cancel; # also accepts values for ->join to retrieve
199
200 Cancellation *can* be dangerous - it's a bit like calling "exit"
201 without actually exiting, and might leave C libraries and XS modules
202 in a weird state. Unlike other thread implementations, however, Coro
203 is exceptionally safe with regards to cancellation, as perl will
204 always be in a consistent state, and for those cases where you want
205 to do truly marvellous things with your coro while it is being
206 cancelled - that is, make sure all cleanup code is executed from the
207 thread being cancelled - there is even a "->safe_cancel" method.
208
209 So, cancelling a thread that runs in an XS event loop might not be
210 the best idea, but any other combination that deals with perl only
211 (cancelling when a thread is in a "tie" method or an "AUTOLOAD" for
212 example) is safe.
213
214 Last not least, a coro thread object that isn't referenced is
215 "->cancel"'ed automatically - just like other objects in Perl. This
216 is not such a common case, however - a running thread is referencedy
217 by $Coro::current, a thread ready to run is referenced by the ready
218 queue, a thread waiting on a lock or semaphore is referenced by
219 being in some wait list and so on. But a thread that isn't in any of
220 those queues gets cancelled:
221
222 async {
223 schedule; # cede to other coros, don't go into the ready queue
224 };
225
226 cede;
227 # now the async above is destroyed, as it is not referenced by anything.
228
229 A slightly embellished example might make it clearer:
230
231 async {
232 my $guard = Guard::guard { print "destroyed\n" };
233 schedule while 1;
234 };
235
236 cede;
237
238 Superficially one might not expect any output - since the "async"
239 implements an endless loop, the $guard will not be cleaned up.
240 However, since the thread object returned by "async" is not stored
241 anywhere, the thread is initially referenced because it is in the
242 ready queue, when it runs it is referenced by $Coro::current, but
243 when it calls "schedule", it gets "cancel"ed causing the guard
244 object to be destroyed (see the next section), and printing it's
245 message.
246
247 If this seems a bit drastic, remember that this only happens when
248 nothing references the thread anymore, which means there is no way
249 to further execute it, ever. The only options at this point are
250 leaking the thread, or cleaning it up, which brings us to...
251
252 5. Cleanup
253 Threads will allocate various resources. Most but not all will be
254 returned when a thread terminates, during clean-up.
255
256 Cleanup is quite similar to throwing an uncaught exception: perl
257 will work it's way up through all subroutine calls and blocks. On
258 it's way, it will release all "my" variables, undo all "local"'s and
259 free any other resources truly local to the thread.
260
261 So, a common way to free resources is to keep them referenced only
262 by my variables:
263
264 async {
265 my $big_cache = new Cache ...;
266 };
267
268 If there are no other references, then the $big_cache object will be
269 freed when the thread terminates, regardless of how it does so.
270
271 What it does "NOT" do is unlock any Coro::Semaphores or similar
272 resources, but that's where the "guard" methods come in handy:
273
274 my $sem = new Coro::Semaphore;
275
276 async {
277 my $lock_guard = $sem->guard;
278 # if we return, or die or get cancelled, here,
279 # then the semaphore will be "up"ed.
280 };
281
282 The "Guard::guard" function comes in handy for any custom cleanup
283 you might want to do (but you cannot switch to other coroutines from
284 those code blocks):
285
286 async {
287 my $window = new Gtk2::Window "toplevel";
288 # The window will not be cleaned up automatically, even when $window
289 # gets freed, so use a guard to ensure it's destruction
290 # in case of an error:
291 my $window_guard = Guard::guard { $window->destroy };
292
293 # we are safe here
294 };
295
296 Last not least, "local" can often be handy, too, e.g. when
297 temporarily replacing the coro thread description:
298
299 sub myfunction {
300 local $Coro::current->{desc} = "inside myfunction(@_)";
301
302 # if we return or die here, the description will be restored
303 }
304
305 6. Viva La Zombie Muerte
306 Even after a thread has terminated and cleaned up its resources, the
307 Coro object still is there and stores the return values of the
308 thread.
309
310 When there are no other references, it will simply be cleaned up and
311 freed.
312
313 If there areany references, the Coro object will stay around, and
314 you can call "->join" as many times as you wish to retrieve the
315 result values:
316
317 async {
318 print "hi\n";
319 1
320 };
321
322 # run the async above, and free everything before returning
323 # from Coro::cede:
324 Coro::cede;
325
326 {
327 my $coro = async {
328 print "hi\n";
329 1
330 };
331
332 # run the async above, and clean up, but do not free the coro
333 # object:
334 Coro::cede;
335
336 # optionally retrieve the result values
337 my @results = $coro->join;
338
339 # now $coro goes out of scope, and presumably gets freed
340 };
341
342 GLOBAL VARIABLES
343 $Coro::main
344 This variable stores the Coro object that represents the main
345 program. While you can "ready" it and do most other things you can
346 do to coro, it is mainly useful to compare again $Coro::current, to
347 see whether you are running in the main program or not.
348
349 $Coro::current
350 The Coro object representing the current coro (the last coro that
351 the Coro scheduler switched to). The initial value is $Coro::main
352 (of course).
353
354 This variable is strictly *read-only*. You can take copies of the
355 value stored in it and use it as any other Coro object, but you must
356 not otherwise modify the variable itself.
357
358 $Coro::idle
359 This variable is mainly useful to integrate Coro into event loops.
360 It is usually better to rely on Coro::AnyEvent or Coro::EV, as this
361 is pretty low-level functionality.
362
363 This variable stores a Coro object that is put into the ready queue
364 when there are no other ready threads (without invoking any ready
365 hooks).
366
367 The default implementation dies with "FATAL: deadlock detected.",
368 followed by a thread listing, because the program has no other way
369 to continue.
370
371 This hook is overwritten by modules such as "Coro::EV" and
372 "Coro::AnyEvent" to wait on an external event that hopefully wakes
373 up a coro so the scheduler can run it.
374
375 See Coro::EV or Coro::AnyEvent for examples of using this technique.
376
377 SIMPLE CORO CREATION
378 async { ... } [@args...]
379 Create a new coro and return its Coro object (usually unused). The
380 coro will be put into the ready queue, so it will start running
381 automatically on the next scheduler run.
382
383 The first argument is a codeblock/closure that should be executed in
384 the coro. When it returns argument returns the coro is automatically
385 terminated.
386
387 The remaining arguments are passed as arguments to the closure.
388
389 See the "Coro::State::new" constructor for info about the coro
390 environment in which coro are executed.
391
392 Calling "exit" in a coro will do the same as calling exit outside
393 the coro. Likewise, when the coro dies, the program will exit, just
394 as it would in the main program.
395
396 If you do not want that, you can provide a default "die" handler, or
397 simply avoid dieing (by use of "eval").
398
399 Example: Create a new coro that just prints its arguments.
400
401 async {
402 print "@_\n";
403 } 1,2,3,4;
404
405 async_pool { ... } [@args...]
406 Similar to "async", but uses a coro pool, so you should not call
407 terminate or join on it (although you are allowed to), and you get a
408 coro that might have executed other code already (which can be good
409 or bad :).
410
411 On the plus side, this function is about twice as fast as creating
412 (and destroying) a completely new coro, so if you need a lot of
413 generic coros in quick successsion, use "async_pool", not "async".
414
415 The code block is executed in an "eval" context and a warning will
416 be issued in case of an exception instead of terminating the
417 program, as "async" does. As the coro is being reused, stuff like
418 "on_destroy" will not work in the expected way, unless you call
419 terminate or cancel, which somehow defeats the purpose of pooling
420 (but is fine in the exceptional case).
421
422 The priority will be reset to 0 after each run, tracing will be
423 disabled, the description will be reset and the default output
424 filehandle gets restored, so you can change all these. Otherwise the
425 coro will be re-used "as-is": most notably if you change other
426 per-coro global stuff such as $/ you *must needs* revert that
427 change, which is most simply done by using local as in: "local $/".
428
429 The idle pool size is limited to 8 idle coros (this can be adjusted
430 by changing $Coro::POOL_SIZE), but there can be as many non-idle
431 coros as required.
432
433 If you are concerned about pooled coros growing a lot because a
434 single "async_pool" used a lot of stackspace you can e.g.
435 "async_pool { terminate }" once per second or so to slowly replenish
436 the pool. In addition to that, when the stacks used by a handler
437 grows larger than 32kb (adjustable via $Coro::POOL_RSS) it will also
438 be destroyed.
439
440 STATIC METHODS
441 Static methods are actually functions that implicitly operate on the
442 current coro.
443
444 schedule
445 Calls the scheduler. The scheduler will find the next coro that is
446 to be run from the ready queue and switches to it. The next coro to
447 be run is simply the one with the highest priority that is longest
448 in its ready queue. If there is no coro ready, it will call the
449 $Coro::idle hook.
450
451 Please note that the current coro will *not* be put into the ready
452 queue, so calling this function usually means you will never be
453 called again unless something else (e.g. an event handler) calls
454 "->ready", thus waking you up.
455
456 This makes "schedule" *the* generic method to use to block the
457 current coro and wait for events: first you remember the current
458 coro in a variable, then arrange for some callback of yours to call
459 "->ready" on that once some event happens, and last you call
460 "schedule" to put yourself to sleep. Note that a lot of things can
461 wake your coro up, so you need to check whether the event indeed
462 happened, e.g. by storing the status in a variable.
463
464 See HOW TO WAIT FOR A CALLBACK, below, for some ways to wait for
465 callbacks.
466
467 cede
468 "Cede" to other coros. This function puts the current coro into the
469 ready queue and calls "schedule", which has the effect of giving up
470 the current "timeslice" to other coros of the same or higher
471 priority. Once your coro gets its turn again it will automatically
472 be resumed.
473
474 This function is often called "yield" in other languages.
475
476 Coro::cede_notself
477 Works like cede, but is not exported by default and will cede to
478 *any* coro, regardless of priority. This is useful sometimes to
479 ensure progress is made.
480
481 terminate [arg...]
482 Terminates the current coro with the given status values (see
483 cancel). The values will not be copied, but referenced directly.
484
485 Coro::on_enter BLOCK, Coro::on_leave BLOCK
486 These function install enter and leave winders in the current scope.
487 The enter block will be executed when on_enter is called and
488 whenever the current coro is re-entered by the scheduler, while the
489 leave block is executed whenever the current coro is blocked by the
490 scheduler, and also when the containing scope is exited (by whatever
491 means, be it exit, die, last etc.).
492
493 *Neither invoking the scheduler, nor exceptions, are allowed within
494 those BLOCKs*. That means: do not even think about calling "die"
495 without an eval, and do not even think of entering the scheduler in
496 any way.
497
498 Since both BLOCKs are tied to the current scope, they will
499 automatically be removed when the current scope exits.
500
501 These functions implement the same concept as "dynamic-wind" in
502 scheme does, and are useful when you want to localise some resource
503 to a specific coro.
504
505 They slow down thread switching considerably for coros that use them
506 (about 40% for a BLOCK with a single assignment, so thread switching
507 is still reasonably fast if the handlers are fast).
508
509 These functions are best understood by an example: The following
510 function will change the current timezone to
511 "Antarctica/South_Pole", which requires a call to "tzset", but by
512 using "on_enter" and "on_leave", which remember/change the current
513 timezone and restore the previous value, respectively, the timezone
514 is only changed for the coro that installed those handlers.
515
516 use POSIX qw(tzset);
517
518 async {
519 my $old_tz; # store outside TZ value here
520
521 Coro::on_enter {
522 $old_tz = $ENV{TZ}; # remember the old value
523
524 $ENV{TZ} = "Antarctica/South_Pole";
525 tzset; # enable new value
526 };
527
528 Coro::on_leave {
529 $ENV{TZ} = $old_tz;
530 tzset; # restore old value
531 };
532
533 # at this place, the timezone is Antarctica/South_Pole,
534 # without disturbing the TZ of any other coro.
535 };
536
537 This can be used to localise about any resource (locale, uid,
538 current working directory etc.) to a block, despite the existance of
539 other coros.
540
541 Another interesting example implements time-sliced multitasking
542 using interval timers (this could obviously be optimised, but does
543 the job):
544
545 # "timeslice" the given block
546 sub timeslice(&) {
547 use Time::HiRes ();
548
549 Coro::on_enter {
550 # on entering the thread, we set an VTALRM handler to cede
551 $SIG{VTALRM} = sub { cede };
552 # and then start the interval timer
553 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
554 };
555 Coro::on_leave {
556 # on leaving the thread, we stop the interval timer again
557 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
558 };
559
560 &{+shift};
561 }
562
563 # use like this:
564 timeslice {
565 # The following is an endless loop that would normally
566 # monopolise the process. Since it runs in a timesliced
567 # environment, it will regularly cede to other threads.
568 while () { }
569 };
570
571 killall
572 Kills/terminates/cancels all coros except the currently running one.
573
574 Note that while this will try to free some of the main interpreter
575 resources if the calling coro isn't the main coro, but one cannot
576 free all of them, so if a coro that is not the main coro calls this
577 function, there will be some one-time resource leak.
578
579 CORO OBJECT METHODS
580 These are the methods you can call on coro objects (or to create them).
581
582 new Coro \&sub [, @args...]
583 Create a new coro and return it. When the sub returns, the coro
584 automatically terminates as if "terminate" with the returned values
585 were called. To make the coro run you must first put it into the
586 ready queue by calling the ready method.
587
588 See "async" and "Coro::State::new" for additional info about the
589 coro environment.
590
591 $success = $coro->ready
592 Put the given coro into the end of its ready queue (there is one
593 queue for each priority) and return true. If the coro is already in
594 the ready queue, do nothing and return false.
595
596 This ensures that the scheduler will resume this coro automatically
597 once all the coro of higher priority and all coro of the same
598 priority that were put into the ready queue earlier have been
599 resumed.
600
601 $coro->suspend
602 Suspends the specified coro. A suspended coro works just like any
603 other coro, except that the scheduler will not select a suspended
604 coro for execution.
605
606 Suspending a coro can be useful when you want to keep the coro from
607 running, but you don't want to destroy it, or when you want to
608 temporarily freeze a coro (e.g. for debugging) to resume it later.
609
610 A scenario for the former would be to suspend all (other) coros
611 after a fork and keep them alive, so their destructors aren't
612 called, but new coros can be created.
613
614 $coro->resume
615 If the specified coro was suspended, it will be resumed. Note that
616 when the coro was in the ready queue when it was suspended, it might
617 have been unreadied by the scheduler, so an activation might have
618 been lost.
619
620 To avoid this, it is best to put a suspended coro into the ready
621 queue unconditionally, as every synchronisation mechanism must
622 protect itself against spurious wakeups, and the one in the Coro
623 family certainly do that.
624
625 $state->is_new
626 Returns true iff this Coro object is "new", i.e. has never been run
627 yet. Those states basically consist of only the code reference to
628 call and the arguments, but consumes very little other resources.
629 New states will automatically get assigned a perl interpreter when
630 they are transfered to.
631
632 $state->is_zombie
633 Returns true iff the Coro object has been cancelled, i.e. it's
634 resources freed because they were "cancel"'ed, "terminate"'d,
635 "safe_cancel"'ed or simply went out of scope.
636
637 The name "zombie" stems from UNIX culture, where a process that has
638 exited and only stores and exit status and no other resources is
639 called a "zombie".
640
641 $is_ready = $coro->is_ready
642 Returns true iff the Coro object is in the ready queue. Unless the
643 Coro object gets destroyed, it will eventually be scheduled by the
644 scheduler.
645
646 $is_running = $coro->is_running
647 Returns true iff the Coro object is currently running. Only one Coro
648 object can ever be in the running state (but it currently is
649 possible to have multiple running Coro::States).
650
651 $is_suspended = $coro->is_suspended
652 Returns true iff this Coro object has been suspended. Suspended
653 Coros will not ever be scheduled.
654
655 $coro->cancel (arg...)
656 Terminates the given Coro thread and makes it return the given
657 arguments as status (default: an empty list). Never returns if the
658 Coro is the current Coro.
659
660 This is a rather brutal way to free a coro, with some limitations -
661 if the thread is inside a C callback that doesn't expect to be
662 canceled, bad things can happen, or if the cancelled thread insists
663 on running complicated cleanup handlers that rely on its thread
664 context, things will not work.
665
666 Any cleanup code being run (e.g. from "guard" blocks, destructors
667 and so on) will be run without a thread context, and is not allowed
668 to switch to other threads. A common mistake is to call "->cancel"
669 from a destructor called by die'ing inside the thread to be
670 cancelled for example.
671
672 On the plus side, "->cancel" will always clean up the thread, no
673 matter what. If your cleanup code is complex or you want to avoid
674 cancelling a C-thread that doesn't know how to clean up itself, it
675 can be better to "->throw" an exception, or use "->safe_cancel".
676
677 The arguments to "->cancel" are not copied, but instead will be
678 referenced directly (e.g. if you pass $var and after the call change
679 that variable, then you might change the return values passed to
680 e.g. "join", so don't do that).
681
682 The resources of the Coro are usually freed (or destructed) before
683 this call returns, but this can be delayed for an indefinite amount
684 of time, as in some cases the manager thread has to run first to
685 actually destruct the Coro object.
686
687 $coro->safe_cancel ($arg...)
688 Works mostly like "->cancel", but is inherently "safer", and
689 consequently, can fail with an exception in cases the thread is not
690 in a cancellable state. Essentially, "->safe_cancel" is a "->cancel"
691 with extra checks before canceling.
692
693 It works a bit like throwing an exception that cannot be caught -
694 specifically, it will clean up the thread from within itself, so all
695 cleanup handlers (e.g. "guard" blocks) are run with full thread
696 context and can block if they wish. The downside is that there is no
697 guarantee that the thread can be cancelled when you call this
698 method, and therefore, it might fail. It is also considerably slower
699 than "cancel" or "terminate".
700
701 A thread is in a safe-cancellable state if it either hasn't been run
702 yet, or it has no C context attached and is inside an SLF function.
703
704 The latter two basically mean that the thread isn't currently inside
705 a perl callback called from some C function (usually via some XS
706 modules) and isn't currently executing inside some C function itself
707 (via Coro's XS API).
708
709 This call returns true when it could cancel the thread, or croaks
710 with an error otherwise (i.e. it either returns true or doesn't
711 return at all).
712
713 Why the weird interface? Well, there are two common models on how
714 and when to cancel things. In the first, you have the expectation
715 that your coro thread can be cancelled when you want to cancel it -
716 if the thread isn't cancellable, this would be a bug somewhere, so
717 "->safe_cancel" croaks to notify of the bug.
718
719 In the second model you sometimes want to ask nicely to cancel a
720 thread, but if it's not a good time, well, then don't cancel. This
721 can be done relatively easy like this:
722
723 if (! eval { $coro->safe_cancel }) {
724 warn "unable to cancel thread: $@";
725 }
726
727 However, what you never should do is first try to cancel "safely"
728 and if that fails, cancel the "hard" way with "->cancel". That makes
729 no sense: either you rely on being able to execute cleanup code in
730 your thread context, or you don't. If you do, then "->safe_cancel"
731 is the only way, and if you don't, then "->cancel" is always faster
732 and more direct.
733
734 $coro->schedule_to
735 Puts the current coro to sleep (like "Coro::schedule"), but instead
736 of continuing with the next coro from the ready queue, always switch
737 to the given coro object (regardless of priority etc.). The
738 readyness state of that coro isn't changed.
739
740 This is an advanced method for special cases - I'd love to hear
741 about any uses for this one.
742
743 $coro->cede_to
744 Like "schedule_to", but puts the current coro into the ready queue.
745 This has the effect of temporarily switching to the given coro, and
746 continuing some time later.
747
748 This is an advanced method for special cases - I'd love to hear
749 about any uses for this one.
750
751 $coro->throw ([$scalar])
752 If $throw is specified and defined, it will be thrown as an
753 exception inside the coro at the next convenient point in time.
754 Otherwise clears the exception object.
755
756 Coro will check for the exception each time a schedule-like-function
757 returns, i.e. after each "schedule", "cede",
758 "Coro::Semaphore->down", "Coro::Handle->readable" and so on. Most of
759 those functions (all that are part of Coro itself) detect this case
760 and return early in case an exception is pending.
761
762 The exception object will be thrown "as is" with the specified
763 scalar in $@, i.e. if it is a string, no line number or newline will
764 be appended (unlike with "die").
765
766 This can be used as a softer means than either "cancel" or
767 "safe_cancel "to ask a coro to end itself, although there is no
768 guarantee that the exception will lead to termination, and if the
769 exception isn't caught it might well end the whole program.
770
771 You might also think of "throw" as being the moral equivalent of
772 "kill"ing a coro with a signal (in this case, a scalar).
773
774 $coro->join
775 Wait until the coro terminates and return any values given to the
776 "terminate" or "cancel" functions. "join" can be called concurrently
777 from multiple threads, and all will be resumed and given the status
778 return once the $coro terminates.
779
780 $coro->on_destroy (\&cb)
781 Registers a callback that is called when this coro thread gets
782 destroyed, that is, after it's resources have been freed but before
783 it is joined. The callback gets passed the terminate/cancel
784 arguments, if any, and *must not* die, under any circumstances.
785
786 There can be any number of "on_destroy" callbacks per coro, and
787 there is currently no way to remove a callback once added.
788
789 $oldprio = $coro->prio ($newprio)
790 Sets (or gets, if the argument is missing) the priority of the coro
791 thread. Higher priority coro get run before lower priority coros.
792 Priorities are small signed integers (currently -4 .. +3), that you
793 can refer to using PRIO_xxx constants (use the import tag :prio to
794 get then):
795
796 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
797 3 > 1 > 0 > -1 > -3 > -4
798
799 # set priority to HIGH
800 current->prio (PRIO_HIGH);
801
802 The idle coro thread ($Coro::idle) always has a lower priority than
803 any existing coro.
804
805 Changing the priority of the current coro will take effect
806 immediately, but changing the priority of a coro in the ready queue
807 (but not running) will only take effect after the next schedule (of
808 that coro). This is a bug that will be fixed in some future version.
809
810 $newprio = $coro->nice ($change)
811 Similar to "prio", but subtract the given value from the priority
812 (i.e. higher values mean lower priority, just as in UNIX's nice
813 command).
814
815 $olddesc = $coro->desc ($newdesc)
816 Sets (or gets in case the argument is missing) the description for
817 this coro thread. This is just a free-form string you can associate
818 with a coro.
819
820 This method simply sets the "$coro->{desc}" member to the given
821 string. You can modify this member directly if you wish, and in
822 fact, this is often preferred to indicate major processing states
823 that can then be seen for example in a Coro::Debug session:
824
825 sub my_long_function {
826 local $Coro::current->{desc} = "now in my_long_function";
827 ...
828 $Coro::current->{desc} = "my_long_function: phase 1";
829 ...
830 $Coro::current->{desc} = "my_long_function: phase 2";
831 ...
832 }
833
834 GLOBAL FUNCTIONS
835 Coro::nready
836 Returns the number of coro that are currently in the ready state,
837 i.e. that can be switched to by calling "schedule" directory or
838 indirectly. The value 0 means that the only runnable coro is the
839 currently running one, so "cede" would have no effect, and
840 "schedule" would cause a deadlock unless there is an idle handler
841 that wakes up some coro.
842
843 my $guard = Coro::guard { ... }
844 This function still exists, but is deprecated. Please use the
845 "Guard::guard" function instead.
846
847 unblock_sub { ... }
848 This utility function takes a BLOCK or code reference and "unblocks"
849 it, returning a new coderef. Unblocking means that calling the new
850 coderef will return immediately without blocking, returning nothing,
851 while the original code ref will be called (with parameters) from
852 within another coro.
853
854 The reason this function exists is that many event libraries (such
855 as the venerable Event module) are not thread-safe (a weaker form of
856 reentrancy). This means you must not block within event callbacks,
857 otherwise you might suffer from crashes or worse. The only event
858 library currently known that is safe to use without "unblock_sub" is
859 EV (but you might still run into deadlocks if all event loops are
860 blocked).
861
862 Coro will try to catch you when you block in the event loop ("FATAL:
863 $Coro::idle blocked itself"), but this is just best effort and only
864 works when you do not run your own event loop.
865
866 This function allows your callbacks to block by executing them in
867 another coro where it is safe to block. One example where blocking
868 is handy is when you use the Coro::AIO functions to save results to
869 disk, for example.
870
871 In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
872 when creating event callbacks that want to block.
873
874 If your handler does not plan to block (e.g. simply sends a message
875 to another coro, or puts some other coro into the ready queue),
876 there is no reason to use "unblock_sub".
877
878 Note that you also need to use "unblock_sub" for any other callbacks
879 that are indirectly executed by any C-based event loop. For example,
880 when you use a module that uses AnyEvent (and you use
881 Coro::AnyEvent) and it provides callbacks that are the result of
882 some event callback, then you must not block either, or use
883 "unblock_sub".
884
885 $cb = rouse_cb
886 Create and return a "rouse callback". That's a code reference that,
887 when called, will remember a copy of its arguments and notify the
888 owner coro of the callback.
889
890 See the next function.
891
892 @args = rouse_wait [$cb]
893 Wait for the specified rouse callback (or the last one that was
894 created in this coro).
895
896 As soon as the callback is invoked (or when the callback was invoked
897 before "rouse_wait"), it will return the arguments originally passed
898 to the rouse callback. In scalar context, that means you get the
899 *last* argument, just as if "rouse_wait" had a "return ($a1, $a2,
900 $a3...)" statement at the end.
901
902 See the section HOW TO WAIT FOR A CALLBACK for an actual usage
903 example.
904
905 HOW TO WAIT FOR A CALLBACK
906 It is very common for a coro to wait for some callback to be called.
907 This occurs naturally when you use coro in an otherwise event-based
908 program, or when you use event-based libraries.
909
910 These typically register a callback for some event, and call that
911 callback when the event occured. In a coro, however, you typically want
912 to just wait for the event, simplyifying things.
913
914 For example "AnyEvent->child" registers a callback to be called when a
915 specific child has exited:
916
917 my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
918
919 But from within a coro, you often just want to write this:
920
921 my $status = wait_for_child $pid;
922
923 Coro offers two functions specifically designed to make this easy,
924 "rouse_cb" and "rouse_wait".
925
926 The first function, "rouse_cb", generates and returns a callback that,
927 when invoked, will save its arguments and notify the coro that created
928 the callback.
929
930 The second function, "rouse_wait", waits for the callback to be called
931 (by calling "schedule" to go to sleep) and returns the arguments
932 originally passed to the callback.
933
934 Using these functions, it becomes easy to write the "wait_for_child"
935 function mentioned above:
936
937 sub wait_for_child($) {
938 my ($pid) = @_;
939
940 my $watcher = AnyEvent->child (pid => $pid, cb => rouse_cb);
941
942 my ($rpid, $rstatus) = rouse_wait;
943 $rstatus
944 }
945
946 In the case where "rouse_cb" and "rouse_wait" are not flexible enough,
947 you can roll your own, using "schedule" and "ready":
948
949 sub wait_for_child($) {
950 my ($pid) = @_;
951
952 # store the current coro in $current,
953 # and provide result variables for the closure passed to ->child
954 my $current = $Coro::current;
955 my ($done, $rstatus);
956
957 # pass a closure to ->child
958 my $watcher = AnyEvent->child (pid => $pid, cb => sub {
959 $rstatus = $_[1]; # remember rstatus
960 $done = 1; # mark $rstatus as valid
961 $current->ready; # wake up the waiting thread
962 });
963
964 # wait until the closure has been called
965 schedule while !$done;
966
967 $rstatus
968 }
969
970 BUGS/LIMITATIONS
971 fork with pthread backend
972 When Coro is compiled using the pthread backend (which isn't
973 recommended but required on many BSDs as their libcs are completely
974 broken), then coro will not survive a fork. There is no known
975 workaround except to fix your libc and use a saner backend.
976
977 perl process emulation ("threads")
978 This module is not perl-pseudo-thread-safe. You should only ever use
979 this module from the first thread (this requirement might be removed
980 in the future to allow per-thread schedulers, but Coro::State does
981 not yet allow this). I recommend disabling thread support and using
982 processes, as having the windows process emulation enabled under
983 unix roughly halves perl performance, even when not used.
984
985 Attempts to use threads created in another emulated process will
986 crash ("cleanly", with a null pointer exception).
987
988 coro switching is not signal safe
989 You must not switch to another coro from within a signal handler
990 (only relevant with %SIG - most event libraries provide safe
991 signals), *unless* you are sure you are not interrupting a Coro
992 function.
993
994 That means you *MUST NOT* call any function that might "block" the
995 current coro - "cede", "schedule" "Coro::Semaphore->down" or
996 anything that calls those. Everything else, including calling
997 "ready", works.
998
999 WINDOWS PROCESS EMULATION
1000 A great many people seem to be confused about ithreads (for example,
1001 Chip Salzenberg called me unintelligent, incapable, stupid and gullible,
1002 while in the same mail making rather confused statements about perl
1003 ithreads (for example, that memory or files would be shared), showing
1004 his lack of understanding of this area - if it is hard to understand for
1005 Chip, it is probably not obvious to everybody).
1006
1007 What follows is an ultra-condensed version of my talk about threads in
1008 scripting languages given on the perl workshop 2009:
1009
1010 The so-called "ithreads" were originally implemented for two reasons:
1011 first, to (badly) emulate unix processes on native win32 perls, and
1012 secondly, to replace the older, real thread model ("5.005-threads").
1013
1014 It does that by using threads instead of OS processes. The difference
1015 between processes and threads is that threads share memory (and other
1016 state, such as files) between threads within a single process, while
1017 processes do not share anything (at least not semantically). That means
1018 that modifications done by one thread are seen by others, while
1019 modifications by one process are not seen by other processes.
1020
1021 The "ithreads" work exactly like that: when creating a new ithreads
1022 process, all state is copied (memory is copied physically, files and
1023 code is copied logically). Afterwards, it isolates all modifications. On
1024 UNIX, the same behaviour can be achieved by using operating system
1025 processes, except that UNIX typically uses hardware built into the
1026 system to do this efficiently, while the windows process emulation
1027 emulates this hardware in software (rather efficiently, but of course it
1028 is still much slower than dedicated hardware).
1029
1030 As mentioned before, loading code, modifying code, modifying data
1031 structures and so on is only visible in the ithreads process doing the
1032 modification, not in other ithread processes within the same OS process.
1033
1034 This is why "ithreads" do not implement threads for perl at all, only
1035 processes. What makes it so bad is that on non-windows platforms, you
1036 can actually take advantage of custom hardware for this purpose (as
1037 evidenced by the forks module, which gives you the (i-) threads API,
1038 just much faster).
1039
1040 Sharing data is in the i-threads model is done by transfering data
1041 structures between threads using copying semantics, which is very slow -
1042 shared data simply does not exist. Benchmarks using i-threads which are
1043 communication-intensive show extremely bad behaviour with i-threads (in
1044 fact, so bad that Coro, which cannot take direct advantage of multiple
1045 CPUs, is often orders of magnitude faster because it shares data using
1046 real threads, refer to my talk for details).
1047
1048 As summary, i-threads *use* threads to implement processes, while the
1049 compatible forks module *uses* processes to emulate, uhm, processes.
1050 I-threads slow down every perl program when enabled, and outside of
1051 windows, serve no (or little) practical purpose, but disadvantages every
1052 single-threaded Perl program.
1053
1054 This is the reason that I try to avoid the name "ithreads", as it is
1055 misleading as it implies that it implements some kind of thread model
1056 for perl, and prefer the name "windows process emulation", which
1057 describes the actual use and behaviour of it much better.
1058
1059 SEE ALSO
1060 Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event.
1061
1062 Debugging: Coro::Debug.
1063
1064 Support/Utility: Coro::Specific, Coro::Util.
1065
1066 Locking and IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,
1067 Coro::SemaphoreSet, Coro::RWLock.
1068
1069 I/O and Timers: Coro::Timer, Coro::Handle, Coro::Socket, Coro::AIO.
1070
1071 Compatibility with other modules: Coro::LWP (but see also AnyEvent::HTTP
1072 for a better-working alternative), Coro::BDB, Coro::Storable,
1073 Coro::Select.
1074
1075 XS API: Coro::MakeMaker.
1076
1077 Low level Configuration, Thread Environment, Continuations: Coro::State.
1078
1079 AUTHOR
1080 Marc Lehmann <schmorp@schmorp.de>
1081 http://home.schmorp.de/
1082