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. |
|
|
561 | |
|
|
562 | =item @AnyEvent::post_detect |
|
|
563 | |
|
|
564 | If there are any code references in this array (you can C<push> to it |
|
|
565 | before or after loading AnyEvent), then they will called directly after |
|
|
566 | the event loop has been chosen. |
|
|
567 | |
|
|
568 | You should check C<$AnyEvent::MODEL> before adding to this array, though: |
|
|
569 | if it contains a true value then the event loop has already been detected, |
|
|
570 | and the array will be ignored. |
|
|
571 | |
|
|
572 | Best use C<AnyEvent::post_detect { BLOCK }> instead. |
|
|
573 | |
552 | =back |
574 | =back |
553 | |
575 | |
554 | =head1 WHAT TO DO IN A MODULE |
576 | =head1 WHAT TO DO IN A MODULE |
555 | |
577 | |
556 | As a module author, you should C<use AnyEvent> and call AnyEvent methods |
578 | As a module author, you should C<use AnyEvent> and call AnyEvent methods |
… | |
… | |
644 | |
666 | |
645 | High level API for event-based execution flow control. |
667 | High level API for event-based execution flow control. |
646 | |
668 | |
647 | =item L<Coro> |
669 | =item L<Coro> |
648 | |
670 | |
649 | Has special support for AnyEvent. |
671 | Has special support for AnyEvent via L<Coro::AnyEvent>. |
650 | |
672 | |
651 | =item L<IO::Lambda> |
673 | =item L<IO::Lambda> |
652 | |
674 | |
653 | The lambda approach to I/O - don't ask, look there. Can use AnyEvent. |
675 | The lambda approach to I/O - don't ask, look there. Can use AnyEvent. |
654 | |
676 | |
… | |
… | |
671 | no warnings; |
693 | no warnings; |
672 | use strict; |
694 | use strict; |
673 | |
695 | |
674 | use Carp; |
696 | use Carp; |
675 | |
697 | |
676 | our $VERSION = '3.3'; |
698 | our $VERSION = '3.4'; |
677 | our $MODEL; |
699 | our $MODEL; |
678 | |
700 | |
679 | our $AUTOLOAD; |
701 | our $AUTOLOAD; |
680 | our @ISA; |
702 | our @ISA; |
681 | |
703 | |
682 | our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; |
704 | our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; |
683 | |
705 | |
684 | our @REGISTRY; |
706 | our @REGISTRY; |
685 | |
707 | |
686 | my @models = ( |
708 | my @models = ( |
687 | [Coro::EV:: => AnyEvent::Impl::CoroEV::], |
|
|
688 | [Coro::Event:: => AnyEvent::Impl::CoroEvent::], |
|
|
689 | [EV:: => AnyEvent::Impl::EV::], |
709 | [EV:: => AnyEvent::Impl::EV::], |
690 | [Event:: => AnyEvent::Impl::Event::], |
710 | [Event:: => AnyEvent::Impl::Event::], |
691 | [Tk:: => AnyEvent::Impl::Tk::], |
711 | [Tk:: => AnyEvent::Impl::Tk::], |
692 | [Wx:: => AnyEvent::Impl::POE::], |
712 | [Wx:: => AnyEvent::Impl::POE::], |
693 | [Prima:: => AnyEvent::Impl::POE::], |
713 | [Prima:: => AnyEvent::Impl::POE::], |
… | |
… | |
699 | [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza |
719 | [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza |
700 | ); |
720 | ); |
701 | |
721 | |
702 | our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); |
722 | our %method = map +($_ => 1), qw(io timer signal child condvar one_event DESTROY); |
703 | |
723 | |
|
|
724 | our @post_detect; |
|
|
725 | |
|
|
726 | sub post_detect(&) { |
|
|
727 | my ($cb) = @_; |
|
|
728 | |
|
|
729 | if ($MODEL) { |
|
|
730 | $cb->(); |
|
|
731 | |
|
|
732 | 1 |
|
|
733 | } else { |
|
|
734 | push @post_detect, $cb; |
|
|
735 | |
|
|
736 | defined wantarray |
|
|
737 | ? bless \$cb, "AnyEvent::Util::Guard" |
|
|
738 | : () |
|
|
739 | } |
|
|
740 | } |
|
|
741 | |
|
|
742 | sub AnyEvent::Util::Guard::DESTROY { |
|
|
743 | @post_detect = grep $_ != ${$_[0]}, @post_detect; |
|
|
744 | } |
|
|
745 | |
704 | sub detect() { |
746 | sub detect() { |
705 | unless ($MODEL) { |
747 | unless ($MODEL) { |
706 | no strict 'refs'; |
748 | no strict 'refs'; |
707 | |
749 | |
708 | if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { |
750 | if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { |
… | |
… | |
741 | last; |
783 | last; |
742 | } |
784 | } |
743 | } |
785 | } |
744 | |
786 | |
745 | $MODEL |
787 | $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."; |
788 | or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib."; |
747 | } |
789 | } |
748 | } |
790 | } |
749 | |
791 | |
750 | unshift @ISA, $MODEL; |
792 | unshift @ISA, $MODEL; |
751 | push @{"$MODEL\::ISA"}, "AnyEvent::Base"; |
793 | push @{"$MODEL\::ISA"}, "AnyEvent::Base"; |
|
|
794 | |
|
|
795 | (shift @post_detect)->() while @post_detect; |
752 | } |
796 | } |
753 | |
797 | |
754 | $MODEL |
798 | $MODEL |
755 | } |
799 | } |
756 | |
800 | |
… | |
… | |
1390 | |
1434 | |
1391 | BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } |
1435 | BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } |
1392 | |
1436 | |
1393 | use AnyEvent; |
1437 | use AnyEvent; |
1394 | |
1438 | |
|
|
1439 | Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can |
|
|
1440 | be used to probe what backend is used and gain other information (which is |
|
|
1441 | probably even less useful to an attacker than PERL_ANYEVENT_MODEL). |
|
|
1442 | |
1395 | |
1443 | |
1396 | =head1 SEE ALSO |
1444 | =head1 SEE ALSO |
1397 | |
1445 | |
1398 | Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>, |
1446 | 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>. |
1447 | L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. |
1401 | |
1448 | |
1402 | Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>, |
1449 | Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, |
1403 | L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, |
1450 | 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>, |
1451 | L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, |
1405 | L<AnyEvent::Impl::Qt>, L<AnyEvent::Impl::POE>. |
1452 | L<AnyEvent::Impl::POE>. |
|
|
1453 | |
|
|
1454 | Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>, |
1406 | |
1455 | |
1407 | Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. |
1456 | Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. |
1408 | |
1457 | |
1409 | |
1458 | |
1410 | =head1 AUTHOR |
1459 | =head1 AUTHOR |