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

Comparing Coro/Coro.pm (file contents):
Revision 1.121 by root, Fri Apr 13 12:56:55 2007 UTC vs.
Revision 1.141 by root, Tue Oct 2 10:38:17 2007 UTC

… …
20 20
21=head1 DESCRIPTION 21=head1 DESCRIPTION
22 22
23This module collection manages coroutines. Coroutines are similar 23This module collection manages coroutines. Coroutines are similar
24to threads but don't run in parallel at the same time even on SMP 24to threads but don't run in parallel at the same time even on SMP
25machines. The specific flavor of coroutine use din this module also 25machines. The specific flavor of coroutine used in this module also
26guarentees you that it will not switch between coroutines unless 26guarantees you that it will not switch between coroutines unless
27necessary, at easily-identified points in your program, so locking and 27necessary, at easily-identified points in your program, so locking and
28parallel access are rarely an issue, making coroutine programming much 28parallel access are rarely an issue, making coroutine programming much
29safer than threads programming. 29safer than threads programming.
30 30
31(Perl, however, does not natively support real threads but instead does a 31(Perl, however, does not natively support real threads but instead does a
… …
50 50
51our $idle; # idle handler 51our $idle; # idle handler
52our $main; # main coroutine 52our $main; # main coroutine
53our $current; # current coroutine 53our $current; # current coroutine
54 54
55our $VERSION = '3.56'; 55our $VERSION = '3.8';
56 56
57our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); 57our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
58our %EXPORT_TAGS = ( 58our %EXPORT_TAGS = (
59 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 59 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
60); 60);
… …
108 108
109The current coroutine (the last coroutine switched to). The initial value 109The current coroutine (the last coroutine switched to). The initial value
110is C<$main> (of course). 110is C<$main> (of course).
111 111
112This variable is B<strictly> I<read-only>. It is provided for performance 112This variable is B<strictly> I<read-only>. It is provided for performance
113reasons. If performance is not essentiel you are encouraged to use the 113reasons. If performance is not essential you are encouraged to use the
114C<Coro::current> function instead. 114C<Coro::current> function instead.
115 115
116=cut 116=cut
117
118$main->{desc} = "[main::]";
117 119
118# maybe some other module used Coro::Specific before... 120# maybe some other module used Coro::Specific before...
119$main->{specific} = $current->{specific} 121$main->{specific} = $current->{specific}
120 if $current; 122 if $current;
121 123
… …
166 while @destroy; 168 while @destroy;
167 169
168 &schedule; 170 &schedule;
169 } 171 }
170}; 172};
171 173$manager->desc ("[coro manager]");
172$manager->prio (PRIO_MAX); 174$manager->prio (PRIO_MAX);
173 175
174# static methods. not really. 176# static methods. not really.
175 177
176=back 178=back
… …
185 187
186Create a new asynchronous coroutine and return it's coroutine object 188Create a new asynchronous coroutine and return it's coroutine object
187(usually unused). When the sub returns the new coroutine is automatically 189(usually unused). When the sub returns the new coroutine is automatically
188terminated. 190terminated.
189 191
190Calling C<exit> in a coroutine will try to do the same as calling exit 192Calling C<exit> in a coroutine will do the same as calling exit outside
191outside the coroutine, but this is experimental. It is best not to rely on 193the coroutine. Likewise, when the coroutine dies, the program will exit,
192exit doing any cleanups or even not crashing. 194just as it would in the main program.
193
194When the coroutine dies, the program will exit, just as in the main
195program.
196 195
197 # create a new coroutine that just prints its arguments 196 # create a new coroutine that just prints its arguments
198 async { 197 async {
199 print "@_\n"; 198 print "@_\n";
200 } 1,2,3,4; 199 } 1,2,3,4;
… …
225The pool size is limited to 8 idle coroutines (this can be adjusted by 224The pool size is limited to 8 idle coroutines (this can be adjusted by
226changing $Coro::POOL_SIZE), and there can be as many non-idle coros as 225changing $Coro::POOL_SIZE), and there can be as many non-idle coros as
227required. 226required.
228 227
229If you are concerned about pooled coroutines growing a lot because a 228If you are concerned about pooled coroutines growing a lot because a
230single C<async_pool> used a lot of stackspace you can e.g. C<async_pool { 229single C<async_pool> used a lot of stackspace you can e.g. C<async_pool
231terminate }> once per second or so to slowly replenish the pool. 230{ terminate }> once per second or so to slowly replenish the pool. In
231addition to that, when the stacks used by a handler grows larger than 16kb
232(adjustable with $Coro::POOL_RSS) it will also exit.
232 233
233=cut 234=cut
234 235
235our $POOL_SIZE = 8; 236our $POOL_SIZE = 8;
237our $POOL_RSS = 16 * 1024;
236our @pool; 238our @async_pool;
237 239
238sub pool_handler { 240sub pool_handler {
241 my $cb;
242
239 while () { 243 while () {
240 eval { 244 eval {
241 my ($cb, @arg) = @{ delete $current->{_invoke} or return }; 245 while () {
242 $cb->(@arg); 246 _pool_1 $cb;
247 &$cb;
248 _pool_2 $cb;
249 &schedule;
250 }
243 }; 251 };
252
253 last if $@ eq "\3terminate\2\n";
244 warn $@ if $@; 254 warn $@ if $@;
245
246 last if @pool >= $POOL_SIZE;
247 push @pool, $current;
248
249 $current->save (Coro::State::SAVE_DEF);
250 $current->prio (0);
251 schedule;
252 } 255 }
253} 256}
254 257
255sub async_pool(&@) { 258sub async_pool(&@) {
256 # this is also inlined into the unlock_scheduler 259 # this is also inlined into the unlock_scheduler
257 my $coro = (pop @pool or new Coro \&pool_handler); 260 my $coro = (pop @async_pool) || new Coro \&pool_handler;
258 261
259 $coro->{_invoke} = [@_]; 262 $coro->{_invoke} = [@_];
260 $coro->ready; 263 $coro->ready;
261 264
262 $coro 265 $coro
… …
280 # wake up sleeping coroutine 283 # wake up sleeping coroutine
281 $current->ready; 284 $current->ready;
282 undef $current; 285 undef $current;
283 }; 286 };
284 287
285 # call schedule until event occured. 288 # call schedule until event occurred.
286 # in case we are woken up for other reasons 289 # in case we are woken up for other reasons
287 # (current still defined), loop. 290 # (current still defined), loop.
288 Coro::schedule while $current; 291 Coro::schedule while $current;
289 } 292 }
290 293
… …
305 308
306=item terminate [arg...] 309=item terminate [arg...]
307 310
308Terminates the current coroutine with the given status values (see L<cancel>). 311Terminates the current coroutine with the given status values (see L<cancel>).
309 312
313=item killall
314
315Kills/terminates/cancels all coroutines except the currently running
316one. This is useful after a fork, either in the child or the parent, as
317usually only one of them should inherit the running coroutines.
318
310=cut 319=cut
311 320
312sub terminate { 321sub terminate {
313 $current->cancel (@_); 322 $current->cancel (@_);
323}
324
325sub killall {
326 for (Coro::State::list) {
327 $_->cancel
328 if $_ != $current && UNIVERSAL::isa $_, "Coro";
329 }
314} 330}
315 331
316=back 332=back
317 333
318# dynamic methods 334# dynamic methods
… …
461=over 4 477=over 4
462 478
463=item Coro::nready 479=item Coro::nready
464 480
465Returns the number of coroutines that are currently in the ready state, 481Returns the number of coroutines that are currently in the ready state,
466i.e. that can be swicthed to. The value C<0> means that the only runnable 482i.e. that can be switched to. The value C<0> means that the only runnable
467coroutine is the currently running one, so C<cede> would have no effect, 483coroutine is the currently running one, so C<cede> would have no effect,
468and C<schedule> would cause a deadlock unless there is an idle handler 484and C<schedule> would cause a deadlock unless there is an idle handler
469that wakes up some coroutines. 485that wakes up some coroutines.
470 486
471=item my $guard = Coro::guard { ... } 487=item my $guard = Coro::guard { ... }
… …
507This utility function takes a BLOCK or code reference and "unblocks" it, 523This utility function takes a BLOCK or code reference and "unblocks" it,
508returning the new coderef. This means that the new coderef will return 524returning the new coderef. This means that the new coderef will return
509immediately without blocking, returning nothing, while the original code 525immediately without blocking, returning nothing, while the original code
510ref will be called (with parameters) from within its own coroutine. 526ref will be called (with parameters) from within its own coroutine.
511 527
512The reason this fucntion exists is that many event libraries (such as the 528The reason this function exists is that many event libraries (such as the
513venerable L<Event|Event> module) are not coroutine-safe (a weaker form 529venerable L<Event|Event> module) are not coroutine-safe (a weaker form
514of thread-safety). This means you must not block within event callbacks, 530of thread-safety). This means you must not block within event callbacks,
515otherwise you might suffer from crashes or worse. 531otherwise you might suffer from crashes or worse.
516 532
517This function allows your callbacks to block by executing them in another 533This function allows your callbacks to block by executing them in another
… …
528 544
529# we create a special coro because we want to cede, 545# we create a special coro because we want to cede,
530# to reduce pressure on the coro pool (because most callbacks 546# to reduce pressure on the coro pool (because most callbacks
531# return immediately and can be reused) and because we cannot cede 547# return immediately and can be reused) and because we cannot cede
532# inside an event callback. 548# inside an event callback.
533our $unblock_scheduler = async { 549our $unblock_scheduler = new Coro sub {
534 while () { 550 while () {
535 while (my $cb = pop @unblock_queue) { 551 while (my $cb = pop @unblock_queue) {
536 # this is an inlined copy of async_pool 552 # this is an inlined copy of async_pool
537 my $coro = (pop @pool or new Coro \&pool_handler); 553 my $coro = (pop @async_pool) || new Coro \&pool_handler;
538 554
539 $coro->{_invoke} = $cb; 555 $coro->{_invoke} = $cb;
540 $coro->ready; 556 $coro->ready;
541 cede; # for short-lived callbacks, this reduces pressure on the coro pool 557 cede; # for short-lived callbacks, this reduces pressure on the coro pool
542 } 558 }
543 schedule; # sleep well 559 schedule; # sleep well
544 } 560 }
545}; 561};
562$unblock_scheduler->desc ("[unblock_sub scheduler]");
546 563
547sub unblock_sub(&) { 564sub unblock_sub(&) {
548 my $cb = shift; 565 my $cb = shift;
549 566
550 sub { 567 sub {
… …
563 580
564 - you must make very sure that no coro is still active on global 581 - you must make very sure that no coro is still active on global
565 destruction. very bad things might happen otherwise (usually segfaults). 582 destruction. very bad things might happen otherwise (usually segfaults).
566 583
567 - this module is not thread-safe. You should only ever use this module 584 - this module is not thread-safe. You should only ever use this module
568 from the same thread (this requirement might be losened in the future 585 from the same thread (this requirement might be loosened in the future
569 to allow per-thread schedulers, but Coro::State does not yet allow 586 to allow per-thread schedulers, but Coro::State does not yet allow
570 this). 587 this).
571 588
572=head1 SEE ALSO 589=head1 SEE ALSO
573 590

Diff Legend

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