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.126 by root, Fri May 23 23:44:55 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
1058Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1059but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1060- only support IPv4, never try to resolve or contact IPv6
1061addressses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1062IPv6, but prefer IPv6 over IPv4.
1033 1063
1034=back 1064=back
1035 1065
1036=head1 EXAMPLE PROGRAM 1066=head1 EXAMPLE PROGRAM
1037 1067
… …
1048 poll => 'r', 1078 poll => 'r',
1049 cb => sub { 1079 cb => sub {
1050 warn "io event <$_[0]>\n"; # will always output <r> 1080 warn "io event <$_[0]>\n"; # will always output <r>
1051 chomp (my $input = <STDIN>); # read a line 1081 chomp (my $input = <STDIN>); # read a line
1052 warn "read: $input\n"; # output what has been read 1082 warn "read: $input\n"; # output what has been read
1053 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 1083 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1054 }, 1084 },
1055 ); 1085 );
1056 1086
1057 my $time_watcher; # can only be used once 1087 my $time_watcher; # can only be used once
1058 1088
… …
1063 }); 1093 });
1064 } 1094 }
1065 1095
1066 new_timer; # create first timer 1096 new_timer; # create first timer
1067 1097
1068 $cv->wait; # wait until user enters /^q/i 1098 $cv->recv; # wait until user enters /^q/i
1069 1099
1070=head1 REAL-WORLD EXAMPLE 1100=head1 REAL-WORLD EXAMPLE
1071 1101
1072Consider the L<Net::FCP> module. It features (among others) the following 1102Consider the L<Net::FCP> module. It features (among others) the following
1073API calls, which are to freenet what HTTP GET requests are to http: 1103API calls, which are to freenet what HTTP GET requests are to http:
… …
1129 1159
1130 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 1160 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
1131 1161
1132 if (end-of-file or data complete) { 1162 if (end-of-file or data complete) {
1133 $txn->{result} = $txn->{buf}; 1163 $txn->{result} = $txn->{buf};
1134 $txn->{finished}->broadcast; 1164 $txn->{finished}->send;
1135 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 1165 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
1136 } 1166 }
1137 1167
1138The C<result> method, finally, just waits for the finished signal (if the 1168The 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 1169request was already finished, it doesn't wait, of course, and returns the
1140data: 1170data:
1141 1171
1142 $txn->{finished}->wait; 1172 $txn->{finished}->recv;
1143 return $txn->{result}; 1173 return $txn->{result};
1144 1174
1145The actual code goes further and collects all errors (C<die>s, exceptions) 1175The actual code goes further and collects all errors (C<die>s, exceptions)
1146that occured during request processing. The C<result> method detects 1176that occured during request processing. The C<result> method detects
1147whether an exception as thrown (it is stored inside the $txn object) 1177whether an exception as thrown (it is stored inside the $txn object)
… …
1182 1212
1183 my $quit = AnyEvent->condvar; 1213 my $quit = AnyEvent->condvar;
1184 1214
1185 $fcp->txn_client_get ($url)->cb (sub { 1215 $fcp->txn_client_get ($url)->cb (sub {
1186 ... 1216 ...
1187 $quit->broadcast; 1217 $quit->send;
1188 }); 1218 });
1189 1219
1190 $quit->wait; 1220 $quit->recv;
1191 1221
1192 1222
1193=head1 BENCHMARKS 1223=head1 BENCHMARKS
1194 1224
1195To give you an idea of the performance and overheads that AnyEvent adds 1225To give you an idea of the performance and overheads that AnyEvent adds
… …
1224all watchers, to avoid adding memory overhead. That means closure creation 1254all watchers, to avoid adding memory overhead. That means closure creation
1225and memory usage is not included in the figures. 1255and memory usage is not included in the figures.
1226 1256
1227I<invoke> is the time, in microseconds, used to invoke a simple 1257I<invoke> is the time, in microseconds, used to invoke a simple
1228callback. The callback simply counts down a Perl variable and after it was 1258callback. The callback simply counts down a Perl variable and after it was
1229invoked "watcher" times, it would C<< ->broadcast >> a condvar once to 1259invoked "watcher" times, it would C<< ->send >> a condvar once to
1230signal the end of this phase. 1260signal the end of this phase.
1231 1261
1232I<destroy> is the time, in microseconds, that it takes to destroy a single 1262I<destroy> is the time, in microseconds, that it takes to destroy a single
1233watcher. 1263watcher.
1234 1264
… …
1487probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1517probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1488 1518
1489 1519
1490=head1 SEE ALSO 1520=head1 SEE ALSO
1491 1521
1522Utility functions: L<AnyEvent::Util>.
1523
1492Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>, 1524Event 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>. 1525L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1494 1526
1495Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 1527Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1496L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 1528L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1497L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 1529L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1498L<AnyEvent::Impl::POE>. 1530L<AnyEvent::Impl::POE>.
1499 1531
1532Non-blocking file handles, sockets, TCP clients and
1533servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>.
1534
1535Asynchronous DNS: L<AnyEvent::DNS>.
1536
1500Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>, 1537Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,
1501 1538
1502Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1539Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1503 1540
1504 1541
1505=head1 AUTHOR 1542=head1 AUTHOR
1506 1543
1507 Marc Lehmann <schmorp@schmorp.de> 1544 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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