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.228 by root, Wed Jul 8 01:11:12 2009 UTC vs.
Revision 1.232 by root, Thu Jul 9 01:08:22 2009 UTC

… …
176=head2 I/O WATCHERS 176=head2 I/O WATCHERS
177 177
178You can create an I/O watcher by calling the C<< AnyEvent->io >> method 178You can create an I/O watcher by calling the C<< AnyEvent->io >> method
179with the following mandatory key-value pairs as arguments: 179with the following mandatory key-value pairs as arguments:
180 180
181C<fh> is the Perl I<file handle> (I<not> file descriptor, see below) to 181C<fh> is the Perl I<file handle> (or a naked file descriptor) to watch
182watch for events (AnyEvent might or might not keep a reference to this 182for events (AnyEvent might or might not keep a reference to this file
183file handle). Note that only file handles pointing to things for which 183handle). Note that only file handles pointing to things for which
184non-blocking operation makes sense are allowed. This includes sockets, 184non-blocking operation makes sense are allowed. This includes sockets,
185most character devices, pipes, fifos and so on, but not for example files 185most character devices, pipes, fifos and so on, but not for example files
186or block devices. 186or block devices.
187 187
188C<poll> must be a string that is either C<r> or C<w>, which creates a 188C<poll> must be a string that is either C<r> or C<w>, which creates a
… …
208 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 208 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
209 chomp (my $input = <STDIN>); 209 chomp (my $input = <STDIN>);
210 warn "read: $input\n"; 210 warn "read: $input\n";
211 undef $w; 211 undef $w;
212 }); 212 });
213
214=head3 GETTING A FILE HANDLE FROM A FILE DESCRIPTOR
215
216It is not uncommon to only have a file descriptor, while AnyEvent requires
217a Perl file handle.
218
219There are basically two methods to convert a file descriptor into a file handle. If you own
220the file descriptor, you can open it with C<&=>, as in:
221
222 open my $fh, "<&=$fileno" or die "xxx: ยง!";
223
224This will "own" the file descriptor, meaning that when C<$fh> is
225destroyed, it will automatically close the C<$fileno>. Also, note that
226the open mode (read, write, read/write) must correspond with how the
227underlying file descriptor was opened.
228
229In many cases, taking over the file descriptor is now what you want, in
230which case the only alternative is to dup the file descriptor:
231
232 open my $fh, "<&$fileno" or die "xxx: $!";
233
234This has the advantage of not closing the file descriptor and the
235disadvantage of making a slow copy.
236 213
237=head2 TIME WATCHERS 214=head2 TIME WATCHERS
238 215
239You can create a time watcher by calling the C<< AnyEvent->timer >> 216You can create a time watcher by calling the C<< AnyEvent->timer >>
240method with the following mandatory arguments: 217method with the following mandatory arguments:
… …
763variable 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
764is guaranteed not to block. 741is guaranteed not to block.
765 742
766=back 743=back
767 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
768=head1 GLOBAL VARIABLES AND FUNCTIONS 812=head1 GLOBAL VARIABLES AND FUNCTIONS
769 813
770=over 4 814=over 4
771 815
772=item $AnyEvent::MODEL 816=item $AnyEvent::MODEL
… …
774Contains C<undef> until the first watcher is being created. Then it 818Contains C<undef> until the first watcher is being created. Then it
775contains 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
776Perl class implementing the model. This class is usually one of the 820Perl class implementing the model. This class is usually one of the
777C<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
778AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 822AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
779
780The known classes so far are:
781
782 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
783 AnyEvent::Impl::Event based on Event, second best choice.
784 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
785 AnyEvent::Impl::Glib based on Glib, third-best choice.
786 AnyEvent::Impl::Tk based on Tk, very bad choice.
787 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
788 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
789 AnyEvent::Impl::POE based on POE, not generic enough for full support.
790
791 # warning, support for IO::Async is only partial, as it is too broken
792 # and limited toe ven support the AnyEvent API. See AnyEvent::Impl::Async.
793 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed (see its docs).
794
795There is no support for WxWidgets, as WxWidgets has no support for
796watching file handles. However, you can use WxWidgets through the
797POE Adaptor, as POE has a Wx backend that simply polls 20 times per
798second, which was considered to be too horrible to even consider for
799AnyEvent. Likewise, other POE backends can be used by AnyEvent by using
800it's adaptor.
801
802AnyEvent knows about L<Prima> and L<Wx> and will try to use L<POE> when
803autodetecting them.
804 823
805=item AnyEvent::detect 824=item AnyEvent::detect
806 825
807Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 826Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
808if necessary. You should only call this function right before you would 827if necessary. You should only call this function right before you would
… …
891 910
892 911
893=head1 OTHER MODULES 912=head1 OTHER MODULES
894 913
895The following is a non-exhaustive list of additional modules that use 914The following is a non-exhaustive list of additional modules that use
896AnyEvent and can therefore be mixed easily with other AnyEvent modules 915AnyEvent as a client and can therefore be mixed easily with other AnyEvent
897in 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
898available via CPAN. 917come with AnyEvent, most are available via CPAN.
899 918
900=over 4 919=over 4
901 920
902=item L<AnyEvent::Util> 921=item L<AnyEvent::Util>
903 922
… …
912 931
913=item L<AnyEvent::Handle> 932=item L<AnyEvent::Handle>
914 933
915Provide read and write buffers, manages watchers for reads and writes, 934Provide read and write buffers, manages watchers for reads and writes,
916supports 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
917non-blocking SSL/TLS. 936non-blocking SSL/TLS (via L<AnyEvent::TLS>.
918 937
919=item L<AnyEvent::DNS> 938=item L<AnyEvent::DNS>
920 939
921Provides rich asynchronous DNS resolver capabilities. 940Provides rich asynchronous DNS resolver capabilities.
922 941
… …
950 969
951=item L<AnyEvent::GPSD> 970=item L<AnyEvent::GPSD>
952 971
953A non-blocking interface to gpsd, a daemon delivering GPS information. 972A non-blocking interface to gpsd, a daemon delivering GPS information.
954 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
955=item L<AnyEvent::IGS> 983=item L<AnyEvent::IGS>
956 984
957A non-blocking interface to the Internet Go Server protocol (used by 985A non-blocking interface to the Internet Go Server protocol (used by
958L<App::IGS>). 986L<App::IGS>).
959 987
960=item L<AnyEvent::IRC>
961
962AnyEvent based IRC client module family (replacing the older Net::IRC3).
963
964=item L<Net::XMPP2>
965
966AnyEvent based XMPP (Jabber protocol) module family.
967
968=item L<Net::FCP> 988=item L<Net::FCP>
969 989
970AnyEvent-based implementation of the Freenet Client Protocol, birthplace 990AnyEvent-based implementation of the Freenet Client Protocol, birthplace
971of AnyEvent. 991of AnyEvent.
972 992
… …
976 996
977=item L<Coro> 997=item L<Coro>
978 998
979Has special support for AnyEvent via L<Coro::AnyEvent>. 999Has special support for AnyEvent via L<Coro::AnyEvent>.
980 1000
981=item L<IO::Lambda>
982
983The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
984
985=back 1001=back
986 1002
987=cut 1003=cut
988 1004
989package AnyEvent; 1005package AnyEvent;
… …
991no warnings; 1007no warnings;
992use strict qw(vars subs); 1008use strict qw(vars subs);
993 1009
994use Carp; 1010use Carp;
995 1011
996our $VERSION = 4.8; 1012our $VERSION = 4.801;
997our $MODEL; 1013our $MODEL;
998 1014
999our $AUTOLOAD; 1015our $AUTOLOAD;
1000our @ISA; 1016our @ISA;
1001 1017
… …
1027 [Event:: => AnyEvent::Impl::Event::], 1043 [Event:: => AnyEvent::Impl::Event::],
1028 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 1044 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
1029 # everything below here will not be autoprobed 1045 # everything below here will not be autoprobed
1030 # as the pureperl backend should work everywhere 1046 # as the pureperl backend should work everywhere
1031 # and is usually faster 1047 # and is usually faster
1032 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1033 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers 1048 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
1034 [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
1035 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1052 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1036 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1037 [Wx:: => AnyEvent::Impl::POE::], 1053 [Wx:: => AnyEvent::Impl::POE::],
1038 [Prima:: => AnyEvent::Impl::POE::], 1054 [Prima:: => AnyEvent::Impl::POE::],
1039 # 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
1040 # byzantine signal and broken child handling, among others. 1056 # byzantine signal and broken child handling, among others.
1041 # 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
1042 # obvious default class. 1058 # obvious default class.
1043# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program 1059# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1044# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program 1060# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
… …
1146# allow only one watcher per fd, so we dup it to get a different one). 1162# allow only one watcher per fd, so we dup it to get a different one).
1147sub _dupfh($$;$$) { 1163sub _dupfh($$;$$) {
1148 my ($poll, $fh, $r, $w) = @_; 1164 my ($poll, $fh, $r, $w) = @_;
1149 1165
1150 # cygwin requires the fh mode to be matching, unix doesn't 1166 # cygwin requires the fh mode to be matching, unix doesn't
1151 my ($rw, $mode) = $poll eq "r" ? ($r, "<") 1167 my ($rw, $mode) = $poll eq "r" ? ($r, "<") : ($w, ">");
1152 : $poll eq "w" ? ($w, ">")
1153 : Carp::croak "AnyEvent->io requires poll set to either 'r' or 'w'";
1154 1168
1155 open my $fh2, "$mode&" . fileno $fh 1169 open my $fh2, "$mode&", $fh
1156 or die "cannot dup() filehandle: $!,"; 1170 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,";
1157 1171
1158 # we assume CLOEXEC is already set by perl in all important cases 1172 # we assume CLOEXEC is already set by perl in all important cases
1159 1173
1160 ($fh2, $rw) 1174 ($fh2, $rw)
1161} 1175}
… …
2144L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2158L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
2145 2159
2146Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2160Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2147L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2161L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2148L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2162L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2149L<AnyEvent::Impl::POE>. 2163L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>.
2150 2164
2151Non-blocking file handles, sockets, TCP clients and 2165Non-blocking file handles, sockets, TCP clients and
2152servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>. 2166servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2153 2167
2154Asynchronous DNS: L<AnyEvent::DNS>. 2168Asynchronous DNS: L<AnyEvent::DNS>.
2155 2169
2156Coroutine 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>,
2157 2172
2158Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>. 2173Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::XMPP>,
2174L<AnyEvent::HTTP>.
2159 2175
2160 2176
2161=head1 AUTHOR 2177=head1 AUTHOR
2162 2178
2163 Marc Lehmann <schmorp@schmorp.de> 2179 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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