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

Comparing Coro/Coro.pm (file contents):
Revision 1.114 by root, Wed Jan 24 16:22:08 2007 UTC vs.
Revision 1.134 by root, Sat Sep 22 14:42:56 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.5'; 55our $VERSION = '3.7';
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 not work correctly, so do not do that. 192Calling C<exit> in a coroutine will do the same as calling exit outside
191 193the coroutine. Likewise, when the coroutine dies, the program will exit,
192When the coroutine dies, the program will exit, just as in the main 194just as it would in the main program.
193program.
194 195
195 # create a new coroutine that just prints its arguments 196 # create a new coroutine that just prints its arguments
196 async { 197 async {
197 print "@_\n"; 198 print "@_\n";
198 } 1,2,3,4; 199 } 1,2,3,4;
… …
223The 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
224changing $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
225required. 226required.
226 227
227If you are concerned about pooled coroutines growing a lot because a 228If you are concerned about pooled coroutines growing a lot because a
228single 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
229terminate }> 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.
230 233
231=cut 234=cut
232 235
233our $POOL_SIZE = 8; 236our $POOL_SIZE = 8;
237our $POOL_RSS = 16 * 1024;
234our @pool; 238our @async_pool;
235 239
236sub pool_handler { 240sub pool_handler {
241 my $cb;
242
237 while () { 243 while () {
238 eval { 244 eval {
239 my ($cb, @arg) = @{ delete $current->{_invoke} or return }; 245 while () {
240 $cb->(@arg); 246 $cb = &_pool_1
247 or return;
248
249 &$cb;
250
251 return if &_pool_2;
252
253 undef $cb;
254 schedule;
255 }
241 }; 256 };
257
242 warn $@ if $@; 258 warn $@ if $@;
243
244 last if @pool >= $POOL_SIZE;
245 push @pool, $current;
246
247 $current->prio (0);
248 schedule;
249 } 259 }
250} 260}
251 261
252sub async_pool(&@) { 262sub async_pool(&@) {
253 # this is also inlined into the unlock_scheduler 263 # this is also inlined into the unlock_scheduler
254 my $coro = (pop @pool or new Coro \&pool_handler); 264 my $coro = (pop @async_pool) || new Coro \&pool_handler;;
255 265
256 $coro->{_invoke} = [@_]; 266 $coro->{_invoke} = [@_];
257 $coro->ready; 267 $coro->ready;
258 268
259 $coro 269 $coro
… …
277 # wake up sleeping coroutine 287 # wake up sleeping coroutine
278 $current->ready; 288 $current->ready;
279 undef $current; 289 undef $current;
280 }; 290 };
281 291
282 # call schedule until event occured. 292 # call schedule until event occurred.
283 # in case we are woken up for other reasons 293 # in case we are woken up for other reasons
284 # (current still defined), loop. 294 # (current still defined), loop.
285 Coro::schedule while $current; 295 Coro::schedule while $current;
286 } 296 }
287 297
… …
325Create a new coroutine and return it. When the sub returns the coroutine 335Create a new coroutine and return it. When the sub returns the coroutine
326automatically terminates as if C<terminate> with the returned values were 336automatically terminates as if C<terminate> with the returned values were
327called. To make the coroutine run you must first put it into the ready queue 337called. To make the coroutine run you must first put it into the ready queue
328by calling the ready method. 338by calling the ready method.
329 339
330Calling C<exit> in a coroutine will not work correctly, so do not do that. 340See C<async> for additional discussion.
331 341
332=cut 342=cut
333 343
334sub _run_coro { 344sub _run_coro {
335 terminate &{+shift}; 345 terminate &{+shift};
… …
458=over 4 468=over 4
459 469
460=item Coro::nready 470=item Coro::nready
461 471
462Returns the number of coroutines that are currently in the ready state, 472Returns the number of coroutines that are currently in the ready state,
463i.e. that can be swicthed to. The value C<0> means that the only runnable 473i.e. that can be switched to. The value C<0> means that the only runnable
464coroutine is the currently running one, so C<cede> would have no effect, 474coroutine is the currently running one, so C<cede> would have no effect,
465and C<schedule> would cause a deadlock unless there is an idle handler 475and C<schedule> would cause a deadlock unless there is an idle handler
466that wakes up some coroutines. 476that wakes up some coroutines.
467 477
468=item my $guard = Coro::guard { ... } 478=item my $guard = Coro::guard { ... }
469 479
470This creates and returns a guard object. Nothing happens until the objetc 480This creates and returns a guard object. Nothing happens until the object
471gets destroyed, in which case the codeblock given as argument will be 481gets destroyed, in which case the codeblock given as argument will be
472executed. This is useful to free locks or other resources in case of a 482executed. This is useful to free locks or other resources in case of a
473runtime error or when the coroutine gets canceled, as in both cases the 483runtime error or when the coroutine gets canceled, as in both cases the
474guard block will be executed. The guard object supports only one method, 484guard block will be executed. The guard object supports only one method,
475C<< ->cancel >>, which will keep the codeblock from being executed. 485C<< ->cancel >>, which will keep the codeblock from being executed.
… …
504This utility function takes a BLOCK or code reference and "unblocks" it, 514This utility function takes a BLOCK or code reference and "unblocks" it,
505returning the new coderef. This means that the new coderef will return 515returning the new coderef. This means that the new coderef will return
506immediately without blocking, returning nothing, while the original code 516immediately without blocking, returning nothing, while the original code
507ref will be called (with parameters) from within its own coroutine. 517ref will be called (with parameters) from within its own coroutine.
508 518
509The reason this fucntion exists is that many event libraries (such as the 519The reason this function exists is that many event libraries (such as the
510venerable L<Event|Event> module) are not coroutine-safe (a weaker form 520venerable L<Event|Event> module) are not coroutine-safe (a weaker form
511of thread-safety). This means you must not block within event callbacks, 521of thread-safety). This means you must not block within event callbacks,
512otherwise you might suffer from crashes or worse. 522otherwise you might suffer from crashes or worse.
513 523
514This function allows your callbacks to block by executing them in another 524This function allows your callbacks to block by executing them in another
… …
525 535
526# we create a special coro because we want to cede, 536# we create a special coro because we want to cede,
527# to reduce pressure on the coro pool (because most callbacks 537# to reduce pressure on the coro pool (because most callbacks
528# return immediately and can be reused) and because we cannot cede 538# return immediately and can be reused) and because we cannot cede
529# inside an event callback. 539# inside an event callback.
530our $unblock_scheduler = async { 540our $unblock_scheduler = new Coro sub {
531 while () { 541 while () {
532 while (my $cb = pop @unblock_queue) { 542 while (my $cb = pop @unblock_queue) {
533 # this is an inlined copy of async_pool 543 # this is an inlined copy of async_pool
534 my $coro = (pop @pool or new Coro \&pool_handler); 544 my $coro = (pop @async_pool) || new Coro \&pool_handler;
535 545
536 $coro->{_invoke} = $cb; 546 $coro->{_invoke} = $cb;
537 $coro->ready; 547 $coro->ready;
538 cede; # for short-lived callbacks, this reduces pressure on the coro pool 548 cede; # for short-lived callbacks, this reduces pressure on the coro pool
539 } 549 }
540 schedule; # sleep well 550 schedule; # sleep well
541 } 551 }
542}; 552};
553$unblock_scheduler->desc ("[unblock_sub scheduler]");
543 554
544sub unblock_sub(&) { 555sub unblock_sub(&) {
545 my $cb = shift; 556 my $cb = shift;
546 557
547 sub { 558 sub {
… …
560 571
561 - you must make very sure that no coro is still active on global 572 - you must make very sure that no coro is still active on global
562 destruction. very bad things might happen otherwise (usually segfaults). 573 destruction. very bad things might happen otherwise (usually segfaults).
563 574
564 - this module is not thread-safe. You should only ever use this module 575 - this module is not thread-safe. You should only ever use this module
565 from the same thread (this requirement might be losened in the future 576 from the same thread (this requirement might be loosened in the future
566 to allow per-thread schedulers, but Coro::State does not yet allow 577 to allow per-thread schedulers, but Coro::State does not yet allow
567 this). 578 this).
568 579
569=head1 SEE ALSO 580=head1 SEE ALSO
570 581

Diff Legend

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