ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/Coro/Coro.pm
(Generate patch)

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.235 by root, Fri Nov 21 06:54:51 2008 UTC vs.
Revision 1.247 by root, Mon Dec 15 02:07:11 2008 UTC

1=head1 NAME 1=head1 NAME
2 2
3Coro - the real perl threads 3Coro - the only real threads in perl
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use Coro; 7 use Coro;
8 8
… …
26 $locked = 1; 26 $locked = 1;
27 $lock->up; 27 $lock->up;
28 28
29=head1 DESCRIPTION 29=head1 DESCRIPTION
30 30
31This module collection manages coroutines, that is, cooperative 31For a tutorial-style introduction, please read the L<Coro::Intro>
32threads. Coroutines are similar to kernel threads but don't (in general) 32manpage. This manpage mainly contains reference information.
33
34This module collection manages continuations in general, most often
35in the form of cooperative threads (also called coroutines in the
36documentation). They are similar to kernel threads but don't (in general)
33run in parallel at the same time even on SMP machines. The specific flavor 37run in parallel at the same time even on SMP machines. The specific flavor
34of coroutine used in this module also guarantees you that it will not 38of thread offered by this module also guarantees you that it will not
35switch between coroutines unless necessary, at easily-identified points 39switch between threads unless necessary, at easily-identified points in
36in your program, so locking and parallel access are rarely an issue, 40your program, so locking and parallel access are rarely an issue, making
37making coroutine programming much safer and easier than using other thread 41thread programming much safer and easier than using other thread models.
38models.
39 42
40Unlike the so-called "Perl threads" (which are not actually real threads 43Unlike the so-called "Perl threads" (which are not actually real threads
41but only the windows process emulation ported to unix), Coro provides a 44but only the windows process emulation ported to unix), Coro provides a
42full shared address space, which makes communication between coroutines 45full shared address space, which makes communication between threads
43very easy. And coroutines are fast, too: disabling the Windows process 46very easy. And threads are fast, too: disabling the Windows process
44emulation code in your perl and using Coro can easily result in a two to 47emulation code in your perl and using Coro can easily result in a two to
45four times speed increase for your programs. 48four times speed increase for your programs.
46 49
47Coro achieves that by supporting multiple running interpreters that share 50Coro achieves that by supporting multiple running interpreters that share
48data, which is especially useful to code pseudo-parallel processes and 51data, which is especially useful to code pseudo-parallel processes and
49for event-based programming, such as multiple HTTP-GET requests running 52for event-based programming, such as multiple HTTP-GET requests running
50concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro 53concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro
51into an event-based environment. 54into an event-based environment.
52 55
53In this module, a coroutines is defined as "callchain + lexical variables 56In this module, a thread is defined as "callchain + lexical variables +
54+ @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own 57@_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain,
55callchain, its own set of lexicals and its own set of perls most important 58its own set of lexicals and its own set of perls most important global
56global variables (see L<Coro::State> for more configuration and background 59variables (see L<Coro::State> for more configuration and background info).
57info).
58 60
59See also the C<SEE ALSO> section at the end of this document - the Coro 61See also the C<SEE ALSO> section at the end of this document - the Coro
60module family is quite large. 62module family is quite large.
61 63
62=cut 64=cut
63 65
64package Coro; 66package Coro;
65 67
66use strict qw(vars subs); 68use strict qw(vars subs);
67no warnings "uninitialized"; 69no warnings "uninitialized";
70
71use Guard ();
68 72
69use Coro::State; 73use Coro::State;
70 74
71use base qw(Coro::State Exporter); 75use base qw(Coro::State Exporter);
72 76
73our $idle; # idle handler 77our $idle; # idle handler
74our $main; # main coroutine 78our $main; # main coroutine
75our $current; # current coroutine 79our $current; # current coroutine
76 80
77our $VERSION = "5.0"; 81our $VERSION = 5.13;
78 82
79our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); 83our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
80our %EXPORT_TAGS = ( 84our %EXPORT_TAGS = (
81 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 85 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
82); 86);
… …
112sub current() { $current } # [DEPRECATED] 116sub current() { $current } # [DEPRECATED]
113 117
114=item $Coro::idle 118=item $Coro::idle
115 119
116This variable is mainly useful to integrate Coro into event loops. It is 120This variable is mainly useful to integrate Coro into event loops. It is
117usually better to rely on L<Coro::AnyEvent> or LC<Coro::EV>, as this is 121usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is
118pretty low-level functionality. 122pretty low-level functionality.
119 123
120This variable stores a callback that is called whenever the scheduler 124This variable stores either a coroutine or a callback.
125
126If it is a callback, the it is called whenever the scheduler finds no
121finds no ready coroutines to run. The default implementation prints 127ready coroutines to run. The default implementation prints "FATAL:
122"FATAL: deadlock detected" and exits, because the program has no other way 128deadlock detected" and exits, because the program has no other way to
123to continue. 129continue.
124 130
131If it is a coroutine object, then this object will be readied (without
132invoking any ready hooks, however) when the scheduler finds no other ready
133coroutines to run.
134
125This hook is overwritten by modules such as C<Coro::Timer> and 135This hook is overwritten by modules such as C<Coro::EV> and
126C<Coro::AnyEvent> to wait on an external event that hopefully wake up a 136C<Coro::AnyEvent> to wait on an external event that hopefully wake up a
127coroutine so the scheduler can run it. 137coroutine so the scheduler can run it.
128 138
129Note that the callback I<must not>, under any circumstances, block 139Note that the callback I<must not>, under any circumstances, block
130the current coroutine. Normally, this is achieved by having an "idle 140the current coroutine. Normally, this is achieved by having an "idle
131coroutine" that calls the event loop and then blocks again, and then 141coroutine" that calls the event loop and then blocks again, and then
132readying that coroutine in the idle handler. 142readying that coroutine in the idle handler, or by simply placing the idle
143coroutine in this variable.
133 144
134See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this 145See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this
135technique. 146technique.
136 147
137Please note that if your callback recursively invokes perl (e.g. for event 148Please note that if your callback recursively invokes perl (e.g. for event
… …
166 177
167=over 4 178=over 4
168 179
169=item async { ... } [@args...] 180=item async { ... } [@args...]
170 181
171Create a new coroutine and return it's coroutine object (usually 182Create a new coroutine and return its coroutine object (usually
172unused). The coroutine will be put into the ready queue, so 183unused). The coroutine will be put into the ready queue, so
173it will start running automatically on the next scheduler run. 184it will start running automatically on the next scheduler run.
174 185
175The first argument is a codeblock/closure that should be executed in the 186The first argument is a codeblock/closure that should be executed in the
176coroutine. When it returns argument returns the coroutine is automatically 187coroutine. When it returns argument returns the coroutine is automatically
… …
303 314
304=item terminate [arg...] 315=item terminate [arg...]
305 316
306Terminates the current coroutine with the given status values (see L<cancel>). 317Terminates the current coroutine with the given status values (see L<cancel>).
307 318
319=item Coro::on_enter BLOCK, Coro::on_leave BLOCK
320
321These function install enter and leave winders in the current scope. The
322enter block will be executed when on_enter is called and whenever the
323current coroutine is re-entered by the scheduler, while the leave block is
324executed whenever the current coroutine is blocked by the scheduler, and
325also when the containing scope is exited (by whatever means, be it exit,
326die, last etc.).
327
328I<Neither invoking the scheduler, nor exceptions, are allowed within those
329BLOCKs>. That means: do not even think about calling C<die> without an
330eval, and do not even think of entering the scheduler in any way.
331
332Since both BLOCKs are tied to the current scope, they will automatically
333be removed when the current scope exits.
334
335These functions implement the same concept as C<dynamic-wind> in scheme
336does, and are useful when you want to localise some resource to a specific
337coroutine.
338
339They slow down coroutine switching considerably for coroutines that use
340them (But coroutine switching is still reasonably fast if the handlers are
341fast).
342
343These functions are best understood by an example: The following function
344will change the current timezone to "Antarctica/South_Pole", which
345requires a call to C<tzset>, but by using C<on_enter> and C<on_leave>,
346which remember/change the current timezone and restore the previous
347value, respectively, the timezone is only changes for the coroutine that
348installed those handlers.
349
350 use POSIX qw(tzset);
351
352 async {
353 my $old_tz; # store outside TZ value here
354
355 Coro::on_enter {
356 $old_tz = $ENV{TZ}; # remember the old value
357
358 $ENV{TZ} = "Antarctica/South_Pole";
359 tzset; # enable new value
360 };
361
362 Coro::on_leave {
363 $ENV{TZ} = $old_tz;
364 tzset; # restore old value
365 };
366
367 # at this place, the timezone is Antarctica/South_Pole,
368 # without disturbing the TZ of any other coroutine.
369 };
370
371This can be used to localise about any resource (locale, uid, current
372working directory etc.) to a block, despite the existance of other
373coroutines.
374
308=item killall 375=item killall
309 376
310Kills/terminates/cancels all coroutines except the currently running 377Kills/terminates/cancels all coroutines except the currently running one.
311one. This is useful after a fork, either in the child or the parent, as
312usually only one of them should inherit the running coroutines.
313 378
314Note that while this will try to free some of the main programs resources, 379Note that while this will try to free some of the main interpreter
380resources if the calling coroutine isn't the main coroutine, but one
315you cannot free all of them, so if a coroutine that is not the main 381cannot free all of them, so if a coroutine that is not the main coroutine
316program calls this function, there will be some one-time resource leak. 382calls this function, there will be some one-time resource leak.
317 383
318=cut 384=cut
319 385
320sub killall { 386sub killall {
321 for (Coro::State::list) { 387 for (Coro::State::list) {
… …
343See C<async> and C<Coro::State::new> for additional info about the 409See C<async> and C<Coro::State::new> for additional info about the
344coroutine environment. 410coroutine environment.
345 411
346=cut 412=cut
347 413
348sub _terminate { 414sub _coro_run {
349 terminate &{+shift}; 415 terminate &{+shift};
350} 416}
351 417
352=item $success = $coroutine->ready 418=item $success = $coroutine->ready
353 419
… …
528would cause a deadlock unless there is an idle handler that wakes up some 594would cause a deadlock unless there is an idle handler that wakes up some
529coroutines. 595coroutines.
530 596
531=item my $guard = Coro::guard { ... } 597=item my $guard = Coro::guard { ... }
532 598
533This creates and returns a guard object. Nothing happens until the object 599This function still exists, but is deprecated. Please use the
534gets destroyed, in which case the codeblock given as argument will be 600C<Guard::guard> function instead.
535executed. This is useful to free locks or other resources in case of a
536runtime error or when the coroutine gets canceled, as in both cases the
537guard block will be executed. The guard object supports only one method,
538C<< ->cancel >>, which will keep the codeblock from being executed.
539 601
540Example: set some flag and clear it again when the coroutine gets canceled
541or the function returns:
542
543 sub do_something {
544 my $guard = Coro::guard { $busy = 0 };
545 $busy = 1;
546
547 # do something that requires $busy to be true
548 }
549
550=cut 602=cut
551 603
552sub guard(&) { 604BEGIN { *guard = \&Guard::guard }
553 bless \(my $cb = $_[0]), "Coro::guard"
554}
555
556sub Coro::guard::cancel {
557 ${$_[0]} = sub { };
558}
559
560sub Coro::guard::DESTROY {
561 ${$_[0]}->();
562}
563
564 605
565=item unblock_sub { ... } 606=item unblock_sub { ... }
566 607
567This utility function takes a BLOCK or code reference and "unblocks" it, 608This utility function takes a BLOCK or code reference and "unblocks" it,
568returning a new coderef. Unblocking means that calling the new coderef 609returning a new coderef. Unblocking means that calling the new coderef
… …
570original code ref will be called (with parameters) from within another 611original code ref will be called (with parameters) from within another
571coroutine. 612coroutine.
572 613
573The reason this function exists is that many event libraries (such as the 614The reason this function exists is that many event libraries (such as the
574venerable L<Event|Event> module) are not coroutine-safe (a weaker form 615venerable L<Event|Event> module) are not coroutine-safe (a weaker form
575of thread-safety). This means you must not block within event callbacks, 616of reentrancy). This means you must not block within event callbacks,
576otherwise you might suffer from crashes or worse. The only event library 617otherwise you might suffer from crashes or worse. The only event library
577currently known that is safe to use without C<unblock_sub> is L<EV>. 618currently known that is safe to use without C<unblock_sub> is L<EV>.
578 619
579This function allows your callbacks to block by executing them in another 620This function allows your callbacks to block by executing them in another
580coroutine where it is safe to block. One example where blocking is handy 621coroutine where it is safe to block. One example where blocking is handy
… …
626 } 667 }
627} 668}
628 669
629=item $cb = Coro::rouse_cb 670=item $cb = Coro::rouse_cb
630 671
631Create and return a "rouse callback". That's a code reference that, when 672Create and return a "rouse callback". That's a code reference that,
632called, will save its arguments and notify the owner coroutine of the 673when called, will remember a copy of its arguments and notify the owner
633callback. 674coroutine of the callback.
634 675
635See the next function. 676See the next function.
636 677
637=item @args = Coro::rouse_wait [$cb] 678=item @args = Coro::rouse_wait [$cb]
638 679
639Wait for the specified rouse callback (or the last one tht was created in 680Wait for the specified rouse callback (or the last one that was created in
640this coroutine). 681this coroutine).
641 682
642As soon as the callback is invoked (or when the calback was invoked before 683As soon as the callback is invoked (or when the callback was invoked
643C<rouse_wait>), it will return a copy of the arguments originally passed 684before C<rouse_wait>), it will return the arguments originally passed to
644to the rouse callback. 685the rouse callback.
645 686
646See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example. 687See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
647 688
648=back 689=back
649 690
… …
672 713
673Coro offers two functions specifically designed to make this easy, 714Coro offers two functions specifically designed to make this easy,
674C<Coro::rouse_cb> and C<Coro::rouse_wait>. 715C<Coro::rouse_cb> and C<Coro::rouse_wait>.
675 716
676The first function, C<rouse_cb>, generates and returns a callback that, 717The first function, C<rouse_cb>, generates and returns a callback that,
677when invoked, will save it's arguments and notify the coroutine that 718when invoked, will save its arguments and notify the coroutine that
678created the callback. 719created the callback.
679 720
680The second function, C<rouse_wait>, waits for the callback to be called 721The second function, C<rouse_wait>, waits for the callback to be called
681(by calling C<schedule> to go to sleep) and returns the arguments 722(by calling C<schedule> to go to sleep) and returns the arguments
682originally passed to the callback. 723originally passed to the callback.
… …
729fix your libc and use a saner backend. 770fix your libc and use a saner backend.
730 771
731=item perl process emulation ("threads") 772=item perl process emulation ("threads")
732 773
733This module is not perl-pseudo-thread-safe. You should only ever use this 774This module is not perl-pseudo-thread-safe. You should only ever use this
734module from the same thread (this requirement might be removed in the 775module from the first thread (this requirement might be removed in the
735future to allow per-thread schedulers, but Coro::State does not yet allow 776future to allow per-thread schedulers, but Coro::State does not yet allow
736this). I recommend disabling thread support and using processes, as having 777this). I recommend disabling thread support and using processes, as having
737the windows process emulation enabled under unix roughly halves perl 778the windows process emulation enabled under unix roughly halves perl
738performance, even when not used. 779performance, even when not used.
739 780
… …
756 797
757Debugging: L<Coro::Debug>. 798Debugging: L<Coro::Debug>.
758 799
759Support/Utility: L<Coro::Specific>, L<Coro::Util>. 800Support/Utility: L<Coro::Specific>, L<Coro::Util>.
760 801
761Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, 802Locking and IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>,
762L<Coro::SemaphoreSet>, L<Coro::RWLock>. 803L<Coro::SemaphoreSet>, L<Coro::RWLock>.
763 804
764IO/Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>. 805I/O and Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>.
765 806
766Compatibility: L<Coro::LWP> (but see also L<AnyEvent::HTTP> for 807Compatibility with other modules: L<Coro::LWP> (but see also L<AnyEvent::HTTP> for
767a better-working alternative), L<Coro::BDB>, L<Coro::Storable>, 808a better-working alternative), L<Coro::BDB>, L<Coro::Storable>,
768L<Coro::Select>. 809L<Coro::Select>.
769 810
770XS API: L<Coro::MakeMaker>. 811XS API: L<Coro::MakeMaker>.
771 812
772Low level Configuration, Coroutine Environment: L<Coro::State>. 813Low level Configuration, Thread Environment, Continuations: L<Coro::State>.
773 814
774=head1 AUTHOR 815=head1 AUTHOR
775 816
776 Marc Lehmann <schmorp@schmorp.de> 817 Marc Lehmann <schmorp@schmorp.de>
777 http://home.schmorp.de/ 818 http://home.schmorp.de/

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines