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

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.222 by root, Tue Nov 18 08:59:46 2008 UTC vs.
Revision 1.224 by root, Wed Nov 19 05:52:42 2008 UTC

… …
305>> on that once some event happens, and last you call C<schedule> to put 305>> on that once some event happens, and last you call C<schedule> to put
306yourself to sleep. Note that a lot of things can wake your coroutine up, 306yourself to sleep. Note that a lot of things can wake your coroutine up,
307so you need to check whether the event indeed happened, e.g. by storing the 307so you need to check whether the event indeed happened, e.g. by storing the
308status in a variable. 308status in a variable.
309 309
310The canonical way to wait on external events is this: 310See B<HOW TO WAIT FOR A CALLBACK>, below, for some ways to wait for callbacks.
311
312 {
313 # remember current coroutine
314 my $current = $Coro::current;
315
316 # register a hypothetical event handler
317 on_event_invoke sub {
318 # wake up sleeping coroutine
319 $current->ready;
320 undef $current;
321 };
322
323 # call schedule until event occurred.
324 # in case we are woken up for other reasons
325 # (current still defined), loop.
326 Coro::schedule while $current;
327 }
328 311
329=item cede 312=item cede
330 313
331"Cede" to other coroutines. This function puts the current coroutine into 314"Cede" to other coroutines. This function puts the current coroutine into
332the ready queue and calls C<schedule>, which has the effect of giving 315the ready queue and calls C<schedule>, which has the effect of giving
… …
441inside the coroutine at the next convenient point in time. Otherwise 424inside the coroutine at the next convenient point in time. Otherwise
442clears the exception object. 425clears the exception object.
443 426
444Coro will check for the exception each time a schedule-like-function 427Coro will check for the exception each time a schedule-like-function
445returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down 428returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down
446>>, C<< Coro::Handle->readable >> and so on. Note that this means that 429>>, C<< Coro::Handle->readable >> and so on. Most of these functions
447when a coroutine is acquiring a lock, it might only throw after it has 430detect this case and return early in case an exception is pending.
448sucessfully acquired it.
449 431
450The exception object will be thrown "as is" with the specified scalar in 432The exception object will be thrown "as is" with the specified scalar in
451C<$@>, i.e. if it is a string, no line number or newline will be appended 433C<$@>, i.e. if it is a string, no line number or newline will be appended
452(unlike with C<die>). 434(unlike with C<die>).
453 435
… …
654 unshift @unblock_queue, [$cb, @_]; 636 unshift @unblock_queue, [$cb, @_];
655 $unblock_scheduler->ready; 637 $unblock_scheduler->ready;
656 } 638 }
657} 639}
658 640
641=item $cb = Coro::rouse_cb
642
643Create and return a "rouse callback". That's a code reference that, when
644called, will save its arguments and notify the owner coroutine of the
645callback.
646
647See the next function.
648
649=item @args = Coro::rouse_wait [$cb]
650
651Wait for the specified rouse callback (or the last one tht was created in
652this coroutine).
653
654As soon as the callback is invoked (or when the calback was invoked before
655C<rouse_wait>), it will return a copy of the arguments originally passed
656to the rouse callback.
657
658See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
659
659=back 660=back
660 661
661=cut 662=cut
662 663
6631; 6641;
665
666=head1 HOW TO WAIT FOR A CALLBACK
667
668It is very common for a coroutine to wait for some callback to be
669called. This occurs naturally when you use coroutines in an otherwise
670event-based program, or when you use event-based libraries.
671
672These typically register a callback for some event, and call that callback
673when the event occured. In a coroutine, however, you typically want to
674just wait for the event, simplyifying things.
675
676For example C<< AnyEvent->child >> registers a callback to be called when
677a specific child has exited:
678
679 my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
680
681But from withina coroutine, you often just want to write this:
682
683 my $status = wait_for_child $pid;
684
685Coro offers two functions specifically designed to make this easy,
686C<Coro::rouse_cb> and C<Coro::rouse_wait>.
687
688The first function, C<rouse_cb>, generates and returns a callback that,
689when invoked, will save it's arguments and notify the coroutine that
690created the callback.
691
692The second function, C<rouse_wait>, waits for the callback to be called
693(by calling C<schedule> to go to sleep) and returns the arguments
694originally passed to the callback.
695
696Using these functions, it becomes easy to write the C<wait_for_child>
697function mentioned above:
698
699 sub wait_for_child($) {
700 my ($pid) = @_;
701
702 my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb);
703
704 my ($rpid, $rstatus) = Coro::rouse_wait;
705 $rstatus
706 }
707
708In the case where C<rouse_cb> and C<rouse_wait> are not flexible enough,
709you can roll your own, using C<schedule>:
710
711 sub wait_for_child($) {
712 my ($pid) = @_;
713
714 # store the current coroutine in $current,
715 # and provide result variables for the closure passed to ->child
716 my $current = $Coro::current;
717 my ($done, $rstatus);
718
719 # pass a closure to ->child
720 my $watcher = AnyEvent->child (pid => $pid, cb => sub {
721 $rstatus = $_[1]; # remember rstatus
722 $done = 1; # mark $rstatus as valud
723 });
724
725 # wait until the closure has been called
726 schedule while !$done;
727
728 $rstatus
729 }
730
664 731
665=head1 BUGS/LIMITATIONS 732=head1 BUGS/LIMITATIONS
666 733
667=over 4 734=over 4
668 735

Diff Legend

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