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.117 by root, Sun May 11 17:54:13 2008 UTC vs.
Revision 1.127 by root, Sat May 24 01:15:19 2008 UTC

1=head1 NAME 1=head1 => NAME
2 2
3AnyEvent - provide framework for multiple event loops 3AnyEvent - provide framework for multiple event loops
4 4
5EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event loops 5EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event loops
6 6
… …
631 631
632=item L<AnyEvent::Handle> 632=item L<AnyEvent::Handle>
633 633
634Provide read and write buffers and manages watchers for reads and writes. 634Provide read and write buffers and manages watchers for reads and writes.
635 635
636=item L<AnyEvent::Socket>
637
638Provides various utility functions for (internet protocol) sockets,
639addresses and name resolution. Also functions to create non-blocking tcp
640connections or tcp servers, with IPv6 and SRV record support and more.
641
636=item L<AnyEvent::HTTPD> 642=item L<AnyEvent::HTTPD>
637 643
638Provides a simple web application server framework. 644Provides a simple web application server framework.
639 645
640=item L<AnyEvent::DNS> 646=item L<AnyEvent::DNS>
641 647
642Provides asynchronous DNS resolver capabilities, beyond what 648Provides rich asynchronous DNS resolver capabilities.
643L<AnyEvent::Util> offers.
644 649
645=item L<AnyEvent::FastPing> 650=item L<AnyEvent::FastPing>
646 651
647The fastest ping in the west. 652The fastest ping in the west.
648 653
… …
691no warnings; 696no warnings;
692use strict; 697use strict;
693 698
694use Carp; 699use Carp;
695 700
696our $VERSION = '3.41'; 701our $VERSION = '3.6';
697our $MODEL; 702our $MODEL;
698 703
699our $AUTOLOAD; 704our $AUTOLOAD;
700our @ISA; 705our @ISA;
701 706
702our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 707our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
703 708
704our @REGISTRY; 709our @REGISTRY;
710
711our %PROTOCOL; # (ipv4|ipv6) => (1|2)
712
713{
714 my $idx;
715 $PROTOCOL{$_} = ++$idx
716 for split /\s*,\s*/, $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
717}
705 718
706my @models = ( 719my @models = (
707 [EV:: => AnyEvent::Impl::EV::], 720 [EV:: => AnyEvent::Impl::EV::],
708 [Event:: => AnyEvent::Impl::Event::], 721 [Event:: => AnyEvent::Impl::Event::],
709 [Tk:: => AnyEvent::Impl::Tk::], 722 [Tk:: => AnyEvent::Impl::Tk::],
… …
730 1 743 1
731 } else { 744 } else {
732 push @post_detect, $cb; 745 push @post_detect, $cb;
733 746
734 defined wantarray 747 defined wantarray
735 ? bless \$cb, "AnyEvent::Util::Guard" 748 ? bless \$cb, "AnyEvent::Util::PostDetect"
736 : () 749 : ()
737 } 750 }
738} 751}
739 752
740sub AnyEvent::Util::Guard::DESTROY { 753sub AnyEvent::Util::PostDetect::DESTROY {
741 @post_detect = grep $_ != ${$_[0]}, @post_detect; 754 @post_detect = grep $_ != ${$_[0]}, @post_detect;
742} 755}
743 756
744sub detect() { 757sub detect() {
745 unless ($MODEL) { 758 unless ($MODEL) {
… …
811package AnyEvent::Base; 824package AnyEvent::Base;
812 825
813# default implementation for ->condvar 826# default implementation for ->condvar
814 827
815sub condvar { 828sub condvar {
816 bless {}, AnyEvent::CondVar:: 829 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
817} 830}
818 831
819# default implementation for ->signal 832# default implementation for ->signal
820 833
821our %SIG_CB; 834our %SIG_CB;
… …
944 $_[0]{_ae_end_cb} = $_[1] if @_ > 1; 957 $_[0]{_ae_end_cb} = $_[1] if @_ > 1;
945} 958}
946 959
947sub end { 960sub end {
948 return if --$_[0]{_ae_counter}; 961 return if --$_[0]{_ae_counter};
949 &{ $_[0]{_ae_end_cb} } if $_[0]{_ae_end_cb}; 962 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } };
950} 963}
951 964
952# undocumented/compatibility with pre-3.4 965# undocumented/compatibility with pre-3.4
953*broadcast = \&send; 966*broadcast = \&send;
954*wait = \&_wait; 967*wait = \&_wait;
… …
1028 1041
1029For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you 1042For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1030could start your program like this: 1043could start your program like this:
1031 1044
1032 PERL_ANYEVENT_MODEL=Perl perl ... 1045 PERL_ANYEVENT_MODEL=Perl perl ...
1046
1047=item C<PERL_ANYEVENT_PROTOCOLS>
1048
1049Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1050for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1051of autoprobing).
1052
1053Must be set to a comma-separated list of protocols or address families,
1054current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1055used, and preference will be given to protocols mentioned earlier in the
1056list.
1057
1058This variable can effectively be used for denial-of-service attacks
1059against local programs (e.g. when setuid), although the impact is likely
1060small, as the program has to handle connection errors already-
1061
1062Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1063but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1064- only support IPv4, never try to resolve or contact IPv6
1065addressses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1066IPv6, but prefer IPv6 over IPv4.
1067
1068=item C<PERL_ANYEVENT_EDNS0>
1069
1070Used by L<AnyEvent::DNS> to decide wether to use the EDNS0 extension
1071for DNS. This extension is generally useful to reduce DNS traffic, but
1072some (broken) firewalls drop such DNS packets, which is why it is off by
1073default.
1074
1075Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
1076EDNS0 in its DNS requests.
1033 1077
1034=back 1078=back
1035 1079
1036=head1 EXAMPLE PROGRAM 1080=head1 EXAMPLE PROGRAM
1037 1081
… …
1048 poll => 'r', 1092 poll => 'r',
1049 cb => sub { 1093 cb => sub {
1050 warn "io event <$_[0]>\n"; # will always output <r> 1094 warn "io event <$_[0]>\n"; # will always output <r>
1051 chomp (my $input = <STDIN>); # read a line 1095 chomp (my $input = <STDIN>); # read a line
1052 warn "read: $input\n"; # output what has been read 1096 warn "read: $input\n"; # output what has been read
1053 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 1097 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1054 }, 1098 },
1055 ); 1099 );
1056 1100
1057 my $time_watcher; # can only be used once 1101 my $time_watcher; # can only be used once
1058 1102
… …
1063 }); 1107 });
1064 } 1108 }
1065 1109
1066 new_timer; # create first timer 1110 new_timer; # create first timer
1067 1111
1068 $cv->wait; # wait until user enters /^q/i 1112 $cv->recv; # wait until user enters /^q/i
1069 1113
1070=head1 REAL-WORLD EXAMPLE 1114=head1 REAL-WORLD EXAMPLE
1071 1115
1072Consider the L<Net::FCP> module. It features (among others) the following 1116Consider the L<Net::FCP> module. It features (among others) the following
1073API calls, which are to freenet what HTTP GET requests are to http: 1117API calls, which are to freenet what HTTP GET requests are to http:
… …
1129 1173
1130 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 1174 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
1131 1175
1132 if (end-of-file or data complete) { 1176 if (end-of-file or data complete) {
1133 $txn->{result} = $txn->{buf}; 1177 $txn->{result} = $txn->{buf};
1134 $txn->{finished}->broadcast; 1178 $txn->{finished}->send;
1135 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 1179 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
1136 } 1180 }
1137 1181
1138The C<result> method, finally, just waits for the finished signal (if the 1182The C<result> method, finally, just waits for the finished signal (if the
1139request was already finished, it doesn't wait, of course, and returns the 1183request was already finished, it doesn't wait, of course, and returns the
1140data: 1184data:
1141 1185
1142 $txn->{finished}->wait; 1186 $txn->{finished}->recv;
1143 return $txn->{result}; 1187 return $txn->{result};
1144 1188
1145The actual code goes further and collects all errors (C<die>s, exceptions) 1189The actual code goes further and collects all errors (C<die>s, exceptions)
1146that occured during request processing. The C<result> method detects 1190that occured during request processing. The C<result> method detects
1147whether an exception as thrown (it is stored inside the $txn object) 1191whether an exception as thrown (it is stored inside the $txn object)
… …
1182 1226
1183 my $quit = AnyEvent->condvar; 1227 my $quit = AnyEvent->condvar;
1184 1228
1185 $fcp->txn_client_get ($url)->cb (sub { 1229 $fcp->txn_client_get ($url)->cb (sub {
1186 ... 1230 ...
1187 $quit->broadcast; 1231 $quit->send;
1188 }); 1232 });
1189 1233
1190 $quit->wait; 1234 $quit->recv;
1191 1235
1192 1236
1193=head1 BENCHMARKS 1237=head1 BENCHMARKS
1194 1238
1195To give you an idea of the performance and overheads that AnyEvent adds 1239To give you an idea of the performance and overheads that AnyEvent adds
… …
1224all watchers, to avoid adding memory overhead. That means closure creation 1268all watchers, to avoid adding memory overhead. That means closure creation
1225and memory usage is not included in the figures. 1269and memory usage is not included in the figures.
1226 1270
1227I<invoke> is the time, in microseconds, used to invoke a simple 1271I<invoke> is the time, in microseconds, used to invoke a simple
1228callback. The callback simply counts down a Perl variable and after it was 1272callback. The callback simply counts down a Perl variable and after it was
1229invoked "watcher" times, it would C<< ->broadcast >> a condvar once to 1273invoked "watcher" times, it would C<< ->send >> a condvar once to
1230signal the end of this phase. 1274signal the end of this phase.
1231 1275
1232I<destroy> is the time, in microseconds, that it takes to destroy a single 1276I<destroy> is the time, in microseconds, that it takes to destroy a single
1233watcher. 1277watcher.
1234 1278
… …
1487probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1531probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1488 1532
1489 1533
1490=head1 SEE ALSO 1534=head1 SEE ALSO
1491 1535
1536Utility functions: L<AnyEvent::Util>.
1537
1492Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>, 1538Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>,
1493L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 1539L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1494 1540
1495Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 1541Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1496L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 1542L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1497L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 1543L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1498L<AnyEvent::Impl::POE>. 1544L<AnyEvent::Impl::POE>.
1499 1545
1546Non-blocking file handles, sockets, TCP clients and
1547servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>.
1548
1549Asynchronous DNS: L<AnyEvent::DNS>.
1550
1500Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>, 1551Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,
1501 1552
1502Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1553Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1503 1554
1504 1555
1505=head1 AUTHOR 1556=head1 AUTHOR
1506 1557
1507 Marc Lehmann <schmorp@schmorp.de> 1558 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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