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.220 by root, Thu Jun 25 14:27:18 2009 UTC vs.
Revision 1.231 by root, Wed Jul 8 13:46:46 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
… …
839 868
840 869
841=head1 OTHER MODULES 870=head1 OTHER MODULES
842 871
843The following is a non-exhaustive list of additional modules that use 872The following is a non-exhaustive list of additional modules that use
844AnyEvent and can therefore be mixed easily with other AnyEvent modules 873AnyEvent 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 874modules and other event loops in the same program. Some of the modules
846available via CPAN. 875come with AnyEvent, most are available via CPAN.
847 876
848=over 4 877=over 4
849 878
850=item L<AnyEvent::Util> 879=item L<AnyEvent::Util>
851 880
… …
860 889
861=item L<AnyEvent::Handle> 890=item L<AnyEvent::Handle>
862 891
863Provide read and write buffers, manages watchers for reads and writes, 892Provide read and write buffers, manages watchers for reads and writes,
864supports raw and formatted I/O, I/O queued and fully transparent and 893supports raw and formatted I/O, I/O queued and fully transparent and
865non-blocking SSL/TLS. 894non-blocking SSL/TLS (via L<AnyEvent::TLS>.
866 895
867=item L<AnyEvent::DNS> 896=item L<AnyEvent::DNS>
868 897
869Provides rich asynchronous DNS resolver capabilities. 898Provides rich asynchronous DNS resolver capabilities.
870 899
… …
898 927
899=item L<AnyEvent::GPSD> 928=item L<AnyEvent::GPSD>
900 929
901A non-blocking interface to gpsd, a daemon delivering GPS information. 930A non-blocking interface to gpsd, a daemon delivering GPS information.
902 931
932=item L<AnyEvent::IRC>
933
934AnyEvent based IRC client module family (replacing the older Net::IRC3).
935
936=item L<AnyEvent::XMPP>
937
938AnyEvent based XMPP (Jabber protocol) module family (replacing the older
939Net::XMPP2>.
940
903=item L<AnyEvent::IGS> 941=item L<AnyEvent::IGS>
904 942
905A non-blocking interface to the Internet Go Server protocol (used by 943A non-blocking interface to the Internet Go Server protocol (used by
906L<App::IGS>). 944L<App::IGS>).
907 945
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> 946=item L<Net::FCP>
917 947
918AnyEvent-based implementation of the Freenet Client Protocol, birthplace 948AnyEvent-based implementation of the Freenet Client Protocol, birthplace
919of AnyEvent. 949of AnyEvent.
920 950
… …
924 954
925=item L<Coro> 955=item L<Coro>
926 956
927Has special support for AnyEvent via L<Coro::AnyEvent>. 957Has special support for AnyEvent via L<Coro::AnyEvent>.
928 958
929=item L<IO::Lambda>
930
931The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
932
933=back 959=back
934 960
935=cut 961=cut
936 962
937package AnyEvent; 963package AnyEvent;
… …
939no warnings; 965no warnings;
940use strict qw(vars subs); 966use strict qw(vars subs);
941 967
942use Carp; 968use Carp;
943 969
944our $VERSION = 4.412; 970our $VERSION = 4.801;
945our $MODEL; 971our $MODEL;
946 972
947our $AUTOLOAD; 973our $AUTOLOAD;
948our @ISA; 974our @ISA;
949 975
… …
1094# allow only one watcher per fd, so we dup it to get a different one). 1120# allow only one watcher per fd, so we dup it to get a different one).
1095sub _dupfh($$;$$) { 1121sub _dupfh($$;$$) {
1096 my ($poll, $fh, $r, $w) = @_; 1122 my ($poll, $fh, $r, $w) = @_;
1097 1123
1098 # cygwin requires the fh mode to be matching, unix doesn't 1124 # cygwin requires the fh mode to be matching, unix doesn't
1099 my ($rw, $mode) = $poll eq "r" ? ($r, "<") 1125 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 1126
1103 open my $fh2, "$mode&" . fileno $fh 1127 open my $fh2, "$mode&", $fh
1104 or die "cannot dup() filehandle: $!,"; 1128 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,";
1105 1129
1106 # we assume CLOEXEC is already set by perl in all important cases 1130 # we assume CLOEXEC is already set by perl in all important cases
1107 1131
1108 ($fh2, $rw) 1132 ($fh2, $rw)
1109} 1133}
… …
1441 1465
1442=item C<PERL_ANYEVENT_MAX_FORKS> 1466=item C<PERL_ANYEVENT_MAX_FORKS>
1443 1467
1444The maximum number of child processes that C<AnyEvent::Util::fork_call> 1468The maximum number of child processes that C<AnyEvent::Util::fork_call>
1445will create in parallel. 1469will create in parallel.
1470
1471=item C<PERL_ANYEVENT_MAX_OUTSTANDING_DNS>
1472
1473The default value for the C<max_outstanding> parameter for the default DNS
1474resolver - this is the maximum number of parallel DNS requests that are
1475sent to the DNS server.
1476
1477=item C<PERL_ANYEVENT_RESOLV_CONF>
1478
1479The file to use instead of F</etc/resolv.conf> (or OS-specific
1480configuration) in the default resolver. When set to the empty string, no
1481default config will be used.
1482
1483=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
1484
1485When neither C<ca_file> nor C<ca_path> was specified during
1486L<AnyEvent::TLS> context creation, and either of these environment
1487variables exist, they will be used to specify CA certificate locations
1488instead of a system-dependent default.
1446 1489
1447=back 1490=back
1448 1491
1449=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1492=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1450 1493
… …
2073L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2116L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
2074 2117
2075Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2118Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2076L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2119L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2077L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2120L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2078L<AnyEvent::Impl::POE>. 2121L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>.
2079 2122
2080Non-blocking file handles, sockets, TCP clients and 2123Non-blocking file handles, sockets, TCP clients and
2081servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>. 2124servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2082 2125
2083Asynchronous DNS: L<AnyEvent::DNS>. 2126Asynchronous DNS: L<AnyEvent::DNS>.
2084 2127
2085Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>, 2128Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>,
2129L<Coro::Event>,
2086 2130
2087Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>. 2131Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::XMPP>,
2132L<AnyEvent::HTTP>.
2088 2133
2089 2134
2090=head1 AUTHOR 2135=head1 AUTHOR
2091 2136
2092 Marc Lehmann <schmorp@schmorp.de> 2137 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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