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

Comparing Coro/Coro.pm (file contents):
Revision 1.141 by root, Tue Oct 2 10:38:17 2007 UTC vs.
Revision 1.151 by root, Sat Oct 6 19:25:00 2007 UTC

… …
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.8'; 55our $VERSION = '4.03';
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);
… …
116=cut 116=cut
117 117
118$main->{desc} = "[main::]"; 118$main->{desc} = "[main::]";
119 119
120# maybe some other module used Coro::Specific before... 120# maybe some other module used Coro::Specific before...
121$main->{specific} = $current->{specific} 121$main->{_specific} = $current->{_specific}
122 if $current; 122 if $current;
123 123
124_set_current $main; 124_set_current $main;
125 125
126sub current() { $current } 126sub current() { $current }
… …
151 # free coroutine data and mark as destructed 151 # free coroutine data and mark as destructed
152 $self->_destroy 152 $self->_destroy
153 or return; 153 or return;
154 154
155 # call all destruction callbacks 155 # call all destruction callbacks
156 $_->(@{$self->{status}}) 156 $_->(@{$self->{_status}})
157 for @{(delete $self->{destroy_cb}) || []}; 157 for @{(delete $self->{_on_destroy}) || []};
158} 158}
159 159
160# this coroutine is necessary because a coroutine 160# this coroutine is necessary because a coroutine
161# cannot destroy itself. 161# cannot destroy itself.
162my @destroy; 162my @destroy;
… …
186=item async { ... } [@args...] 186=item async { ... } [@args...]
187 187
188Create a new asynchronous coroutine and return it's coroutine object 188Create a new asynchronous coroutine and return it's coroutine object
189(usually unused). When the sub returns the new coroutine is automatically 189(usually unused). When the sub returns the new coroutine is automatically
190terminated. 190terminated.
191
192See the C<Coro::State::new> constructor for info about the coroutine
193environment.
191 194
192Calling C<exit> in a coroutine will do the same as calling exit outside 195Calling C<exit> in a coroutine will do the same as calling exit outside
193the coroutine. Likewise, when the coroutine dies, the program will exit, 196the coroutine. Likewise, when the coroutine dies, the program will exit,
194just as it would in the main program. 197just as it would in the main program.
195 198
… …
216issued in case of an exception instead of terminating the program, as 219issued in case of an exception instead of terminating the program, as
217C<async> does. As the coroutine is being reused, stuff like C<on_destroy> 220C<async> does. As the coroutine is being reused, stuff like C<on_destroy>
218will not work in the expected way, unless you call terminate or cancel, 221will not work in the expected way, unless you call terminate or cancel,
219which somehow defeats the purpose of pooling. 222which somehow defeats the purpose of pooling.
220 223
221The priority will be reset to C<0> after each job, otherwise the coroutine 224The priority will be reset to C<0> after each job, tracing will be
222will be re-used "as-is". 225disabled, the description will be reset and the default output filehandle
226gets restored, so you can change alkl these. Otherwise the coroutine will
227be re-used "as-is": most notably if you change other per-coroutine global
228stuff such as C<$/> you need to revert that change, which is most simply
229done by using local as in C< local $/ >.
223 230
224The pool size is limited to 8 idle coroutines (this can be adjusted by 231The pool size is limited to 8 idle coroutines (this can be adjusted by
225changing $Coro::POOL_SIZE), and there can be as many non-idle coros as 232changing $Coro::POOL_SIZE), and there can be as many non-idle coros as
226required. 233required.
227 234
… …
248 _pool_2 $cb; 255 _pool_2 $cb;
249 &schedule; 256 &schedule;
250 } 257 }
251 }; 258 };
252 259
253 last if $@ eq "\3terminate\2\n"; 260 last if $@ eq "\3async_pool terminate\2\n";
254 warn $@ if $@; 261 warn $@ if $@;
255 } 262 }
256} 263}
257 264
258sub async_pool(&@) { 265sub async_pool(&@) {
… …
344Create a new coroutine and return it. When the sub returns the coroutine 351Create a new coroutine and return it. When the sub returns the coroutine
345automatically terminates as if C<terminate> with the returned values were 352automatically terminates as if C<terminate> with the returned values were
346called. To make the coroutine run you must first put it into the ready queue 353called. To make the coroutine run you must first put it into the ready queue
347by calling the ready method. 354by calling the ready method.
348 355
349See C<async> for additional discussion. 356See C<async> and C<Coro::State::new> for additional info about the
357coroutine environment.
350 358
351=cut 359=cut
352 360
353sub _run_coro { 361sub _run_coro {
354 terminate &{+shift}; 362 terminate &{+shift};
… …
378 386
379=cut 387=cut
380 388
381sub cancel { 389sub cancel {
382 my $self = shift; 390 my $self = shift;
383 $self->{status} = [@_]; 391 $self->{_status} = [@_];
384 392
385 if ($current == $self) { 393 if ($current == $self) {
386 push @destroy, $self; 394 push @destroy, $self;
387 $manager->ready; 395 $manager->ready;
388 &schedule while 1; 396 &schedule while 1;
… …
392} 400}
393 401
394=item $coroutine->join 402=item $coroutine->join
395 403
396Wait until the coroutine terminates and return any values given to the 404Wait until the coroutine terminates and return any values given to the
397C<terminate> or C<cancel> functions. C<join> can be called multiple times 405C<terminate> or C<cancel> functions. C<join> can be called concurrently
398from multiple coroutine. 406from multiple coroutines.
399 407
400=cut 408=cut
401 409
402sub join { 410sub join {
403 my $self = shift; 411 my $self = shift;
404 412
405 unless ($self->{status}) { 413 unless ($self->{_status}) {
406 my $current = $current; 414 my $current = $current;
407 415
408 push @{$self->{destroy_cb}}, sub { 416 push @{$self->{_on_destroy}}, sub {
409 $current->ready; 417 $current->ready;
410 undef $current; 418 undef $current;
411 }; 419 };
412 420
413 &schedule while $current; 421 &schedule while $current;
414 } 422 }
415 423
416 wantarray ? @{$self->{status}} : $self->{status}[0]; 424 wantarray ? @{$self->{_status}} : $self->{_status}[0];
417} 425}
418 426
419=item $coroutine->on_destroy (\&cb) 427=item $coroutine->on_destroy (\&cb)
420 428
421Registers a callback that is called when this coroutine gets destroyed, 429Registers a callback that is called when this coroutine gets destroyed,
… …
425=cut 433=cut
426 434
427sub on_destroy { 435sub on_destroy {
428 my ($self, $cb) = @_; 436 my ($self, $cb) = @_;
429 437
430 push @{ $self->{destroy_cb} }, $cb; 438 push @{ $self->{_on_destroy} }, $cb;
431} 439}
432 440
433=item $oldprio = $coroutine->prio ($newprio) 441=item $oldprio = $coroutine->prio ($newprio)
434 442
435Sets (or gets, if the argument is missing) the priority of the 443Sets (or gets, if the argument is missing) the priority of the
… …
459 467
460=item $olddesc = $coroutine->desc ($newdesc) 468=item $olddesc = $coroutine->desc ($newdesc)
461 469
462Sets (or gets in case the argument is missing) the description for this 470Sets (or gets in case the argument is missing) the description for this
463coroutine. This is just a free-form string you can associate with a coroutine. 471coroutine. This is just a free-form string you can associate with a coroutine.
472
473This method simply sets the C<< $coroutine->{desc} >> member to the given string. You
474can modify this member directly if you wish.
475
476=item $coroutine->throw ([$scalar])
477
478If C<$throw> is specified and defined, it will be thrown as an exception
479inside the coroutine at the next convinient point in time (usually after
480it gains control at the next schedule/transfer/cede). Otherwise clears the
481exception object.
482
483The exception object will be thrown "as is" with the specified scalar in
484C<$@>, i.e. if it is a string, no line number or newline will be appended
485(unlike with C<die>).
486
487This can be used as a softer means than C<cancel> to ask a coroutine to
488end itself, although there is no guarentee that the exception will lead to
489termination, and if the exception isn't caught it might well end the whole
490program.
464 491
465=cut 492=cut
466 493
467sub desc { 494sub desc {
468 my $old = $_[0]{desc}; 495 my $old = $_[0]{desc};
… …
586 to allow per-thread schedulers, but Coro::State does not yet allow 613 to allow per-thread schedulers, but Coro::State does not yet allow
587 this). 614 this).
588 615
589=head1 SEE ALSO 616=head1 SEE ALSO
590 617
591Support/Utility: L<Coro::Cont>, L<Coro::Specific>, L<Coro::State>, L<Coro::Util>. 618Support/Utility: L<Coro::Specific>, L<Coro::State>, L<Coro::Util>.
592 619
593Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>. 620Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>.
594 621
595Event/IO: L<Coro::Timer>, L<Coro::Event>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::Select>. 622Event/IO: L<Coro::Timer>, L<Coro::Event>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::Select>.
596 623

Diff Legend

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