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

Comparing Coro/Coro.pm (file contents):
Revision 1.108 by root, Fri Jan 5 20:00:49 2007 UTC vs.
Revision 1.130 by root, Thu Sep 20 12:02:25 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.3'; 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 117
118# maybe some other module used Coro::Specific before... 118# maybe some other module used Coro::Specific before...
… …
159# cannot destroy itself. 159# cannot destroy itself.
160my @destroy; 160my @destroy;
161my $manager; 161my $manager;
162 162
163$manager = new Coro sub { 163$manager = new Coro sub {
164 $current->desc ("[coro manager]");
165
164 while () { 166 while () {
165 (shift @destroy)->_cancel 167 (shift @destroy)->_cancel
166 while @destroy; 168 while @destroy;
167 169
168 &schedule; 170 &schedule;
… …
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;
… …
229terminate }> once per second or so to slowly replenish the pool. 230terminate }> once per second or so to slowly replenish the pool.
230 231
231=cut 232=cut
232 233
233our $POOL_SIZE = 8; 234our $POOL_SIZE = 8;
235our $MAX_POOL_RSS = 64 * 1024;
234our @pool; 236our @pool;
235 237
236sub pool_handler { 238sub pool_handler {
237 while () { 239 while () {
238 my ($cb, @arg) = @{ delete $current->{_invoke} }; 240 $current->{desc} = "[async_pool]";
239 241
240 eval { 242 eval {
243 my ($cb, @arg) = @{ delete $current->{_invoke} or return };
241 $cb->(@arg); 244 $cb->(@arg);
242 }; 245 };
243 warn $@ if $@; 246 warn $@ if $@;
244 247
245 last if @pool >= $POOL_SIZE; 248 last if @pool >= $POOL_SIZE || $current->rss >= $MAX_POOL_RSS;
249
246 push @pool, $current; 250 push @pool, $current;
247 251 $current->{desc} = "[async_pool idle]";
252 $current->save (Coro::State::SAVE_DEF);
248 $current->prio (0); 253 $current->prio (0);
249 schedule; 254 schedule;
250 } 255 }
251} 256}
252 257
253sub async_pool(&@) { 258sub async_pool(&@) {
254 # this is also inlined into the unlock_scheduler 259 # this is also inlined into the unlock_scheduler
255 my $coro = (pop @pool or new Coro \&pool_handler); 260 my $coro = (pop @pool) || new Coro \&pool_handler;;
256 261
257 $coro->{_invoke} = [@_]; 262 $coro->{_invoke} = [@_];
258 $coro->ready; 263 $coro->ready;
259 264
260 $coro 265 $coro
… …
278 # wake up sleeping coroutine 283 # wake up sleeping coroutine
279 $current->ready; 284 $current->ready;
280 undef $current; 285 undef $current;
281 }; 286 };
282 287
283 # call schedule until event occured. 288 # call schedule until event occurred.
284 # in case we are woken up for other reasons 289 # in case we are woken up for other reasons
285 # (current still defined), loop. 290 # (current still defined), loop.
286 Coro::schedule while $current; 291 Coro::schedule while $current;
287 } 292 }
288 293
… …
326Create a new coroutine and return it. When the sub returns the coroutine 331Create a new coroutine and return it. When the sub returns the coroutine
327automatically terminates as if C<terminate> with the returned values were 332automatically terminates as if C<terminate> with the returned values were
328called. To make the coroutine run you must first put it into the ready queue 333called. To make the coroutine run you must first put it into the ready queue
329by calling the ready method. 334by calling the ready method.
330 335
331Calling C<exit> in a coroutine will not work correctly, so do not do that. 336See C<async> for additional discussion.
332 337
333=cut 338=cut
334 339
335sub _run_coro { 340sub _run_coro {
336 terminate &{+shift}; 341 terminate &{+shift};
… …
459=over 4 464=over 4
460 465
461=item Coro::nready 466=item Coro::nready
462 467
463Returns the number of coroutines that are currently in the ready state, 468Returns the number of coroutines that are currently in the ready state,
464i.e. that can be swicthed to. The value C<0> means that the only runnable 469i.e. that can be switched to. The value C<0> means that the only runnable
465coroutine is the currently running one, so C<cede> would have no effect, 470coroutine is the currently running one, so C<cede> would have no effect,
466and C<schedule> would cause a deadlock unless there is an idle handler 471and C<schedule> would cause a deadlock unless there is an idle handler
467that wakes up some coroutines. 472that wakes up some coroutines.
468 473
469=item my $guard = Coro::guard { ... } 474=item my $guard = Coro::guard { ... }
470 475
471This creates and returns a guard object. Nothing happens until the objetc 476This creates and returns a guard object. Nothing happens until the object
472gets destroyed, in which case the codeblock given as argument will be 477gets destroyed, in which case the codeblock given as argument will be
473executed. This is useful to free locks or other resources in case of a 478executed. This is useful to free locks or other resources in case of a
474runtime error or when the coroutine gets canceled, as in both cases the 479runtime error or when the coroutine gets canceled, as in both cases the
475guard block will be executed. The guard object supports only one method, 480guard block will be executed. The guard object supports only one method,
476C<< ->cancel >>, which will keep the codeblock from being executed. 481C<< ->cancel >>, which will keep the codeblock from being executed.
… …
505This utility function takes a BLOCK or code reference and "unblocks" it, 510This utility function takes a BLOCK or code reference and "unblocks" it,
506returning the new coderef. This means that the new coderef will return 511returning the new coderef. This means that the new coderef will return
507immediately without blocking, returning nothing, while the original code 512immediately without blocking, returning nothing, while the original code
508ref will be called (with parameters) from within its own coroutine. 513ref will be called (with parameters) from within its own coroutine.
509 514
510The reason this fucntion exists is that many event libraries (such as the 515The reason this function exists is that many event libraries (such as the
511venerable L<Event|Event> module) are not coroutine-safe (a weaker form 516venerable L<Event|Event> module) are not coroutine-safe (a weaker form
512of thread-safety). This means you must not block within event callbacks, 517of thread-safety). This means you must not block within event callbacks,
513otherwise you might suffer from crashes or worse. 518otherwise you might suffer from crashes or worse.
514 519
515This function allows your callbacks to block by executing them in another 520This function allows your callbacks to block by executing them in another
… …
527# we create a special coro because we want to cede, 532# we create a special coro because we want to cede,
528# to reduce pressure on the coro pool (because most callbacks 533# to reduce pressure on the coro pool (because most callbacks
529# return immediately and can be reused) and because we cannot cede 534# return immediately and can be reused) and because we cannot cede
530# inside an event callback. 535# inside an event callback.
531our $unblock_scheduler = async { 536our $unblock_scheduler = async {
537 $current->desc ("[unblock_sub scheduler]");
532 while () { 538 while () {
533 while (my $cb = pop @unblock_queue) { 539 while (my $cb = pop @unblock_queue) {
534 # this is an inlined copy of async_pool 540 # this is an inlined copy of async_pool
535 my $coro = (pop @pool or new Coro \&pool_handler); 541 my $coro = (pop @pool or new Coro \&pool_handler);
536 542
… …
561 567
562 - you must make very sure that no coro is still active on global 568 - you must make very sure that no coro is still active on global
563 destruction. very bad things might happen otherwise (usually segfaults). 569 destruction. very bad things might happen otherwise (usually segfaults).
564 570
565 - this module is not thread-safe. You should only ever use this module 571 - this module is not thread-safe. You should only ever use this module
566 from the same thread (this requirement might be losened in the future 572 from the same thread (this requirement might be loosened in the future
567 to allow per-thread schedulers, but Coro::State does not yet allow 573 to allow per-thread schedulers, but Coro::State does not yet allow
568 this). 574 this).
569 575
570=head1 SEE ALSO 576=head1 SEE ALSO
571 577

Diff Legend

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