… | |
… | |
740 | variable itself. Calling C<recv> inside the callback or at any later time |
740 | variable itself. Calling C<recv> inside the callback or at any later time |
741 | is guaranteed not to block. |
741 | is guaranteed not to block. |
742 | |
742 | |
743 | =back |
743 | =back |
744 | |
744 | |
|
|
745 | =head1 SUPPORTED EVENT LOOPS/BACKENDS |
|
|
746 | |
|
|
747 | The available backend classes are (every class has its own manpage): |
|
|
748 | |
|
|
749 | =over 4 |
|
|
750 | |
|
|
751 | =item Backends that are autoprobed when no other event loop can be found. |
|
|
752 | |
|
|
753 | EV is the preferred backend when no other event loop seems to be in |
|
|
754 | use. If EV is not installed, then AnyEvent will try Event, and, failing |
|
|
755 | that, will fall back to its own pure-perl implementation, which is |
|
|
756 | available everywhere as it comes with AnyEvent itself. |
|
|
757 | |
|
|
758 | AnyEvent::Impl::EV based on EV (interface to libev, best choice). |
|
|
759 | AnyEvent::Impl::Event based on Event, very stable, few glitches. |
|
|
760 | AnyEvent::Impl::Perl pure-perl implementation, fast and portable. |
|
|
761 | |
|
|
762 | =item Backends that are transparently being picked up when they are used. |
|
|
763 | |
|
|
764 | These will be used when they are currently loaded when the first watcher |
|
|
765 | is created, in which case it is assumed that the application is using |
|
|
766 | them. This means that AnyEvent will automatically pick the right backend |
|
|
767 | when the main program loads an event module before anything starts to |
|
|
768 | create watchers. Nothing special needs to be done by the main program. |
|
|
769 | |
|
|
770 | AnyEvent::Impl::Glib based on Glib, slow but very stable. |
|
|
771 | AnyEvent::Impl::Tk based on Tk, very broken. |
|
|
772 | AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. |
|
|
773 | AnyEvent::Impl::POE based on POE, very slow, some limitations. |
|
|
774 | |
|
|
775 | =item Backends with special needs. |
|
|
776 | |
|
|
777 | Qt requires the Qt::Application to be instantiated first, but will |
|
|
778 | otherwise be picked up automatically. As long as the main program |
|
|
779 | instantiates the application before any AnyEvent watchers are created, |
|
|
780 | everything should just work. |
|
|
781 | |
|
|
782 | AnyEvent::Impl::Qt based on Qt. |
|
|
783 | |
|
|
784 | Support for IO::Async can only be partial, as it is too broken and |
|
|
785 | architecturally limited to even support the AnyEvent API. It also |
|
|
786 | is the only event loop that needs the loop to be set explicitly, so |
|
|
787 | it can only be used by a main program knowing about AnyEvent. See |
|
|
788 | L<AnyEvent::Impl::Async> for the gory details. |
|
|
789 | |
|
|
790 | AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed. |
|
|
791 | |
|
|
792 | =item Event loops that are indirectly supported via other backends. |
|
|
793 | |
|
|
794 | Some event loops can be supported via other modules: |
|
|
795 | |
|
|
796 | There is no direct support for WxWidgets (L<Wx>) or L<Prima>. |
|
|
797 | |
|
|
798 | B<WxWidgets> has no support for watching file handles. However, you can |
|
|
799 | use WxWidgets through the POE adaptor, as POE has a Wx backend that simply |
|
|
800 | polls 20 times per second, which was considered to be too horrible to even |
|
|
801 | consider for AnyEvent. |
|
|
802 | |
|
|
803 | B<Prima> is not supported as nobody seems to be using it, but it has a POE |
|
|
804 | backend, so it can be supported through POE. |
|
|
805 | |
|
|
806 | AnyEvent knows about both L<Prima> and L<Wx>, however, and will try to |
|
|
807 | load L<POE> when detecting them, in the hope that POE will pick them up, |
|
|
808 | in which case everything will be automatic. |
|
|
809 | |
|
|
810 | =back |
|
|
811 | |
745 | =head1 GLOBAL VARIABLES AND FUNCTIONS |
812 | =head1 GLOBAL VARIABLES AND FUNCTIONS |
746 | |
813 | |
|
|
814 | These are not normally required to use AnyEvent, but can be useful to |
|
|
815 | write AnyEvent extension modules. |
|
|
816 | |
747 | =over 4 |
817 | =over 4 |
748 | |
818 | |
749 | =item $AnyEvent::MODEL |
819 | =item $AnyEvent::MODEL |
750 | |
820 | |
751 | Contains C<undef> until the first watcher is being created. Then it |
821 | Contains C<undef> until the first watcher is being created, before the |
|
|
822 | backend has been autodetected. |
|
|
823 | |
752 | contains the event model that is being used, which is the name of the |
824 | Afterwards it contains the event model that is being used, which is the |
753 | Perl class implementing the model. This class is usually one of the |
825 | name of the Perl class implementing the model. This class is usually one |
754 | C<AnyEvent::Impl:xxx> modules, but can be any other class in the case |
826 | of the C<AnyEvent::Impl:xxx> modules, but can be any other class in the |
755 | AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). |
827 | case AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode> it |
756 | |
828 | will be C<urxvt::anyevent>). |
757 | The known classes so far are: |
|
|
758 | |
|
|
759 | AnyEvent::Impl::EV based on EV (an interface to libev, best choice). |
|
|
760 | AnyEvent::Impl::Event based on Event, second best choice. |
|
|
761 | AnyEvent::Impl::Perl pure-perl implementation, fast and portable. |
|
|
762 | AnyEvent::Impl::Glib based on Glib, third-best choice. |
|
|
763 | AnyEvent::Impl::Tk based on Tk, very bad choice. |
|
|
764 | AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). |
|
|
765 | AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. |
|
|
766 | AnyEvent::Impl::POE based on POE, not generic enough for full support. |
|
|
767 | |
|
|
768 | # warning, support for IO::Async is only partial, as it is too broken |
|
|
769 | # and limited toe ven support the AnyEvent API. See AnyEvent::Impl::Async. |
|
|
770 | AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed (see its docs). |
|
|
771 | |
|
|
772 | There is no support for WxWidgets, as WxWidgets has no support for |
|
|
773 | watching file handles. However, you can use WxWidgets through the |
|
|
774 | POE Adaptor, as POE has a Wx backend that simply polls 20 times per |
|
|
775 | second, which was considered to be too horrible to even consider for |
|
|
776 | AnyEvent. Likewise, other POE backends can be used by AnyEvent by using |
|
|
777 | it's adaptor. |
|
|
778 | |
|
|
779 | AnyEvent knows about L<Prima> and L<Wx> and will try to use L<POE> when |
|
|
780 | autodetecting them. |
|
|
781 | |
829 | |
782 | =item AnyEvent::detect |
830 | =item AnyEvent::detect |
783 | |
831 | |
784 | Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model |
832 | Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model |
785 | if necessary. You should only call this function right before you would |
833 | if necessary. You should only call this function right before you would |
786 | have created an AnyEvent watcher anyway, that is, as late as possible at |
834 | have created an AnyEvent watcher anyway, that is, as late as possible at |
787 | runtime. |
835 | runtime, and not e.g. while initialising of your module. |
|
|
836 | |
|
|
837 | If you need to do some initialisation before AnyEvent watchers are |
|
|
838 | created, use C<post_detect>. |
788 | |
839 | |
789 | =item $guard = AnyEvent::post_detect { BLOCK } |
840 | =item $guard = AnyEvent::post_detect { BLOCK } |
790 | |
841 | |
791 | Arranges for the code block to be executed as soon as the event model is |
842 | Arranges for the code block to be executed as soon as the event model is |
792 | autodetected (or immediately if this has already happened). |
843 | autodetected (or immediately if this has already happened). |
|
|
844 | |
|
|
845 | The block will be executed I<after> the actual backend has been detected |
|
|
846 | (C<$AnyEvent::MODEL> is set), but I<before> any watchers have been |
|
|
847 | created, so it is possible to e.g. patch C<@AnyEvent::ISA> or do |
|
|
848 | other initialisations - see the sources of L<AnyEvent::Strict> or |
|
|
849 | L<AnyEvent::AIO> to see how this is used. |
|
|
850 | |
|
|
851 | The most common usage is to create some global watchers, without forcing |
|
|
852 | event module detection too early, for example, L<AnyEvent::AIO> creates |
|
|
853 | and installs the global L<IO::AIO> watcher in a C<post_detect> block to |
|
|
854 | avoid autodetecting the event module at load time. |
793 | |
855 | |
794 | If called in scalar or list context, then it creates and returns an object |
856 | If called in scalar or list context, then it creates and returns an object |
795 | that automatically removes the callback again when it is destroyed. See |
857 | that automatically removes the callback again when it is destroyed. See |
796 | L<Coro::BDB> for a case where this is useful. |
858 | L<Coro::BDB> for a case where this is useful. |
797 | |
859 | |
… | |
… | |
800 | If there are any code references in this array (you can C<push> to it |
862 | If there are any code references in this array (you can C<push> to it |
801 | before or after loading AnyEvent), then they will called directly after |
863 | before or after loading AnyEvent), then they will called directly after |
802 | the event loop has been chosen. |
864 | the event loop has been chosen. |
803 | |
865 | |
804 | You should check C<$AnyEvent::MODEL> before adding to this array, though: |
866 | You should check C<$AnyEvent::MODEL> before adding to this array, though: |
805 | if it contains a true value then the event loop has already been detected, |
867 | if it is defined then the event loop has already been detected, and the |
806 | and the array will be ignored. |
868 | array will be ignored. |
807 | |
869 | |
808 | Best use C<AnyEvent::post_detect { BLOCK }> instead. |
870 | Best use C<AnyEvent::post_detect { BLOCK }> when your application allows |
|
|
871 | it,as it takes care of these details. |
|
|
872 | |
|
|
873 | This variable is mainly useful for modules that can do something useful |
|
|
874 | when AnyEvent is used and thus want to know when it is initialised, but do |
|
|
875 | not need to even load it by default. This array provides the means to hook |
|
|
876 | into AnyEvent passively, without loading it. |
809 | |
877 | |
810 | =back |
878 | =back |
811 | |
879 | |
812 | =head1 WHAT TO DO IN A MODULE |
880 | =head1 WHAT TO DO IN A MODULE |
813 | |
881 | |
… | |
… | |
965 | no warnings; |
1033 | no warnings; |
966 | use strict qw(vars subs); |
1034 | use strict qw(vars subs); |
967 | |
1035 | |
968 | use Carp; |
1036 | use Carp; |
969 | |
1037 | |
970 | our $VERSION = 4.801; |
1038 | our $VERSION = 4.82; |
971 | our $MODEL; |
1039 | our $MODEL; |
972 | |
1040 | |
973 | our $AUTOLOAD; |
1041 | our $AUTOLOAD; |
974 | our @ISA; |
1042 | our @ISA; |
975 | |
1043 | |
… | |
… | |
1001 | [Event:: => AnyEvent::Impl::Event::], |
1069 | [Event:: => AnyEvent::Impl::Event::], |
1002 | [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], |
1070 | [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], |
1003 | # everything below here will not be autoprobed |
1071 | # everything below here will not be autoprobed |
1004 | # as the pureperl backend should work everywhere |
1072 | # as the pureperl backend should work everywhere |
1005 | # and is usually faster |
1073 | # and is usually faster |
1006 | [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles |
|
|
1007 | [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers |
1074 | [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers |
1008 | [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy |
1075 | [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy |
|
|
1076 | [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles |
|
|
1077 | [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza |
1009 | [Qt:: => AnyEvent::Impl::Qt::], # requires special main program |
1078 | [Qt:: => AnyEvent::Impl::Qt::], # requires special main program |
1010 | [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza |
|
|
1011 | [Wx:: => AnyEvent::Impl::POE::], |
1079 | [Wx:: => AnyEvent::Impl::POE::], |
1012 | [Prima:: => AnyEvent::Impl::POE::], |
1080 | [Prima:: => AnyEvent::Impl::POE::], |
1013 | # IO::Async is just too broken - we would need workaorunds for its |
1081 | # IO::Async is just too broken - we would need workarounds for its |
1014 | # byzantine signal and broken child handling, among others. |
1082 | # byzantine signal and broken child handling, among others. |
1015 | # IO::Async is rather hard to detect, as it doesn't have any |
1083 | # IO::Async is rather hard to detect, as it doesn't have any |
1016 | # obvious default class. |
1084 | # obvious default class. |
1017 | # [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program |
1085 | # [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program |
1018 | # [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program |
1086 | # [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program |
… | |
… | |
2032 | |
2100 | |
2033 | A handler for C<SIGCHLD> is installed by AnyEvent's child watcher |
2101 | A handler for C<SIGCHLD> is installed by AnyEvent's child watcher |
2034 | emulation for event loops that do not support them natively. Also, some |
2102 | emulation for event loops that do not support them natively. Also, some |
2035 | event loops install a similar handler. |
2103 | event loops install a similar handler. |
2036 | |
2104 | |
2037 | If, when AnyEvent is loaded, SIGCHLD is set to IGNORE, then AnyEvent will |
2105 | Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE, then |
2038 | reset it to default, to avoid losing child exit statuses. |
2106 | AnyEvent will reset it to default, to avoid losing child exit statuses. |
2039 | |
2107 | |
2040 | =item SIGPIPE |
2108 | =item SIGPIPE |
2041 | |
2109 | |
2042 | A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef> |
2110 | A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef> |
2043 | when AnyEvent gets loaded. |
2111 | when AnyEvent gets loaded. |