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.226 by root, Wed Nov 19 16:01:32 2008 UTC vs.
Revision 1.235 by root, Fri Nov 21 06:54:51 2008 UTC

1=head1 NAME 1=head1 NAME
2 2
3Coro - coroutine process abstraction 3Coro - the real perl threads
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 31This module collection manages coroutines, that is, cooperative
32threads but don't (in general) run in parallel at the same time even 32threads. Coroutines are similar to kernel threads but don't (in general)
33on SMP machines. The specific flavor of coroutine used in this module 33run in parallel at the same time even on SMP machines. The specific flavor
34also guarantees you that it will not switch between coroutines unless 34of coroutine used in this module also guarantees you that it will not
35necessary, at easily-identified points in your program, so locking and 35switch between coroutines unless necessary, at easily-identified points
36parallel access are rarely an issue, making coroutine programming much 36in your program, so locking and parallel access are rarely an issue,
37safer and easier than threads programming. 37making coroutine programming much safer and easier than using other thread
38models.
38 39
39Unlike a normal perl program, however, coroutines allow you to have 40Unlike the so-called "Perl threads" (which are not actually real threads
40multiple running interpreters that share data, which is especially useful 41but only the windows process emulation ported to unix), Coro provides a
41to code pseudo-parallel processes and for event-based programming, such as 42full shared address space, which makes communication between coroutines
42multiple HTTP-GET requests running concurrently. See L<Coro::AnyEvent> to 43very easy. And coroutines are fast, too: disabling the Windows process
43learn more. 44emulation code in your perl and using Coro can easily result in a two to
45four times speed increase for your programs.
44 46
45Coroutines are also useful because Perl has no support for threads (the so 47Coro achieves that by supporting multiple running interpreters that share
46called "threads" that perl offers are nothing more than the (bad) process 48data, which is especially useful to code pseudo-parallel processes and
47emulation coming from the Windows platform: On standard operating systems 49for event-based programming, such as multiple HTTP-GET requests running
48they serve no purpose whatsoever, except by making your programs slow and 50concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro
49making them use a lot of memory. Best disable them when building perl, or 51into an event-based environment.
50aks your software vendor/distributor to do it for you).
51 52
52In this module, coroutines are defined as "callchain + lexical variables + 53In this module, a coroutines is defined as "callchain + lexical variables
53@_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own callchain, 54+ @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own
54its own set of lexicals and its own set of perls most important global 55callchain, its own set of lexicals and its own set of perls most important
55variables (see L<Coro::State> for more configuration). 56global variables (see L<Coro::State> for more configuration and background
57info).
58
59See also the C<SEE ALSO> section at the end of this document - the Coro
60module family is quite large.
56 61
57=cut 62=cut
58 63
59package Coro; 64package Coro;
60 65
… …
67 72
68our $idle; # idle handler 73our $idle; # idle handler
69our $main; # main coroutine 74our $main; # main coroutine
70our $current; # current coroutine 75our $current; # current coroutine
71 76
72our $VERSION = 5.0; 77our $VERSION = "5.0";
73 78
74our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); 79our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
75our %EXPORT_TAGS = ( 80our %EXPORT_TAGS = (
76 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 81 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
77); 82);
78our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); 83our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
79 84
85=head1 GLOBAL VARIABLES
86
80=over 4 87=over 4
81 88
82=item $Coro::main 89=item $Coro::main
83 90
84This variable stores the coroutine object that represents the main 91This variable stores the coroutine object that represents the main
… …
135$idle = sub { 142$idle = sub {
136 require Carp; 143 require Carp;
137 Carp::croak ("FATAL: deadlock detected"); 144 Carp::croak ("FATAL: deadlock detected");
138}; 145};
139 146
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 147# this coroutine is necessary because a coroutine
153# cannot destroy itself. 148# cannot destroy itself.
154our @destroy; 149our @destroy;
155our $manager; 150our $manager;
156 151
157$manager = new Coro sub { 152$manager = new Coro sub {
158 while () { 153 while () {
159 (shift @destroy)->_cancel 154 Coro::_cancel shift @destroy
160 while @destroy; 155 while @destroy;
161 156
162 &schedule; 157 &schedule;
163 } 158 }
164}; 159};
165$manager->{desc} = "[coro manager]"; 160$manager->{desc} = "[coro manager]";
166$manager->prio (PRIO_MAX); 161$manager->prio (PRIO_MAX);
167 162
168=back 163=back
169 164
170=head2 SIMPLE COROUTINE CREATION 165=head1 SIMPLE COROUTINE CREATION
171 166
172=over 4 167=over 4
173 168
174=item async { ... } [@args...] 169=item async { ... } [@args...]
175 170
… …
212Similar to C<async>, but uses a coroutine pool, so you should not call 207Similar to C<async>, but uses a coroutine pool, so you should not call
213terminate or join on it (although you are allowed to), and you get a 208terminate or join on it (although you are allowed to), and you get a
214coroutine that might have executed other code already (which can be good 209coroutine that might have executed other code already (which can be good
215or bad :). 210or bad :).
216 211
217On the plus side, this function is faster than creating (and destroying) 212On the plus side, this function is about twice as fast as creating (and
218a completly new coroutine, so if you need a lot of generic coroutines in 213destroying) a completely new coroutine, so if you need a lot of generic
219quick successsion, use C<async_pool>, not C<async>. 214coroutines in quick successsion, use C<async_pool>, not C<async>.
220 215
221The code block is executed in an C<eval> context and a warning will be 216The code block is executed in an C<eval> context and a warning will be
222issued in case of an exception instead of terminating the program, as 217issued in case of an exception instead of terminating the program, as
223C<async> does. As the coroutine is being reused, stuff like C<on_destroy> 218C<async> does. As the coroutine is being reused, stuff like C<on_destroy>
224will not work in the expected way, unless you call terminate or cancel, 219will not work in the expected way, unless you call terminate or cancel,
… …
237coros as required. 232coros as required.
238 233
239If you are concerned about pooled coroutines growing a lot because a 234If 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 235single 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 236{ 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 237addition to that, when the stacks used by a handler grows larger than 32kb
243(adjustable via $Coro::POOL_RSS) it will also be destroyed. 238(adjustable via $Coro::POOL_RSS) it will also be destroyed.
244 239
245=cut 240=cut
246 241
247our $POOL_SIZE = 8; 242our $POOL_SIZE = 8;
248our $POOL_RSS = 16 * 1024; 243our $POOL_RSS = 32 * 1024;
249our @async_pool; 244our @async_pool;
250 245
251sub pool_handler { 246sub pool_handler {
252 my $cb;
253
254 while () { 247 while () {
255 eval { 248 eval {
256 while () { 249 &{&_pool_handler} while 1;
257 _pool_1 $cb;
258 &$cb;
259 _pool_2 $cb;
260 &schedule;
261 }
262 }; 250 };
263 251
264 if ($@) {
265 last if $@ eq "\3async_pool terminate\2\n";
266 warn $@; 252 warn $@ if $@;
267 }
268 } 253 }
269}
270
271sub async_pool(&@) {
272 # this is also inlined into the unblock_scheduler
273 my $coro = (pop @async_pool) || new Coro \&pool_handler;
274
275 $coro->{_invoke} = [@_];
276 $coro->ready;
277
278 $coro
279} 254}
280 255
281=back 256=back
282 257
283=head2 STATIC METHODS 258=head1 STATIC METHODS
284 259
285Static methods are actually functions that operate on the current coroutine. 260Static methods are actually functions that implicitly operate on the
261current coroutine.
286 262
287=over 4 263=over 4
288 264
289=item schedule 265=item schedule
290 266
… …
339you cannot free all of them, so if a coroutine that is not the main 315you cannot free all of them, so if a coroutine that is not the main
340program calls this function, there will be some one-time resource leak. 316program calls this function, there will be some one-time resource leak.
341 317
342=cut 318=cut
343 319
344sub terminate {
345 $current->{_status} = [@_];
346 push @destroy, $current;
347 $manager->ready;
348 do { &schedule } while 1;
349}
350
351sub killall { 320sub killall {
352 for (Coro::State::list) { 321 for (Coro::State::list) {
353 $_->cancel 322 $_->cancel
354 if $_ != $current && UNIVERSAL::isa $_, "Coro"; 323 if $_ != $current && UNIVERSAL::isa $_, "Coro";
355 } 324 }
356} 325}
357 326
358=back 327=back
359 328
360=head2 COROUTINE METHODS 329=head1 COROUTINE OBJECT METHODS
361 330
362These are the methods you can call on coroutine objects (or to create 331These are the methods you can call on coroutine objects (or to create
363them). 332them).
364 333
365=over 4 334=over 4
… …
411 $self->{_status} = [@_]; 380 $self->{_status} = [@_];
412 $self->_cancel; 381 $self->_cancel;
413 } 382 }
414} 383}
415 384
385=item $coroutine->schedule_to
386
387Puts the current coroutine to sleep (like C<Coro::schedule>), but instead
388of continuing with the next coro from the ready queue, always switch to
389the given coroutine object (regardless of priority etc.). The readyness
390state of that coroutine isn't changed.
391
392This is an advanced method for special cases - I'd love to hear about any
393uses for this one.
394
395=item $coroutine->cede_to
396
397Like C<schedule_to>, but puts the current coroutine into the ready
398queue. This has the effect of temporarily switching to the given
399coroutine, and continuing some time later.
400
401This is an advanced method for special cases - I'd love to hear about any
402uses for this one.
403
416=item $coroutine->throw ([$scalar]) 404=item $coroutine->throw ([$scalar])
417 405
418If C<$throw> is specified and defined, it will be thrown as an exception 406If C<$throw> is specified and defined, it will be thrown as an exception
419inside the coroutine at the next convenient point in time. Otherwise 407inside the coroutine at the next convenient point in time. Otherwise
420clears the exception object. 408clears the exception object.
… …
518 my $old = $_[0]{desc}; 506 my $old = $_[0]{desc};
519 $_[0]{desc} = $_[1] if @_ > 1; 507 $_[0]{desc} = $_[1] if @_ > 1;
520 $old; 508 $old;
521} 509}
522 510
511sub transfer {
512 require Carp;
513 Carp::croak ("You must not call ->transfer on Coro objects. Use Coro::State objects or the ->schedule_to method. Caught");
514}
515
523=back 516=back
524 517
525=head2 GLOBAL FUNCTIONS 518=head1 GLOBAL FUNCTIONS
526 519
527=over 4 520=over 4
528 521
529=item Coro::nready 522=item Coro::nready
530 523
… …
610# return immediately and can be reused) and because we cannot cede 603# return immediately and can be reused) and because we cannot cede
611# inside an event callback. 604# inside an event callback.
612our $unblock_scheduler = new Coro sub { 605our $unblock_scheduler = new Coro sub {
613 while () { 606 while () {
614 while (my $cb = pop @unblock_queue) { 607 while (my $cb = pop @unblock_queue) {
615 # this is an inlined copy of async_pool 608 &async_pool (@$cb);
616 my $coro = (pop @async_pool) || new Coro \&pool_handler;
617 609
618 $coro->{_invoke} = $cb;
619 $coro->ready;
620 cede; # for short-lived callbacks, this reduces pressure on the coro pool 610 # for short-lived callbacks, this reduces pressure on the coro pool
611 # as the chance is very high that the async_poll coro will be back
612 # in the idle state when cede returns
613 cede;
621 } 614 }
622 schedule; # sleep well 615 schedule; # sleep well
623 } 616 }
624}; 617};
625$unblock_scheduler->{desc} = "[unblock_sub scheduler]"; 618$unblock_scheduler->{desc} = "[unblock_sub scheduler]";
… …
763 756
764Debugging: L<Coro::Debug>. 757Debugging: L<Coro::Debug>.
765 758
766Support/Utility: L<Coro::Specific>, L<Coro::Util>. 759Support/Utility: L<Coro::Specific>, L<Coro::Util>.
767 760
768Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>. 761Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>,
762L<Coro::SemaphoreSet>, L<Coro::RWLock>.
769 763
770IO/Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>. 764IO/Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>.
771 765
772Compatibility: L<Coro::LWP>, L<Coro::BDB>, L<Coro::Storable>, L<Coro::Select>. 766Compatibility: L<Coro::LWP> (but see also L<AnyEvent::HTTP> for
767a better-working alternative), L<Coro::BDB>, L<Coro::Storable>,
768L<Coro::Select>.
773 769
774XS API: L<Coro::MakeMaker>. 770XS API: L<Coro::MakeMaker>.
775 771
776Low level Configuration, Coroutine Environment: L<Coro::State>. 772Low level Configuration, Coroutine Environment: L<Coro::State>.
777 773

Diff Legend

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