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.221 by root, Fri Jun 26 06:33:17 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) to watch 181C<fh> is the Perl I<file handle> (or a naked file descriptor) to watch
182for events (AnyEvent might or might not keep a reference to this file 182for events (AnyEvent might or might not keep a reference to this file
183handle). 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.
… …
599 599
600=item $cv->begin ([group callback]) 600=item $cv->begin ([group callback])
601 601
602=item $cv->end 602=item $cv->end
603 603
604These two methods are EXPERIMENTAL and MIGHT CHANGE.
605
606These two methods can be used to combine many transactions/events into 604These two methods can be used to combine many transactions/events into
607one. For example, a function that pings many hosts in parallel might want 605one. For example, a function that pings many hosts in parallel might want
608to use a condition variable for the whole process. 606to use a condition variable for the whole process.
609 607
610Every call to C<< ->begin >> will increment a counter, and every call to 608Every call to C<< ->begin >> will increment a counter, and every call to
611C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end 609C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end
612>>, the (last) callback passed to C<begin> will be executed. That callback 610>>, the (last) callback passed to C<begin> will be executed. That callback
613is I<supposed> to call C<< ->send >>, but that is not required. If no 611is I<supposed> to call C<< ->send >>, but that is not required. If no
614callback was set, C<send> will be called without any arguments. 612callback was set, C<send> will be called without any arguments.
615 613
616Let's clarify this with the ping example: 614You can think of C<< $cv->send >> giving you an OR condition (one call
615sends), while C<< $cv->begin >> and C<< $cv->end >> giving you an AND
616condition (all C<begin> calls must be C<end>'ed before the condvar sends).
617
618Let's start with a simple example: you have two I/O watchers (for example,
619STDOUT and STDERR for a program), and you want to wait for both streams to
620close before activating a condvar:
621
622 my $cv = AnyEvent->condvar;
623
624 $cv->begin; # first watcher
625 my $w1 = AnyEvent->io (fh => $fh1, cb => sub {
626 defined sysread $fh1, my $buf, 4096
627 or $cv->end;
628 });
629
630 $cv->begin; # second watcher
631 my $w2 = AnyEvent->io (fh => $fh2, cb => sub {
632 defined sysread $fh2, my $buf, 4096
633 or $cv->end;
634 });
635
636 $cv->recv;
637
638This works because for every event source (EOF on file handle), there is
639one call to C<begin>, so the condvar waits for all calls to C<end> before
640sending.
641
642The ping example mentioned above is slightly more complicated, as the
643there are results to be passwd back, and the number of tasks that are
644begung can potentially be zero:
617 645
618 my $cv = AnyEvent->condvar; 646 my $cv = AnyEvent->condvar;
619 647
620 my %result; 648 my %result;
621 $cv->begin (sub { $cv->send (\%result) }); 649 $cv->begin (sub { $cv->send (\%result) });
… …
641loop, which serves two important purposes: first, it sets the callback 669loop, which serves two important purposes: first, it sets the callback
642to be called once the counter reaches C<0>, and second, it ensures that 670to be called once the counter reaches C<0>, and second, it ensures that
643C<send> is called even when C<no> hosts are being pinged (the loop 671C<send> is called even when C<no> hosts are being pinged (the loop
644doesn't execute once). 672doesn't execute once).
645 673
646This is the general pattern when you "fan out" into multiple subrequests: 674This is the general pattern when you "fan out" into multiple (but
647use an outer C<begin>/C<end> pair to set the callback and ensure C<end> 675potentially none) subrequests: use an outer C<begin>/C<end> pair to set
648is called at least once, and then, for each subrequest you start, call 676the callback and ensure C<end> is called at least once, and then, for each
649C<begin> and for each subrequest you finish, call C<end>. 677subrequest you start, call C<begin> and for each subrequest you finish,
678call C<end>.
650 679
651=back 680=back
652 681
653=head3 METHODS FOR CONSUMERS 682=head3 METHODS FOR CONSUMERS
654 683
… …
711variable 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
712is guaranteed not to block. 741is guaranteed not to block.
713 742
714=back 743=back
715 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
716=head1 GLOBAL VARIABLES AND FUNCTIONS 812=head1 GLOBAL VARIABLES AND FUNCTIONS
717 813
718=over 4 814=over 4
719 815
720=item $AnyEvent::MODEL 816=item $AnyEvent::MODEL
… …
722Contains C<undef> until the first watcher is being created. Then it 818Contains C<undef> until the first watcher is being created. Then it
723contains 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
724Perl class implementing the model. This class is usually one of the 820Perl class implementing the model. This class is usually one of the
725C<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
726AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 822AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
727
728The known classes so far are:
729
730 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
731 AnyEvent::Impl::Event based on Event, second best choice.
732 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
733 AnyEvent::Impl::Glib based on Glib, third-best choice.
734 AnyEvent::Impl::Tk based on Tk, very bad choice.
735 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
736 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
737 AnyEvent::Impl::POE based on POE, not generic enough for full support.
738
739 # warning, support for IO::Async is only partial, as it is too broken
740 # and limited toe ven support the AnyEvent API. See AnyEvent::Impl::Async.
741 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed (see its docs).
742
743There is no support for WxWidgets, as WxWidgets has no support for
744watching file handles. However, you can use WxWidgets through the
745POE Adaptor, as POE has a Wx backend that simply polls 20 times per
746second, which was considered to be too horrible to even consider for
747AnyEvent. Likewise, other POE backends can be used by AnyEvent by using
748it's adaptor.
749
750AnyEvent knows about L<Prima> and L<Wx> and will try to use L<POE> when
751autodetecting them.
752 823
753=item AnyEvent::detect 824=item AnyEvent::detect
754 825
755Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 826Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
756if necessary. You should only call this function right before you would 827if necessary. You should only call this function right before you would
… …
839 910
840 911
841=head1 OTHER MODULES 912=head1 OTHER MODULES
842 913
843The following is a non-exhaustive list of additional modules that use 914The following is a non-exhaustive list of additional modules that use
844AnyEvent and can therefore be mixed easily with other AnyEvent modules 915AnyEvent as a client and can therefore be mixed easily with other AnyEvent
845in 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
846available via CPAN. 917come with AnyEvent, most are available via CPAN.
847 918
848=over 4 919=over 4
849 920
850=item L<AnyEvent::Util> 921=item L<AnyEvent::Util>
851 922
… …
860 931
861=item L<AnyEvent::Handle> 932=item L<AnyEvent::Handle>
862 933
863Provide read and write buffers, manages watchers for reads and writes, 934Provide read and write buffers, manages watchers for reads and writes,
864supports 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
865non-blocking SSL/TLS. 936non-blocking SSL/TLS (via L<AnyEvent::TLS>.
866 937
867=item L<AnyEvent::DNS> 938=item L<AnyEvent::DNS>
868 939
869Provides rich asynchronous DNS resolver capabilities. 940Provides rich asynchronous DNS resolver capabilities.
870 941
… …
898 969
899=item L<AnyEvent::GPSD> 970=item L<AnyEvent::GPSD>
900 971
901A non-blocking interface to gpsd, a daemon delivering GPS information. 972A non-blocking interface to gpsd, a daemon delivering GPS information.
902 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
903=item L<AnyEvent::IGS> 983=item L<AnyEvent::IGS>
904 984
905A non-blocking interface to the Internet Go Server protocol (used by 985A non-blocking interface to the Internet Go Server protocol (used by
906L<App::IGS>). 986L<App::IGS>).
907 987
908=item L<AnyEvent::IRC>
909
910AnyEvent based IRC client module family (replacing the older Net::IRC3).
911
912=item L<Net::XMPP2>
913
914AnyEvent based XMPP (Jabber protocol) module family.
915
916=item L<Net::FCP> 988=item L<Net::FCP>
917 989
918AnyEvent-based implementation of the Freenet Client Protocol, birthplace 990AnyEvent-based implementation of the Freenet Client Protocol, birthplace
919of AnyEvent. 991of AnyEvent.
920 992
… …
924 996
925=item L<Coro> 997=item L<Coro>
926 998
927Has special support for AnyEvent via L<Coro::AnyEvent>. 999Has special support for AnyEvent via L<Coro::AnyEvent>.
928 1000
929=item L<IO::Lambda>
930
931The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
932
933=back 1001=back
934 1002
935=cut 1003=cut
936 1004
937package AnyEvent; 1005package AnyEvent;
… …
939no warnings; 1007no warnings;
940use strict qw(vars subs); 1008use strict qw(vars subs);
941 1009
942use Carp; 1010use Carp;
943 1011
944our $VERSION = 4.42; 1012our $VERSION = 4.801;
945our $MODEL; 1013our $MODEL;
946 1014
947our $AUTOLOAD; 1015our $AUTOLOAD;
948our @ISA; 1016our @ISA;
949 1017
… …
975 [Event:: => AnyEvent::Impl::Event::], 1043 [Event:: => AnyEvent::Impl::Event::],
976 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 1044 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
977 # everything below here will not be autoprobed 1045 # everything below here will not be autoprobed
978 # as the pureperl backend should work everywhere 1046 # as the pureperl backend should work everywhere
979 # and is usually faster 1047 # and is usually faster
980 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
981 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers 1048 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
982 [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
983 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1052 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
984 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
985 [Wx:: => AnyEvent::Impl::POE::], 1053 [Wx:: => AnyEvent::Impl::POE::],
986 [Prima:: => AnyEvent::Impl::POE::], 1054 [Prima:: => AnyEvent::Impl::POE::],
987 # 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
988 # byzantine signal and broken child handling, among others. 1056 # byzantine signal and broken child handling, among others.
989 # 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
990 # obvious default class. 1058 # obvious default class.
991# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program 1059# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
992# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program 1060# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
… …
1094# 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).
1095sub _dupfh($$;$$) { 1163sub _dupfh($$;$$) {
1096 my ($poll, $fh, $r, $w) = @_; 1164 my ($poll, $fh, $r, $w) = @_;
1097 1165
1098 # cygwin requires the fh mode to be matching, unix doesn't 1166 # cygwin requires the fh mode to be matching, unix doesn't
1099 my ($rw, $mode) = $poll eq "r" ? ($r, "<") 1167 my ($rw, $mode) = $poll eq "r" ? ($r, "<") : ($w, ">");
1100 : $poll eq "w" ? ($w, ">")
1101 : Carp::croak "AnyEvent->io requires poll set to either 'r' or 'w'";
1102 1168
1103 open my $fh2, "$mode&" . fileno $fh 1169 open my $fh2, "$mode&", $fh
1104 or die "cannot dup() filehandle: $!,"; 1170 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,";
1105 1171
1106 # 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
1107 1173
1108 ($fh2, $rw) 1174 ($fh2, $rw)
1109} 1175}
… …
1441 1507
1442=item C<PERL_ANYEVENT_MAX_FORKS> 1508=item C<PERL_ANYEVENT_MAX_FORKS>
1443 1509
1444The maximum number of child processes that C<AnyEvent::Util::fork_call> 1510The maximum number of child processes that C<AnyEvent::Util::fork_call>
1445will create in parallel. 1511will create in parallel.
1512
1513=item C<PERL_ANYEVENT_MAX_OUTSTANDING_DNS>
1514
1515The default value for the C<max_outstanding> parameter for the default DNS
1516resolver - this is the maximum number of parallel DNS requests that are
1517sent to the DNS server.
1518
1519=item C<PERL_ANYEVENT_RESOLV_CONF>
1520
1521The file to use instead of F</etc/resolv.conf> (or OS-specific
1522configuration) in the default resolver. When set to the empty string, no
1523default config will be used.
1524
1525=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
1526
1527When neither C<ca_file> nor C<ca_path> was specified during
1528L<AnyEvent::TLS> context creation, and either of these environment
1529variables exist, they will be used to specify CA certificate locations
1530instead of a system-dependent default.
1446 1531
1447=back 1532=back
1448 1533
1449=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1534=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1450 1535
… …
2073L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2158L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
2074 2159
2075Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2160Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2076L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2161L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2077L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2162L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2078L<AnyEvent::Impl::POE>. 2163L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>.
2079 2164
2080Non-blocking file handles, sockets, TCP clients and 2165Non-blocking file handles, sockets, TCP clients and
2081servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>. 2166servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2082 2167
2083Asynchronous DNS: L<AnyEvent::DNS>. 2168Asynchronous DNS: L<AnyEvent::DNS>.
2084 2169
2085Coroutine 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>,
2086 2172
2087Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>. 2173Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::XMPP>,
2174L<AnyEvent::HTTP>.
2088 2175
2089 2176
2090=head1 AUTHOR 2177=head1 AUTHOR
2091 2178
2092 Marc Lehmann <schmorp@schmorp.de> 2179 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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