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

Comparing Coro/Coro.pm (file contents):
Revision 1.229 by root, Thu Nov 20 06:32:55 2008 UTC vs.
Revision 1.240 by root, Tue Nov 25 20:48:41 2008 UTC

1=head1 NAME 1=head1 NAME
2 2
3Coro - coroutine process abstraction 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. Coroutines are similar to 31For a tutorial-style introduction, please read the L<Coro::Intro>
32threads but don't (in general) run in parallel at the same time even 32manpage. This manpage mainly contains reference information.
33on SMP machines. The specific flavor of coroutine used in this module
34also guarantees you that it will not switch between coroutines unless
35necessary, at easily-identified points in your program, so locking and
36parallel access are rarely an issue, making coroutine programming much
37safer and easier than threads programming.
38 33
39Unlike a normal perl program, however, coroutines allow you to have 34This module collection manages continuations in general, most often
40multiple running interpreters that share data, which is especially useful 35in the form of cooperative threads (also called coroutines in the
41to code pseudo-parallel processes and for event-based programming, such as 36documentation). They are similar to kernel threads but don't (in general)
42multiple HTTP-GET requests running concurrently. See L<Coro::AnyEvent> to 37run in parallel at the same time even on SMP machines. The specific flavor
43learn more. 38of thread offered by this module also guarantees you that it will not
39switch between threads unless necessary, at easily-identified points in
40your program, so locking and parallel access are rarely an issue, making
41thread programming much safer and easier than using other thread models.
44 42
45Coroutines are also useful because Perl has no support for threads (the so 43Unlike the so-called "Perl threads" (which are not actually real threads
46called "threads" that perl offers are nothing more than the (bad) process 44but only the windows process emulation ported to unix), Coro provides a
47emulation coming from the Windows platform: On standard operating systems 45full shared address space, which makes communication between threads
48they serve no purpose whatsoever, except by making your programs slow and 46very easy. And threads are fast, too: disabling the Windows process
49making them use a lot of memory. Best disable them when building perl, or 47emulation code in your perl and using Coro can easily result in a two to
50aks your software vendor/distributor to do it for you). 48four times speed increase for your programs.
51 49
50Coro achieves that by supporting multiple running interpreters that share
51data, which is especially useful to code pseudo-parallel processes and
52for event-based programming, such as multiple HTTP-GET requests running
53concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro
54into an event-based environment.
55
52In this module, coroutines are defined as "callchain + lexical variables + 56In this module, a thread is defined as "callchain + lexical variables +
53@_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own callchain, 57@_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain,
54its own set of lexicals and its own set of perls most important global 58its own set of lexicals and its own set of perls most important global
55variables (see L<Coro::State> for more configuration). 59variables (see L<Coro::State> for more configuration and background info).
60
61See also the C<SEE ALSO> section at the end of this document - the Coro
62module family is quite large.
56 63
57=cut 64=cut
58 65
59package Coro; 66package Coro;
60 67
… …
67 74
68our $idle; # idle handler 75our $idle; # idle handler
69our $main; # main coroutine 76our $main; # main coroutine
70our $current; # current coroutine 77our $current; # current coroutine
71 78
72our $VERSION = 5.0; 79our $VERSION = 5.11;
73 80
74our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); 81our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
75our %EXPORT_TAGS = ( 82our %EXPORT_TAGS = (
76 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 83 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
77); 84);
78our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); 85our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
79 86
87=head1 GLOBAL VARIABLES
88
80=over 4 89=over 4
81 90
82=item $Coro::main 91=item $Coro::main
83 92
84This variable stores the coroutine object that represents the main 93This variable stores the coroutine object that represents the main
… …
105sub current() { $current } # [DEPRECATED] 114sub current() { $current } # [DEPRECATED]
106 115
107=item $Coro::idle 116=item $Coro::idle
108 117
109This variable is mainly useful to integrate Coro into event loops. It is 118This variable is mainly useful to integrate Coro into event loops. It is
110usually better to rely on L<Coro::AnyEvent> or LC<Coro::EV>, as this is 119usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is
111pretty low-level functionality. 120pretty low-level functionality.
112 121
113This variable stores a callback that is called whenever the scheduler 122This variable stores either a coroutine or a callback.
123
124If it is a callback, the it is called whenever the scheduler finds no
114finds no ready coroutines to run. The default implementation prints 125ready coroutines to run. The default implementation prints "FATAL:
115"FATAL: deadlock detected" and exits, because the program has no other way 126deadlock detected" and exits, because the program has no other way to
116to continue. 127continue.
117 128
129If it is a coroutine object, then this object will be readied (without
130invoking any ready hooks, however) when the scheduler finds no other ready
131coroutines to run.
132
118This hook is overwritten by modules such as C<Coro::Timer> and 133This hook is overwritten by modules such as C<Coro::EV> and
119C<Coro::AnyEvent> to wait on an external event that hopefully wake up a 134C<Coro::AnyEvent> to wait on an external event that hopefully wake up a
120coroutine so the scheduler can run it. 135coroutine so the scheduler can run it.
121 136
122Note that the callback I<must not>, under any circumstances, block 137Note that the callback I<must not>, under any circumstances, block
123the current coroutine. Normally, this is achieved by having an "idle 138the current coroutine. Normally, this is achieved by having an "idle
124coroutine" that calls the event loop and then blocks again, and then 139coroutine" that calls the event loop and then blocks again, and then
125readying that coroutine in the idle handler. 140readying that coroutine in the idle handler, or by simply placing the idle
141coroutine in this variable.
126 142
127See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this 143See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this
128technique. 144technique.
129 145
130Please note that if your callback recursively invokes perl (e.g. for event 146Please note that if your callback recursively invokes perl (e.g. for event
… …
135$idle = sub { 151$idle = sub {
136 require Carp; 152 require Carp;
137 Carp::croak ("FATAL: deadlock detected"); 153 Carp::croak ("FATAL: deadlock detected");
138}; 154};
139 155
140sub _cancel {
141 my ($self) = @_;
142
143 # free coroutine data and mark as destructed
144 $self->_destroy
145 or return;
146
147 # call all destruction callbacks
148 $_->(@{$self->{_status}})
149 for @{ delete $self->{_on_destroy} || [] };
150}
151
152# this coroutine is necessary because a coroutine 156# this coroutine is necessary because a coroutine
153# cannot destroy itself. 157# cannot destroy itself.
154our @destroy; 158our @destroy;
155our $manager; 159our $manager;
156 160
157$manager = new Coro sub { 161$manager = new Coro sub {
158 while () { 162 while () {
159 (shift @destroy)->_cancel 163 Coro::_cancel shift @destroy
160 while @destroy; 164 while @destroy;
161 165
162 &schedule; 166 &schedule;
163 } 167 }
164}; 168};
165$manager->{desc} = "[coro manager]"; 169$manager->{desc} = "[coro manager]";
166$manager->prio (PRIO_MAX); 170$manager->prio (PRIO_MAX);
167 171
168=back 172=back
169 173
170=head2 SIMPLE COROUTINE CREATION 174=head1 SIMPLE COROUTINE CREATION
171 175
172=over 4 176=over 4
173 177
174=item async { ... } [@args...] 178=item async { ... } [@args...]
175 179
176Create a new coroutine and return it's coroutine object (usually 180Create a new coroutine and return its coroutine object (usually
177unused). The coroutine will be put into the ready queue, so 181unused). The coroutine will be put into the ready queue, so
178it will start running automatically on the next scheduler run. 182it will start running automatically on the next scheduler run.
179 183
180The first argument is a codeblock/closure that should be executed in the 184The first argument is a codeblock/closure that should be executed in the
181coroutine. When it returns argument returns the coroutine is automatically 185coroutine. When it returns argument returns the coroutine is automatically
… …
237coros as required. 241coros as required.
238 242
239If you are concerned about pooled coroutines growing a lot because a 243If you are concerned about pooled coroutines growing a lot because a
240single C<async_pool> used a lot of stackspace you can e.g. C<async_pool 244single C<async_pool> used a lot of stackspace you can e.g. C<async_pool
241{ terminate }> once per second or so to slowly replenish the pool. In 245{ terminate }> once per second or so to slowly replenish the pool. In
242addition to that, when the stacks used by a handler grows larger than 16kb 246addition to that, when the stacks used by a handler grows larger than 32kb
243(adjustable via $Coro::POOL_RSS) it will also be destroyed. 247(adjustable via $Coro::POOL_RSS) it will also be destroyed.
244 248
245=cut 249=cut
246 250
247our $POOL_SIZE = 8; 251our $POOL_SIZE = 8;
248our $POOL_RSS = 16 * 1024; 252our $POOL_RSS = 32 * 1024;
249our @async_pool; 253our @async_pool;
250 254
251sub pool_handler { 255sub pool_handler {
252 while () { 256 while () {
253 eval { 257 eval {
… …
258 } 262 }
259} 263}
260 264
261=back 265=back
262 266
263=head2 STATIC METHODS 267=head1 STATIC METHODS
264 268
265Static methods are actually functions that operate on the current coroutine. 269Static methods are actually functions that implicitly operate on the
270current coroutine.
266 271
267=over 4 272=over 4
268 273
269=item schedule 274=item schedule
270 275
… …
319you cannot free all of them, so if a coroutine that is not the main 324you cannot free all of them, so if a coroutine that is not the main
320program calls this function, there will be some one-time resource leak. 325program calls this function, there will be some one-time resource leak.
321 326
322=cut 327=cut
323 328
324sub terminate {
325 $current->{_status} = [@_];
326 push @destroy, $current;
327 $manager->ready;
328 do { &schedule } while 1;
329}
330
331sub killall { 329sub killall {
332 for (Coro::State::list) { 330 for (Coro::State::list) {
333 $_->cancel 331 $_->cancel
334 if $_ != $current && UNIVERSAL::isa $_, "Coro"; 332 if $_ != $current && UNIVERSAL::isa $_, "Coro";
335 } 333 }
336} 334}
337 335
338=back 336=back
339 337
340=head2 COROUTINE METHODS 338=head1 COROUTINE OBJECT METHODS
341 339
342These are the methods you can call on coroutine objects (or to create 340These are the methods you can call on coroutine objects (or to create
343them). 341them).
344 342
345=over 4 343=over 4
… …
517 my $old = $_[0]{desc}; 515 my $old = $_[0]{desc};
518 $_[0]{desc} = $_[1] if @_ > 1; 516 $_[0]{desc} = $_[1] if @_ > 1;
519 $old; 517 $old;
520} 518}
521 519
520sub transfer {
521 require Carp;
522 Carp::croak ("You must not call ->transfer on Coro objects. Use Coro::State objects or the ->schedule_to method. Caught");
523}
524
522=back 525=back
523 526
524=head2 GLOBAL FUNCTIONS 527=head1 GLOBAL FUNCTIONS
525 528
526=over 4 529=over 4
527 530
528=item Coro::nready 531=item Coro::nready
529 532
… …
576original code ref will be called (with parameters) from within another 579original code ref will be called (with parameters) from within another
577coroutine. 580coroutine.
578 581
579The reason this function exists is that many event libraries (such as the 582The reason this function exists is that many event libraries (such as the
580venerable L<Event|Event> module) are not coroutine-safe (a weaker form 583venerable L<Event|Event> module) are not coroutine-safe (a weaker form
581of thread-safety). This means you must not block within event callbacks, 584of reentrancy). This means you must not block within event callbacks,
582otherwise you might suffer from crashes or worse. The only event library 585otherwise you might suffer from crashes or worse. The only event library
583currently known that is safe to use without C<unblock_sub> is L<EV>. 586currently known that is safe to use without C<unblock_sub> is L<EV>.
584 587
585This function allows your callbacks to block by executing them in another 588This function allows your callbacks to block by executing them in another
586coroutine where it is safe to block. One example where blocking is handy 589coroutine where it is safe to block. One example where blocking is handy
… …
632 } 635 }
633} 636}
634 637
635=item $cb = Coro::rouse_cb 638=item $cb = Coro::rouse_cb
636 639
637Create and return a "rouse callback". That's a code reference that, when 640Create and return a "rouse callback". That's a code reference that,
638called, will save its arguments and notify the owner coroutine of the 641when called, will remember a copy of its arguments and notify the owner
639callback. 642coroutine of the callback.
640 643
641See the next function. 644See the next function.
642 645
643=item @args = Coro::rouse_wait [$cb] 646=item @args = Coro::rouse_wait [$cb]
644 647
645Wait for the specified rouse callback (or the last one tht was created in 648Wait for the specified rouse callback (or the last one that was created in
646this coroutine). 649this coroutine).
647 650
648As soon as the callback is invoked (or when the calback was invoked before 651As soon as the callback is invoked (or when the callback was invoked
649C<rouse_wait>), it will return a copy of the arguments originally passed 652before C<rouse_wait>), it will return the arguments originally passed to
650to the rouse callback. 653the rouse callback.
651 654
652See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example. 655See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
653 656
654=back 657=back
655 658
… …
678 681
679Coro offers two functions specifically designed to make this easy, 682Coro offers two functions specifically designed to make this easy,
680C<Coro::rouse_cb> and C<Coro::rouse_wait>. 683C<Coro::rouse_cb> and C<Coro::rouse_wait>.
681 684
682The first function, C<rouse_cb>, generates and returns a callback that, 685The first function, C<rouse_cb>, generates and returns a callback that,
683when invoked, will save it's arguments and notify the coroutine that 686when invoked, will save its arguments and notify the coroutine that
684created the callback. 687created the callback.
685 688
686The second function, C<rouse_wait>, waits for the callback to be called 689The second function, C<rouse_wait>, waits for the callback to be called
687(by calling C<schedule> to go to sleep) and returns the arguments 690(by calling C<schedule> to go to sleep) and returns the arguments
688originally passed to the callback. 691originally passed to the callback.
… …
735fix your libc and use a saner backend. 738fix your libc and use a saner backend.
736 739
737=item perl process emulation ("threads") 740=item perl process emulation ("threads")
738 741
739This module is not perl-pseudo-thread-safe. You should only ever use this 742This module is not perl-pseudo-thread-safe. You should only ever use this
740module from the same thread (this requirement might be removed in the 743module from the first thread (this requirement might be removed in the
741future to allow per-thread schedulers, but Coro::State does not yet allow 744future to allow per-thread schedulers, but Coro::State does not yet allow
742this). I recommend disabling thread support and using processes, as having 745this). I recommend disabling thread support and using processes, as having
743the windows process emulation enabled under unix roughly halves perl 746the windows process emulation enabled under unix roughly halves perl
744performance, even when not used. 747performance, even when not used.
745 748
… …
762 765
763Debugging: L<Coro::Debug>. 766Debugging: L<Coro::Debug>.
764 767
765Support/Utility: L<Coro::Specific>, L<Coro::Util>. 768Support/Utility: L<Coro::Specific>, L<Coro::Util>.
766 769
767Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>. 770Locking and IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>,
771L<Coro::SemaphoreSet>, L<Coro::RWLock>.
768 772
769IO/Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>. 773I/O and Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>.
770 774
771Compatibility: L<Coro::LWP>, L<Coro::BDB>, L<Coro::Storable>, L<Coro::Select>. 775Compatibility with other modules: L<Coro::LWP> (but see also L<AnyEvent::HTTP> for
776a better-working alternative), L<Coro::BDB>, L<Coro::Storable>,
777L<Coro::Select>.
772 778
773XS API: L<Coro::MakeMaker>. 779XS API: L<Coro::MakeMaker>.
774 780
775Low level Configuration, Coroutine Environment: L<Coro::State>. 781Low level Configuration, Thread Environment, Continuations: L<Coro::State>.
776 782
777=head1 AUTHOR 783=head1 AUTHOR
778 784
779 Marc Lehmann <schmorp@schmorp.de> 785 Marc Lehmann <schmorp@schmorp.de>
780 http://home.schmorp.de/ 786 http://home.schmorp.de/

Diff Legend

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