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

Comparing Coro/Coro.pm (file contents):
Revision 1.107 by root, Fri Jan 5 18:25:51 2007 UTC vs.
Revision 1.131 by root, Thu Sep 20 12:24:42 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
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
… …
159# cannot destroy itself. 161# cannot destroy itself.
160my @destroy; 162my @destroy;
161my $manager; 163my $manager;
162 164
163$manager = new Coro sub { 165$manager = new Coro sub {
166 $current->desc ("[coro manager]");
167
164 while () { 168 while () {
165 (shift @destroy)->_cancel 169 (shift @destroy)->_cancel
166 while @destroy; 170 while @destroy;
167 171
168 &schedule; 172 &schedule;
… …
185 189
186Create a new asynchronous coroutine and return it's coroutine object 190Create a new asynchronous coroutine and return it's coroutine object
187(usually unused). When the sub returns the new coroutine is automatically 191(usually unused). When the sub returns the new coroutine is automatically
188terminated. 192terminated.
189 193
190Calling C<exit> in a coroutine will not work correctly, so do not do that. 194Calling C<exit> in a coroutine will do the same as calling exit outside
191 195the coroutine. Likewise, when the coroutine dies, the program will exit,
192When the coroutine dies, the program will exit, just as in the main 196just as it would in the main program.
193program.
194 197
195 # create a new coroutine that just prints its arguments 198 # create a new coroutine that just prints its arguments
196 async { 199 async {
197 print "@_\n"; 200 print "@_\n";
198 } 1,2,3,4; 201 } 1,2,3,4;
… …
210Similar to C<async>, but uses a coroutine pool, so you should not call 213Similar to C<async>, but uses a coroutine pool, so you should not call
211terminate or join (although you are allowed to), and you get a coroutine 214terminate or join (although you are allowed to), and you get a coroutine
212that might have executed other code already (which can be good or bad :). 215that might have executed other code already (which can be good or bad :).
213 216
214Also, the block is executed in an C<eval> context and a warning will be 217Also, the block is executed in an C<eval> context and a warning will be
215issued in case of an exception instead of terminating the program, as C<async> does. 218issued in case of an exception instead of terminating the program, as
219C<async> does. As the coroutine is being reused, stuff like C<on_destroy>
220will not work in the expected way, unless you call terminate or cancel,
221which somehow defeats the purpose of pooling.
216 222
217The priority will be reset to C<0> after each job, otherwise the coroutine 223The priority will be reset to C<0> after each job, otherwise the coroutine
218will be re-used "as-is". 224will be re-used "as-is".
219 225
220The pool size is limited to 8 idle coroutines (this can be adjusted by 226The pool size is limited to 8 idle coroutines (this can be adjusted by
… …
226terminate }> once per second or so to slowly replenish the pool. 232terminate }> once per second or so to slowly replenish the pool.
227 233
228=cut 234=cut
229 235
230our $POOL_SIZE = 8; 236our $POOL_SIZE = 8;
237our $MAX_POOL_RSS = 64 * 1024;
231our @pool; 238our @pool;
232 239
233sub pool_handler { 240sub pool_handler {
234 while () { 241 while () {
235 my ($cb, @arg) = @{ delete $current->{_invoke} }; 242 $current->{desc} = "[async_pool]";
236 243
237 eval { 244 eval {
245 my ($cb, @arg) = @{ delete $current->{_invoke} or return };
238 $cb->(@arg); 246 $cb->(@arg);
239 }; 247 };
240 warn $@ if $@; 248 warn $@ if $@;
241 249
242 last if @pool >= $POOL_SIZE; 250 last if @pool >= $POOL_SIZE || $current->rss >= $MAX_POOL_RSS;
251
243 push @pool, $current; 252 push @pool, $current;
244 253 $current->{desc} = "[async_pool idle]";
254 $current->save (Coro::State::SAVE_DEF);
245 $current->prio (0); 255 $current->prio (0);
246 schedule; 256 schedule;
247 } 257 }
248} 258}
249 259
250sub async_pool(&@) { 260sub async_pool(&@) {
251 # this is also inlined into the unlock_scheduler 261 # this is also inlined into the unlock_scheduler
252 my $coro = (pop @pool or new Coro \&pool_handler); 262 my $coro = (pop @pool) || new Coro \&pool_handler;;
253 263
254 $coro->{_invoke} = [@_]; 264 $coro->{_invoke} = [@_];
255 $coro->ready; 265 $coro->ready;
256 266
257 $coro 267 $coro
… …
275 # wake up sleeping coroutine 285 # wake up sleeping coroutine
276 $current->ready; 286 $current->ready;
277 undef $current; 287 undef $current;
278 }; 288 };
279 289
280 # call schedule until event occured. 290 # call schedule until event occurred.
281 # in case we are woken up for other reasons 291 # in case we are woken up for other reasons
282 # (current still defined), loop. 292 # (current still defined), loop.
283 Coro::schedule while $current; 293 Coro::schedule while $current;
284 } 294 }
285 295
… …
323Create a new coroutine and return it. When the sub returns the coroutine 333Create a new coroutine and return it. When the sub returns the coroutine
324automatically terminates as if C<terminate> with the returned values were 334automatically terminates as if C<terminate> with the returned values were
325called. To make the coroutine run you must first put it into the ready queue 335called. To make the coroutine run you must first put it into the ready queue
326by calling the ready method. 336by calling the ready method.
327 337
328Calling C<exit> in a coroutine will not work correctly, so do not do that. 338See C<async> for additional discussion.
329 339
330=cut 340=cut
331 341
332sub _run_coro { 342sub _run_coro {
333 terminate &{+shift}; 343 terminate &{+shift};
… …
456=over 4 466=over 4
457 467
458=item Coro::nready 468=item Coro::nready
459 469
460Returns the number of coroutines that are currently in the ready state, 470Returns the number of coroutines that are currently in the ready state,
461i.e. that can be swicthed to. The value C<0> means that the only runnable 471i.e. that can be switched to. The value C<0> means that the only runnable
462coroutine is the currently running one, so C<cede> would have no effect, 472coroutine is the currently running one, so C<cede> would have no effect,
463and C<schedule> would cause a deadlock unless there is an idle handler 473and C<schedule> would cause a deadlock unless there is an idle handler
464that wakes up some coroutines. 474that wakes up some coroutines.
465 475
466=item my $guard = Coro::guard { ... } 476=item my $guard = Coro::guard { ... }
467 477
468This creates and returns a guard object. Nothing happens until the objetc 478This creates and returns a guard object. Nothing happens until the object
469gets destroyed, in which case the codeblock given as argument will be 479gets destroyed, in which case the codeblock given as argument will be
470executed. This is useful to free locks or other resources in case of a 480executed. This is useful to free locks or other resources in case of a
471runtime error or when the coroutine gets canceled, as in both cases the 481runtime error or when the coroutine gets canceled, as in both cases the
472guard block will be executed. The guard object supports only one method, 482guard block will be executed. The guard object supports only one method,
473C<< ->cancel >>, which will keep the codeblock from being executed. 483C<< ->cancel >>, which will keep the codeblock from being executed.
… …
502This utility function takes a BLOCK or code reference and "unblocks" it, 512This utility function takes a BLOCK or code reference and "unblocks" it,
503returning the new coderef. This means that the new coderef will return 513returning the new coderef. This means that the new coderef will return
504immediately without blocking, returning nothing, while the original code 514immediately without blocking, returning nothing, while the original code
505ref will be called (with parameters) from within its own coroutine. 515ref will be called (with parameters) from within its own coroutine.
506 516
507The reason this fucntion exists is that many event libraries (such as the 517The reason this function exists is that many event libraries (such as the
508venerable L<Event|Event> module) are not coroutine-safe (a weaker form 518venerable L<Event|Event> module) are not coroutine-safe (a weaker form
509of thread-safety). This means you must not block within event callbacks, 519of thread-safety). This means you must not block within event callbacks,
510otherwise you might suffer from crashes or worse. 520otherwise you might suffer from crashes or worse.
511 521
512This function allows your callbacks to block by executing them in another 522This function allows your callbacks to block by executing them in another
… …
524# we create a special coro because we want to cede, 534# we create a special coro because we want to cede,
525# to reduce pressure on the coro pool (because most callbacks 535# to reduce pressure on the coro pool (because most callbacks
526# return immediately and can be reused) and because we cannot cede 536# return immediately and can be reused) and because we cannot cede
527# inside an event callback. 537# inside an event callback.
528our $unblock_scheduler = async { 538our $unblock_scheduler = async {
539 $current->desc ("[unblock_sub scheduler]");
529 while () { 540 while () {
530 while (my $cb = pop @unblock_queue) { 541 while (my $cb = pop @unblock_queue) {
531 # this is an inlined copy of async_pool 542 # this is an inlined copy of async_pool
532 my $coro = (pop @pool or new Coro \&pool_handler); 543 my $coro = (pop @pool or new Coro \&pool_handler);
533 544
… …
558 569
559 - you must make very sure that no coro is still active on global 570 - you must make very sure that no coro is still active on global
560 destruction. very bad things might happen otherwise (usually segfaults). 571 destruction. very bad things might happen otherwise (usually segfaults).
561 572
562 - this module is not thread-safe. You should only ever use this module 573 - this module is not thread-safe. You should only ever use this module
563 from the same thread (this requirement might be losened in the future 574 from the same thread (this requirement might be loosened in the future
564 to allow per-thread schedulers, but Coro::State does not yet allow 575 to allow per-thread schedulers, but Coro::State does not yet allow
565 this). 576 this).
566 577
567=head1 SEE ALSO 578=head1 SEE ALSO
568 579

Diff Legend

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