1 | =head1 NAME |
1 | =head1 NAME |
2 | |
2 | |
3 | AnyEvent - provide framework for multiple event loops |
3 | AnyEvent - provide framework for multiple event loops |
4 | |
4 | |
5 | EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event loops |
5 | EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event loops |
6 | |
6 | |
7 | =head1 SYNOPSIS |
7 | =head1 SYNOPSIS |
8 | |
8 | |
9 | use AnyEvent; |
9 | use AnyEvent; |
10 | |
10 | |
… | |
… | |
78 | The interface itself is vaguely similar, but not identical to the L<Event> |
78 | The interface itself is vaguely similar, but not identical to the L<Event> |
79 | module. |
79 | module. |
80 | |
80 | |
81 | During the first call of any watcher-creation method, the module tries |
81 | During the first call of any watcher-creation method, the module tries |
82 | to detect the currently loaded event loop by probing whether one of the |
82 | to detect the currently loaded event loop by probing whether one of the |
83 | following modules is already loaded: L<Coro::EV>, L<Coro::Event>, L<EV>, |
83 | following modules is already loaded: L<EV>, |
84 | L<Event>, L<Glib>, L<AnyEvent::Impl::Perl>, L<Tk>, L<Event::Lib>, L<Qt>, |
84 | L<Event>, L<Glib>, L<AnyEvent::Impl::Perl>, L<Tk>, L<Event::Lib>, L<Qt>, |
85 | L<POE>. The first one found is used. If none are found, the module tries |
85 | L<POE>. The first one found is used. If none are found, the module tries |
86 | to load these modules (excluding Tk, Event::Lib, Qt and POE as the pure perl |
86 | to load these modules (excluding Tk, Event::Lib, Qt and POE as the pure perl |
87 | adaptor should always succeed) in the order given. The first one that can |
87 | adaptor should always succeed) in the order given. The first one that can |
88 | be successfully loaded will be used. If, after this, still none could be |
88 | be successfully loaded will be used. If, after this, still none could be |
… | |
… | |
480 | while still suppporting blocking waits if the caller so desires). |
480 | while still suppporting blocking waits if the caller so desires). |
481 | |
481 | |
482 | Another reason I<never> to C<< ->wait >> in a module is that you cannot |
482 | Another reason I<never> to C<< ->wait >> in a module is that you cannot |
483 | sensibly have two C<< ->wait >>'s in parallel, as that would require |
483 | sensibly have two C<< ->wait >>'s in parallel, as that would require |
484 | multiple interpreters or coroutines/threads, none of which C<AnyEvent> |
484 | multiple interpreters or coroutines/threads, none of which C<AnyEvent> |
485 | can supply (the coroutine-aware backends L<AnyEvent::Impl::CoroEV> and |
485 | can supply. |
486 | L<AnyEvent::Impl::CoroEvent> explicitly support concurrent C<< ->wait >>'s |
486 | |
487 | from different coroutines, however). |
487 | The L<Coro> module, however, I<can> and I<does> supply coroutines and, in |
|
|
488 | fact, L<Coro::AnyEvent> replaces AnyEvent's condvars by coroutine-safe |
|
|
489 | versions and also integrates coroutines into AnyEvent, making blocking |
|
|
490 | C<< ->wait >> calls perfectly safe as long as they are done from another |
|
|
491 | coroutine (one that doesn't run the event loop). |
488 | |
492 | |
489 | You can ensure that C<< -wait >> never blocks by setting a callback and |
493 | You can ensure that C<< -wait >> never blocks by setting a callback and |
490 | only calling C<< ->wait >> from within that callback (or at a later |
494 | only calling C<< ->wait >> from within that callback (or at a later |
491 | time). This will work even when the event loop does not support blocking |
495 | time). This will work even when the event loop does not support blocking |
492 | waits otherwise. |
496 | waits otherwise. |
… | |
… | |
519 | C<AnyEvent::Impl:xxx> modules, but can be any other class in the case |
523 | C<AnyEvent::Impl:xxx> modules, but can be any other class in the case |
520 | AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). |
524 | AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). |
521 | |
525 | |
522 | The known classes so far are: |
526 | The known classes so far are: |
523 | |
527 | |
524 | AnyEvent::Impl::CoroEV based on Coro::EV, best choice. |
|
|
525 | AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice. |
|
|
526 | AnyEvent::Impl::EV based on EV (an interface to libev, best choice). |
528 | AnyEvent::Impl::EV based on EV (an interface to libev, best choice). |
527 | AnyEvent::Impl::Event based on Event, second best choice. |
529 | AnyEvent::Impl::Event based on Event, second best choice. |
528 | AnyEvent::Impl::Perl pure-perl implementation, fast and portable. |
530 | AnyEvent::Impl::Perl pure-perl implementation, fast and portable. |
529 | AnyEvent::Impl::Glib based on Glib, third-best choice. |
531 | AnyEvent::Impl::Glib based on Glib, third-best choice. |
530 | AnyEvent::Impl::Tk based on Tk, very bad choice. |
532 | AnyEvent::Impl::Tk based on Tk, very bad choice. |
… | |
… | |
547 | Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model |
549 | Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model |
548 | if necessary. You should only call this function right before you would |
550 | if necessary. You should only call this function right before you would |
549 | have created an AnyEvent watcher anyway, that is, as late as possible at |
551 | have created an AnyEvent watcher anyway, that is, as late as possible at |
550 | runtime. |
552 | runtime. |
551 | |
553 | |
|
|
554 | =item $guard = AnyEvent::post_detect { BLOCK } |
|
|
555 | |
|
|
556 | Arranges for the code block to be executed as soon as the event model is |
|
|
557 | autodetected (or immediately if this has already happened). |
|
|
558 | |
|
|
559 | If called in scalar or list context, then it creates and returns an object |
|
|
560 | that automatically removes the callback again when it is destroyed. See |
|
|
561 | L<Coro::BDB> for a case where this is useful. |
|
|
562 | |
|
|
563 | =item @AnyEvent::post_detect |
|
|
564 | |
|
|
565 | If there are any code references in this array (you can C<push> to it |
|
|
566 | before or after loading AnyEvent), then they will called directly after |
|
|
567 | the event loop has been chosen. |
|
|
568 | |
|
|
569 | You should check C<$AnyEvent::MODEL> before adding to this array, though: |
|
|
570 | if it contains a true value then the event loop has already been detected, |
|
|
571 | and the array will be ignored. |
|
|
572 | |
|
|
573 | Best use C<AnyEvent::post_detect { BLOCK }> instead. |
|
|
574 | |
552 | =back |
575 | =back |
553 | |
576 | |
554 | =head1 WHAT TO DO IN A MODULE |
577 | =head1 WHAT TO DO IN A MODULE |
555 | |
578 | |
556 | As a module author, you should C<use AnyEvent> and call AnyEvent methods |
579 | As a module author, you should C<use AnyEvent> and call AnyEvent methods |
… | |
… | |
644 | |
667 | |
645 | High level API for event-based execution flow control. |
668 | High level API for event-based execution flow control. |
646 | |
669 | |
647 | =item L<Coro> |
670 | =item L<Coro> |
648 | |
671 | |
649 | Has special support for AnyEvent. |
672 | Has special support for AnyEvent via L<Coro::AnyEvent>. |
650 | |
673 | |
651 | =item L<IO::Lambda> |
674 | =item L<IO::Lambda> |
652 | |
675 | |
653 | The lambda approach to I/O - don't ask, look there. Can use AnyEvent. |
676 | The lambda approach to I/O - don't ask, look there. Can use AnyEvent. |
654 | |
677 | |
… | |
… | |
671 | no warnings; |
694 | no warnings; |
672 | use strict; |
695 | use strict; |
673 | |
696 | |
674 | use Carp; |
697 | use Carp; |
675 | |
698 | |
676 | our $VERSION = '3.3'; |
699 | our $VERSION = '3.4'; |
677 | our $MODEL; |
700 | our $MODEL; |
678 | |
701 | |
679 | our $AUTOLOAD; |
702 | our $AUTOLOAD; |
680 | our @ISA; |
703 | our @ISA; |
681 | |
704 | |
682 | our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; |
705 | our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; |
683 | |
706 | |
684 | our @REGISTRY; |
707 | our @REGISTRY; |
685 | |
708 | |
686 | my @models = ( |
709 | my @models = ( |
687 | [Coro::EV:: => AnyEvent::Impl::CoroEV::], |
|
|
688 | [Coro::Event:: => AnyEvent::Impl::CoroEvent::], |
|
|
689 | [EV:: => AnyEvent::Impl::EV::], |
710 | [EV:: => AnyEvent::Impl::EV::], |
690 | [Event:: => AnyEvent::Impl::Event::], |
711 | [Event:: => AnyEvent::Impl::Event::], |
691 | [Tk:: => AnyEvent::Impl::Tk::], |
712 | [Tk:: => AnyEvent::Impl::Tk::], |
692 | [Wx:: => AnyEvent::Impl::POE::], |
713 | [Wx:: => AnyEvent::Impl::POE::], |
693 | [Prima:: => AnyEvent::Impl::POE::], |
714 | [Prima:: => AnyEvent::Impl::POE::], |
… | |
… | |
699 | [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza |
720 | [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza |
700 | ); |
721 | ); |
701 | |
722 | |
702 | our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); |
723 | our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); |
703 | |
724 | |
|
|
725 | our @post_detect; |
|
|
726 | |
|
|
727 | sub post_detect(&) { |
|
|
728 | my ($cb) = @_; |
|
|
729 | |
|
|
730 | if ($MODEL) { |
|
|
731 | $cb->(); |
|
|
732 | |
|
|
733 | 1 |
|
|
734 | } else { |
|
|
735 | push @post_detect, $cb; |
|
|
736 | |
|
|
737 | defined wantarray |
|
|
738 | ? bless \$cb, "AnyEvent::Util::Guard" |
|
|
739 | : () |
|
|
740 | } |
|
|
741 | } |
|
|
742 | |
|
|
743 | sub AnyEvent::Util::Guard::DESTROY { |
|
|
744 | @post_detect = grep $_ != ${$_[0]}, @post_detect; |
|
|
745 | } |
|
|
746 | |
704 | sub detect() { |
747 | sub detect() { |
705 | unless ($MODEL) { |
748 | unless ($MODEL) { |
706 | no strict 'refs'; |
749 | no strict 'refs'; |
707 | |
750 | |
708 | if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { |
751 | if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { |
… | |
… | |
741 | last; |
784 | last; |
742 | } |
785 | } |
743 | } |
786 | } |
744 | |
787 | |
745 | $MODEL |
788 | $MODEL |
746 | or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV (or Coro+EV), Event (or Coro+Event) or Glib."; |
789 | or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib."; |
747 | } |
790 | } |
748 | } |
791 | } |
749 | |
792 | |
750 | unshift @ISA, $MODEL; |
793 | unshift @ISA, $MODEL; |
751 | push @{"$MODEL\::ISA"}, "AnyEvent::Base"; |
794 | push @{"$MODEL\::ISA"}, "AnyEvent::Base"; |
|
|
795 | |
|
|
796 | (shift @post_detect)->() while @post_detect; |
752 | } |
797 | } |
753 | |
798 | |
754 | $MODEL |
799 | $MODEL |
755 | } |
800 | } |
756 | |
801 | |
… | |
… | |
1390 | |
1435 | |
1391 | BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } |
1436 | BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } |
1392 | |
1437 | |
1393 | use AnyEvent; |
1438 | use AnyEvent; |
1394 | |
1439 | |
|
|
1440 | Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can |
|
|
1441 | be used to probe what backend is used and gain other information (which is |
|
|
1442 | probably even less useful to an attacker than PERL_ANYEVENT_MODEL). |
|
|
1443 | |
1395 | |
1444 | |
1396 | =head1 SEE ALSO |
1445 | =head1 SEE ALSO |
1397 | |
1446 | |
1398 | Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, |
1447 | Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>, |
1399 | L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>, |
|
|
1400 | L<Event::Lib>, L<Qt>, L<POE>. |
1448 | L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. |
1401 | |
1449 | |
1402 | Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, |
1450 | Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, |
1403 | L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, |
1451 | L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, |
1404 | L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, L<AnyEvent::Impl::EventLib>, |
1452 | L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, |
1405 | L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>. |
1453 | L<AnyEvent::Impl::POE>. |
|
|
1454 | |
|
|
1455 | Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>, |
1406 | |
1456 | |
1407 | Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. |
1457 | Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. |
1408 | |
1458 | |
1409 | |
1459 | |
1410 | =head1 AUTHOR |
1460 | =head1 AUTHOR |