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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.229 by root, Wed Jul 8 02:01:12 2009 UTC vs.
Revision 1.232 by root, Thu Jul 9 01:08:22 2009 UTC

… …
740variable itself. Calling C<recv> inside the callback or at any later time 740variable itself. Calling C<recv> inside the callback or at any later time
741is guaranteed not to block. 741is guaranteed not to block.
742 742
743=back 743=back
744 744
745=head1 SUPPORTED EVENT LOOPS/BACKENDS
746
747The 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
753EV is the preferred backend when no other event loop seems to be in
754use. If EV is not installed, then AnyEvent will try Event, and, failing
755that, will fall back to its own pure-perl implementation, which is
756available 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
764These will be used when they are currently loaded when the first watcher
765is created, in which case it is assumed that the application is using
766them. This means that AnyEvent will automatically pick the right backend
767when the main program loads an event module before anything starts to
768create 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
777Qt requires the Qt::Application to be instantiated first, but will
778otherwise be picked up automatically. As long as the main program
779instantiates the application before any AnyEvent watchers are created,
780everything should just work.
781
782 AnyEvent::Impl::Qt based on Qt.
783
784Support for IO::Async can only be partial, as it is too broken and
785architecturally limited to even support the AnyEvent API. It also
786is the only event loop that needs the loop to be set explicitly, so
787it can only be used by a main program knowing about AnyEvent. See
788L<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
794Some event loops can be supported via other modules:
795
796There is no direct support for WxWidgets (L<Wx>) or L<Prima>.
797
798B<WxWidgets> has no support for watching file handles. However, you can
799use WxWidgets through the POE adaptor, as POE has a Wx backend that simply
800polls 20 times per second, which was considered to be too horrible to even
801consider for AnyEvent.
802
803B<Prima> is not supported as nobody seems to be using it, but it has a POE
804backend, so it can be supported through POE.
805
806AnyEvent knows about both L<Prima> and L<Wx>, however, and will try to
807load L<POE> when detecting them, in the hope that POE will pick them up,
808in which case everything will be automatic.
809
810=back
811
745=head1 GLOBAL VARIABLES AND FUNCTIONS 812=head1 GLOBAL VARIABLES AND FUNCTIONS
746 813
747=over 4 814=over 4
748 815
749=item $AnyEvent::MODEL 816=item $AnyEvent::MODEL
… …
751Contains C<undef> until the first watcher is being created. Then it 818Contains C<undef> until the first watcher is being created. Then it
752contains the event model that is being used, which is the name of the 819contains the event model that is being used, which is the name of the
753Perl class implementing the model. This class is usually one of the 820Perl class implementing the model. This class is usually one of the
754C<AnyEvent::Impl:xxx> modules, but can be any other class in the case 821C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
755AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 822AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
756
757The 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
772There is no support for WxWidgets, as WxWidgets has no support for
773watching file handles. However, you can use WxWidgets through the
774POE Adaptor, as POE has a Wx backend that simply polls 20 times per
775second, which was considered to be too horrible to even consider for
776AnyEvent. Likewise, other POE backends can be used by AnyEvent by using
777it's adaptor.
778
779AnyEvent knows about L<Prima> and L<Wx> and will try to use L<POE> when
780autodetecting them.
781 823
782=item AnyEvent::detect 824=item AnyEvent::detect
783 825
784Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 826Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
785if necessary. You should only call this function right before you would 827if necessary. You should only call this function right before you would
… …
868 910
869 911
870=head1 OTHER MODULES 912=head1 OTHER MODULES
871 913
872The following is a non-exhaustive list of additional modules that use 914The following is a non-exhaustive list of additional modules that use
873AnyEvent and can therefore be mixed easily with other AnyEvent modules 915AnyEvent as a client and can therefore be mixed easily with other AnyEvent
874in the same program. Some of the modules come with AnyEvent, some are 916modules and other event loops in the same program. Some of the modules
875available via CPAN. 917come with AnyEvent, most are available via CPAN.
876 918
877=over 4 919=over 4
878 920
879=item L<AnyEvent::Util> 921=item L<AnyEvent::Util>
880 922
… …
889 931
890=item L<AnyEvent::Handle> 932=item L<AnyEvent::Handle>
891 933
892Provide read and write buffers, manages watchers for reads and writes, 934Provide read and write buffers, manages watchers for reads and writes,
893supports raw and formatted I/O, I/O queued and fully transparent and 935supports raw and formatted I/O, I/O queued and fully transparent and
894non-blocking SSL/TLS. 936non-blocking SSL/TLS (via L<AnyEvent::TLS>.
895 937
896=item L<AnyEvent::DNS> 938=item L<AnyEvent::DNS>
897 939
898Provides rich asynchronous DNS resolver capabilities. 940Provides rich asynchronous DNS resolver capabilities.
899 941
… …
927 969
928=item L<AnyEvent::GPSD> 970=item L<AnyEvent::GPSD>
929 971
930A non-blocking interface to gpsd, a daemon delivering GPS information. 972A non-blocking interface to gpsd, a daemon delivering GPS information.
931 973
974=item L<AnyEvent::IRC>
975
976AnyEvent based IRC client module family (replacing the older Net::IRC3).
977
978=item L<AnyEvent::XMPP>
979
980AnyEvent based XMPP (Jabber protocol) module family (replacing the older
981Net::XMPP2>.
982
932=item L<AnyEvent::IGS> 983=item L<AnyEvent::IGS>
933 984
934A non-blocking interface to the Internet Go Server protocol (used by 985A non-blocking interface to the Internet Go Server protocol (used by
935L<App::IGS>). 986L<App::IGS>).
936 987
937=item L<AnyEvent::IRC>
938
939AnyEvent based IRC client module family (replacing the older Net::IRC3).
940
941=item L<Net::XMPP2>
942
943AnyEvent based XMPP (Jabber protocol) module family.
944
945=item L<Net::FCP> 988=item L<Net::FCP>
946 989
947AnyEvent-based implementation of the Freenet Client Protocol, birthplace 990AnyEvent-based implementation of the Freenet Client Protocol, birthplace
948of AnyEvent. 991of AnyEvent.
949 992
… …
953 996
954=item L<Coro> 997=item L<Coro>
955 998
956Has special support for AnyEvent via L<Coro::AnyEvent>. 999Has special support for AnyEvent via L<Coro::AnyEvent>.
957 1000
958=item L<IO::Lambda>
959
960The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
961
962=back 1001=back
963 1002
964=cut 1003=cut
965 1004
966package AnyEvent; 1005package AnyEvent;
… …
968no warnings; 1007no warnings;
969use strict qw(vars subs); 1008use strict qw(vars subs);
970 1009
971use Carp; 1010use Carp;
972 1011
973our $VERSION = 4.8; 1012our $VERSION = 4.801;
974our $MODEL; 1013our $MODEL;
975 1014
976our $AUTOLOAD; 1015our $AUTOLOAD;
977our @ISA; 1016our @ISA;
978 1017
… …
1004 [Event:: => AnyEvent::Impl::Event::], 1043 [Event:: => AnyEvent::Impl::Event::],
1005 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 1044 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
1006 # everything below here will not be autoprobed 1045 # everything below here will not be autoprobed
1007 # as the pureperl backend should work everywhere 1046 # as the pureperl backend should work everywhere
1008 # and is usually faster 1047 # and is usually faster
1009 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1010 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers 1048 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
1011 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1049 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1050 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1051 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1012 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1052 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1013 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1014 [Wx:: => AnyEvent::Impl::POE::], 1053 [Wx:: => AnyEvent::Impl::POE::],
1015 [Prima:: => AnyEvent::Impl::POE::], 1054 [Prima:: => AnyEvent::Impl::POE::],
1016 # IO::Async is just too broken - we would need workaorunds for its 1055 # IO::Async is just too broken - we would need workarounds for its
1017 # byzantine signal and broken child handling, among others. 1056 # byzantine signal and broken child handling, among others.
1018 # IO::Async is rather hard to detect, as it doesn't have any 1057 # IO::Async is rather hard to detect, as it doesn't have any
1019 # obvious default class. 1058 # obvious default class.
1020# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program 1059# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1021# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program 1060# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
… …
2119L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2158L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
2120 2159
2121Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2160Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2122L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2161L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2123L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2162L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2124L<AnyEvent::Impl::POE>. 2163L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>.
2125 2164
2126Non-blocking file handles, sockets, TCP clients and 2165Non-blocking file handles, sockets, TCP clients and
2127servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>. 2166servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2128 2167
2129Asynchronous DNS: L<AnyEvent::DNS>. 2168Asynchronous DNS: L<AnyEvent::DNS>.
2130 2169
2131Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>, 2170Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>,
2171L<Coro::Event>,
2132 2172
2133Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>. 2173Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::XMPP>,
2174L<AnyEvent::HTTP>.
2134 2175
2135 2176
2136=head1 AUTHOR 2177=head1 AUTHOR
2137 2178
2138 Marc Lehmann <schmorp@schmorp.de> 2179 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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