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

Comparing Coro/Coro.pm (file contents):
Revision 1.105 by root, Fri Jan 5 16:55:01 2007 UTC vs.
Revision 1.139 by root, Thu Sep 27 15:52:30 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.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
… …
153 # call all destruction callbacks 155 # call all destruction callbacks
154 $_->(@{$self->{status}}) 156 $_->(@{$self->{status}})
155 for @{(delete $self->{destroy_cb}) || []}; 157 for @{(delete $self->{destroy_cb}) || []};
156} 158}
157 159
160sub _do_trace_sub {
161 &{$current->{_trace_sub_cb}}
162}
163
164sub _do_trace_line {
165 &{$current->{_trace_line_cb}}
166}
167
158# this coroutine is necessary because a coroutine 168# this coroutine is necessary because a coroutine
159# cannot destroy itself. 169# cannot destroy itself.
160my @destroy; 170my @destroy;
161my $manager; 171my $manager;
162 172
… …
166 while @destroy; 176 while @destroy;
167 177
168 &schedule; 178 &schedule;
169 } 179 }
170}; 180};
171 181$manager->desc ("[coro manager]");
172$manager->prio (PRIO_MAX); 182$manager->prio (PRIO_MAX);
173 183
174# static methods. not really. 184# static methods. not really.
175 185
176=back 186=back
… …
185 195
186Create a new asynchronous coroutine and return it's coroutine object 196Create a new asynchronous coroutine and return it's coroutine object
187(usually unused). When the sub returns the new coroutine is automatically 197(usually unused). When the sub returns the new coroutine is automatically
188terminated. 198terminated.
189 199
190Calling C<exit> in a coroutine will not work correctly, so do not do that. 200Calling C<exit> in a coroutine will do the same as calling exit outside
191 201the coroutine. Likewise, when the coroutine dies, the program will exit,
192When the coroutine dies, the program will exit, just as in the main 202just as it would in the main program.
193program.
194 203
195 # create a new coroutine that just prints its arguments 204 # create a new coroutine that just prints its arguments
196 async { 205 async {
197 print "@_\n"; 206 print "@_\n";
198 } 1,2,3,4; 207 } 1,2,3,4;
… …
210Similar to C<async>, but uses a coroutine pool, so you should not call 219Similar 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 220terminate 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 :). 221that might have executed other code already (which can be good or bad :).
213 222
214Also, the block is executed in an C<eval> context and a warning will be 223Also, 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. 224issued in case of an exception instead of terminating the program, as
225C<async> does. As the coroutine is being reused, stuff like C<on_destroy>
226will not work in the expected way, unless you call terminate or cancel,
227which somehow defeats the purpose of pooling.
216 228
217The priority will be reset to C<0> after each job, otherwise the coroutine 229The priority will be reset to C<0> after each job, otherwise the coroutine
218will be re-used "as-is". 230will be re-used "as-is".
219 231
220The pool size is limited to 8 idle coroutines (this can be adjusted by 232The pool size is limited to 8 idle coroutines (this can be adjusted by
221changing $Coro::POOL_SIZE), and there can be as many non-idle coros as 233changing $Coro::POOL_SIZE), and there can be as many non-idle coros as
222required. 234required.
223 235
224If you are concerned about pooled coroutines growing a lot because a 236If you are concerned about pooled coroutines growing a lot because a
225single C<async_pool> used a lot of stackspace you can e.g. C<async_pool { 237single C<async_pool> used a lot of stackspace you can e.g. C<async_pool
226terminate }> once per second or so to slowly replenish the pool. 238{ terminate }> once per second or so to slowly replenish the pool. In
239addition to that, when the stacks used by a handler grows larger than 16kb
240(adjustable with $Coro::POOL_RSS) it will also exit.
227 241
228=cut 242=cut
229 243
230our $POOL_SIZE = 8; 244our $POOL_SIZE = 8;
245our $POOL_RSS = 16 * 1024;
231our @pool; 246our @async_pool;
232 247
233sub pool_handler { 248sub pool_handler {
249 my $cb;
250
234 while () { 251 while () {
235 my ($cb, @arg) = @{ delete $current->{_invoke} };
236
237 eval { 252 eval {
238 $cb->(@arg); 253 while () {
254 _pool_1 $cb;
255 &$cb;
256 _pool_2 $cb;
257 &schedule;
258 }
239 }; 259 };
260
261 last if $@ eq "\3terminate\2\n";
240 warn $@ if $@; 262 warn $@ if $@;
241 263 }
242 last if @pool >= $POOL_SIZE; 264}
243 push @pool, $current;
244
245 $current->prio (0);
246 schedule;
247 }
248}
249 265
250sub async_pool(&@) { 266sub async_pool(&@) {
251 # this is also inlined into the unlock_scheduler 267 # this is also inlined into the unlock_scheduler
252 my $coro = (pop @pool or new Coro \&pool_handler); 268 my $coro = (pop @async_pool) || new Coro \&pool_handler;
253 269
254 $coro->{_invoke} = [@_]; 270 $coro->{_invoke} = [@_];
255 $coro->ready; 271 $coro->ready;
256 272
257 $coro 273 $coro
… …
275 # wake up sleeping coroutine 291 # wake up sleeping coroutine
276 $current->ready; 292 $current->ready;
277 undef $current; 293 undef $current;
278 }; 294 };
279 295
280 # call schedule until event occured. 296 # call schedule until event occurred.
281 # in case we are woken up for other reasons 297 # in case we are woken up for other reasons
282 # (current still defined), loop. 298 # (current still defined), loop.
283 Coro::schedule while $current; 299 Coro::schedule while $current;
284 } 300 }
285 301
… …
287 303
288"Cede" to other coroutines. This function puts the current coroutine into the 304"Cede" to other coroutines. This function puts the current coroutine into the
289ready queue and calls C<schedule>, which has the effect of giving up the 305ready queue and calls C<schedule>, which has the effect of giving up the
290current "timeslice" to other coroutines of the same or higher priority. 306current "timeslice" to other coroutines of the same or higher priority.
291 307
308Returns true if at least one coroutine switch has happened.
309
292=item Coro::cede_notself 310=item Coro::cede_notself
293 311
294Works like cede, but is not exported by default and will cede to any 312Works like cede, but is not exported by default and will cede to any
295coroutine, regardless of priority, once. 313coroutine, regardless of priority, once.
314
315Returns true if at least one coroutine switch has happened.
296 316
297=item terminate [arg...] 317=item terminate [arg...]
298 318
299Terminates the current coroutine with the given status values (see L<cancel>). 319Terminates the current coroutine with the given status values (see L<cancel>).
300 320
… …
319Create a new coroutine and return it. When the sub returns the coroutine 339Create a new coroutine and return it. When the sub returns the coroutine
320automatically terminates as if C<terminate> with the returned values were 340automatically terminates as if C<terminate> with the returned values were
321called. To make the coroutine run you must first put it into the ready queue 341called. To make the coroutine run you must first put it into the ready queue
322by calling the ready method. 342by calling the ready method.
323 343
324Calling C<exit> in a coroutine will not work correctly, so do not do that. 344See C<async> for additional discussion.
325 345
326=cut 346=cut
327 347
328sub _run_coro { 348sub _run_coro {
329 terminate &{+shift}; 349 terminate &{+shift};
… …
452=over 4 472=over 4
453 473
454=item Coro::nready 474=item Coro::nready
455 475
456Returns the number of coroutines that are currently in the ready state, 476Returns the number of coroutines that are currently in the ready state,
457i.e. that can be swicthed to. The value C<0> means that the only runnable 477i.e. that can be switched to. The value C<0> means that the only runnable
458coroutine is the currently running one, so C<cede> would have no effect, 478coroutine is the currently running one, so C<cede> would have no effect,
459and C<schedule> would cause a deadlock unless there is an idle handler 479and C<schedule> would cause a deadlock unless there is an idle handler
460that wakes up some coroutines. 480that wakes up some coroutines.
461 481
462=item my $guard = Coro::guard { ... } 482=item my $guard = Coro::guard { ... }
463 483
464This creates and returns a guard object. Nothing happens until the objetc 484This creates and returns a guard object. Nothing happens until the object
465gets destroyed, in which case the codeblock given as argument will be 485gets destroyed, in which case the codeblock given as argument will be
466executed. This is useful to free locks or other resources in case of a 486executed. This is useful to free locks or other resources in case of a
467runtime error or when the coroutine gets canceled, as in both cases the 487runtime error or when the coroutine gets canceled, as in both cases the
468guard block will be executed. The guard object supports only one method, 488guard block will be executed. The guard object supports only one method,
469C<< ->cancel >>, which will keep the codeblock from being executed. 489C<< ->cancel >>, which will keep the codeblock from being executed.
… …
498This utility function takes a BLOCK or code reference and "unblocks" it, 518This utility function takes a BLOCK or code reference and "unblocks" it,
499returning the new coderef. This means that the new coderef will return 519returning the new coderef. This means that the new coderef will return
500immediately without blocking, returning nothing, while the original code 520immediately without blocking, returning nothing, while the original code
501ref will be called (with parameters) from within its own coroutine. 521ref will be called (with parameters) from within its own coroutine.
502 522
503The reason this fucntion exists is that many event libraries (such as the 523The reason this function exists is that many event libraries (such as the
504venerable L<Event|Event> module) are not coroutine-safe (a weaker form 524venerable L<Event|Event> module) are not coroutine-safe (a weaker form
505of thread-safety). This means you must not block within event callbacks, 525of thread-safety). This means you must not block within event callbacks,
506otherwise you might suffer from crashes or worse. 526otherwise you might suffer from crashes or worse.
507 527
508This function allows your callbacks to block by executing them in another 528This function allows your callbacks to block by executing them in another
… …
519 539
520# we create a special coro because we want to cede, 540# we create a special coro because we want to cede,
521# to reduce pressure on the coro pool (because most callbacks 541# to reduce pressure on the coro pool (because most callbacks
522# return immediately and can be reused) and because we cannot cede 542# return immediately and can be reused) and because we cannot cede
523# inside an event callback. 543# inside an event callback.
524our $unblock_scheduler = async { 544our $unblock_scheduler = new Coro sub {
525 while () { 545 while () {
526 while (my $cb = pop @unblock_queue) { 546 while (my $cb = pop @unblock_queue) {
527 # this is an inlined copy of async_pool 547 # this is an inlined copy of async_pool
528 my $coro = (pop @pool or new Coro \&pool_handler); 548 my $coro = (pop @async_pool) || new Coro \&pool_handler;
529 549
530 $coro->{_invoke} = $cb; 550 $coro->{_invoke} = $cb;
531 $coro->ready; 551 $coro->ready;
532 cede; # for short-lived callbacks, this reduces pressure on the coro pool 552 cede; # for short-lived callbacks, this reduces pressure on the coro pool
533 } 553 }
534 schedule; # sleep well 554 schedule; # sleep well
535 } 555 }
536}; 556};
557$unblock_scheduler->desc ("[unblock_sub scheduler]");
537 558
538sub unblock_sub(&) { 559sub unblock_sub(&) {
539 my $cb = shift; 560 my $cb = shift;
540 561
541 sub { 562 sub {
… …
554 575
555 - you must make very sure that no coro is still active on global 576 - you must make very sure that no coro is still active on global
556 destruction. very bad things might happen otherwise (usually segfaults). 577 destruction. very bad things might happen otherwise (usually segfaults).
557 578
558 - this module is not thread-safe. You should only ever use this module 579 - this module is not thread-safe. You should only ever use this module
559 from the same thread (this requirement might be losened in the future 580 from the same thread (this requirement might be loosened in the future
560 to allow per-thread schedulers, but Coro::State does not yet allow 581 to allow per-thread schedulers, but Coro::State does not yet allow
561 this). 582 this).
562 583
563=head1 SEE ALSO 584=head1 SEE ALSO
564 585

Diff Legend

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