| … | |
… | |
| 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 |
| 306 | yourself to sleep. Note that a lot of things can wake your coroutine up, |
306 | yourself to sleep. Note that a lot of things can wake your coroutine up, |
| 307 | so you need to check whether the event indeed happened, e.g. by storing the |
307 | so you need to check whether the event indeed happened, e.g. by storing the |
| 308 | status in a variable. |
308 | status in a variable. |
| 309 | |
309 | |
| 310 | The canonical way to wait on external events is this: |
310 | See 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 |
| 332 | the ready queue and calls C<schedule>, which has the effect of giving |
315 | the ready queue and calls C<schedule>, which has the effect of giving |
| … | |
… | |
| 653 | unshift @unblock_queue, [$cb, @_]; |
636 | unshift @unblock_queue, [$cb, @_]; |
| 654 | $unblock_scheduler->ready; |
637 | $unblock_scheduler->ready; |
| 655 | } |
638 | } |
| 656 | } |
639 | } |
| 657 | |
640 | |
|
|
641 | =item $cb = Coro::rouse_cb |
|
|
642 | |
|
|
643 | Create and return a "rouse callback". That's a code reference that, when |
|
|
644 | called, will save its arguments and notify the owner coroutine of the |
|
|
645 | callback. |
|
|
646 | |
|
|
647 | See the next function. |
|
|
648 | |
|
|
649 | =item @args = Coro::rouse_wait [$cb] |
|
|
650 | |
|
|
651 | Wait for the specified rouse callback (or the last one tht was created in |
|
|
652 | this coroutine). |
|
|
653 | |
|
|
654 | As soon as the callback is invoked (or when the calback was invoked before |
|
|
655 | C<rouse_wait>), it will return a copy of the arguments originally passed |
|
|
656 | to the rouse callback. |
|
|
657 | |
|
|
658 | See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example. |
|
|
659 | |
| 658 | =back |
660 | =back |
| 659 | |
661 | |
| 660 | =cut |
662 | =cut |
| 661 | |
663 | |
| 662 | 1; |
664 | 1; |
|
|
665 | |
|
|
666 | =head1 HOW TO WAIT FOR A CALLBACK |
|
|
667 | |
|
|
668 | It is very common for a coroutine to wait for some callback to be |
|
|
669 | called. This occurs naturally when you use coroutines in an otherwise |
|
|
670 | event-based program, or when you use event-based libraries. |
|
|
671 | |
|
|
672 | These typically register a callback for some event, and call that callback |
|
|
673 | when the event occured. In a coroutine, however, you typically want to |
|
|
674 | just wait for the event, simplyifying things. |
|
|
675 | |
|
|
676 | For example C<< AnyEvent->child >> registers a callback to be called when |
|
|
677 | a specific child has exited: |
|
|
678 | |
|
|
679 | my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... }); |
|
|
680 | |
|
|
681 | But from withina coroutine, you often just want to write this: |
|
|
682 | |
|
|
683 | my $status = wait_for_child $pid; |
|
|
684 | |
|
|
685 | Coro offers two functions specifically designed to make this easy, |
|
|
686 | C<Coro::rouse_cb> and C<Coro::rouse_wait>. |
|
|
687 | |
|
|
688 | The first function, C<rouse_cb>, generates and returns a callback that, |
|
|
689 | when invoked, will save it's arguments and notify the coroutine that |
|
|
690 | created the callback. |
|
|
691 | |
|
|
692 | The 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 |
|
|
694 | originally passed to the callback. |
|
|
695 | |
|
|
696 | Using these functions, it becomes easy to write the C<wait_for_child> |
|
|
697 | function 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 | |
|
|
708 | In the case where C<rouse_cb> and C<rouse_wait> are not flexible enough, |
|
|
709 | you 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 | |
| 663 | |
731 | |
| 664 | =head1 BUGS/LIMITATIONS |
732 | =head1 BUGS/LIMITATIONS |
| 665 | |
733 | |
| 666 | =over 4 |
734 | =over 4 |
| 667 | |
735 | |
