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.125 by root, Fri May 23 23:37:13 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
… …
730 1 735 1
731 } else { 736 } else {
732 push @post_detect, $cb; 737 push @post_detect, $cb;
733 738
734 defined wantarray 739 defined wantarray
735 ? bless \$cb, "AnyEvent::Util::Guard" 740 ? bless \$cb, "AnyEvent::Util::PostDetect"
736 : () 741 : ()
737 } 742 }
738} 743}
739 744
740sub AnyEvent::Util::Guard::DESTROY { 745sub AnyEvent::Util::PostDetect::DESTROY {
741 @post_detect = grep $_ != ${$_[0]}, @post_detect; 746 @post_detect = grep $_ != ${$_[0]}, @post_detect;
742} 747}
743 748
744sub detect() { 749sub detect() {
745 unless ($MODEL) { 750 unless ($MODEL) {
… …
811package AnyEvent::Base; 816package AnyEvent::Base;
812 817
813# default implementation for ->condvar 818# default implementation for ->condvar
814 819
815sub condvar { 820sub condvar {
816 bless {}, AnyEvent::CondVar:: 821 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar::
817} 822}
818 823
819# default implementation for ->signal 824# default implementation for ->signal
820 825
821our %SIG_CB; 826our %SIG_CB;
… …
944 $_[0]{_ae_end_cb} = $_[1] if @_ > 1; 949 $_[0]{_ae_end_cb} = $_[1] if @_ > 1;
945} 950}
946 951
947sub end { 952sub end {
948 return if --$_[0]{_ae_counter}; 953 return if --$_[0]{_ae_counter};
949 &{ $_[0]{_ae_end_cb} } if $_[0]{_ae_end_cb}; 954 &{ $_[0]{_ae_end_cb} || sub { $_[0]->send } };
950} 955}
951 956
952# undocumented/compatibility with pre-3.4 957# undocumented/compatibility with pre-3.4
953*broadcast = \&send; 958*broadcast = \&send;
954*wait = \&_wait; 959*wait = \&_wait;
… …
1028 1033
1029For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you 1034For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1030could start your program like this: 1035could start your program like this:
1031 1036
1032 PERL_ANYEVENT_MODEL=Perl perl ... 1037 PERL_ANYEVENT_MODEL=Perl perl ...
1038
1039=item C<PERL_ANYEVENT_PROTOCOLS>
1040
1041Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1042for IPv4 or IPv6. The default is unspecified (and might change, or be the result
1043of autoprobing).
1044
1045Must be set to a comma-separated list of protocols or address families,
1046current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
1047used, and preference will be given to protocols mentioned earlier in the
1048list.
1049
1050Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
1051but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
1052- only support IPv4, never try to resolve or contact IPv6
1053addressses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
1054IPv6, but prefer IPv6 over IPv4.
1033 1055
1034=back 1056=back
1035 1057
1036=head1 EXAMPLE PROGRAM 1058=head1 EXAMPLE PROGRAM
1037 1059
… …
1048 poll => 'r', 1070 poll => 'r',
1049 cb => sub { 1071 cb => sub {
1050 warn "io event <$_[0]>\n"; # will always output <r> 1072 warn "io event <$_[0]>\n"; # will always output <r>
1051 chomp (my $input = <STDIN>); # read a line 1073 chomp (my $input = <STDIN>); # read a line
1052 warn "read: $input\n"; # output what has been read 1074 warn "read: $input\n"; # output what has been read
1053 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 1075 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1054 }, 1076 },
1055 ); 1077 );
1056 1078
1057 my $time_watcher; # can only be used once 1079 my $time_watcher; # can only be used once
1058 1080
… …
1063 }); 1085 });
1064 } 1086 }
1065 1087
1066 new_timer; # create first timer 1088 new_timer; # create first timer
1067 1089
1068 $cv->wait; # wait until user enters /^q/i 1090 $cv->recv; # wait until user enters /^q/i
1069 1091
1070=head1 REAL-WORLD EXAMPLE 1092=head1 REAL-WORLD EXAMPLE
1071 1093
1072Consider the L<Net::FCP> module. It features (among others) the following 1094Consider the L<Net::FCP> module. It features (among others) the following
1073API calls, which are to freenet what HTTP GET requests are to http: 1095API calls, which are to freenet what HTTP GET requests are to http:
… …
1129 1151
1130 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 1152 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
1131 1153
1132 if (end-of-file or data complete) { 1154 if (end-of-file or data complete) {
1133 $txn->{result} = $txn->{buf}; 1155 $txn->{result} = $txn->{buf};
1134 $txn->{finished}->broadcast; 1156 $txn->{finished}->send;
1135 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 1157 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
1136 } 1158 }
1137 1159
1138The C<result> method, finally, just waits for the finished signal (if the 1160The 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 1161request was already finished, it doesn't wait, of course, and returns the
1140data: 1162data:
1141 1163
1142 $txn->{finished}->wait; 1164 $txn->{finished}->recv;
1143 return $txn->{result}; 1165 return $txn->{result};
1144 1166
1145The actual code goes further and collects all errors (C<die>s, exceptions) 1167The actual code goes further and collects all errors (C<die>s, exceptions)
1146that occured during request processing. The C<result> method detects 1168that occured during request processing. The C<result> method detects
1147whether an exception as thrown (it is stored inside the $txn object) 1169whether an exception as thrown (it is stored inside the $txn object)
… …
1182 1204
1183 my $quit = AnyEvent->condvar; 1205 my $quit = AnyEvent->condvar;
1184 1206
1185 $fcp->txn_client_get ($url)->cb (sub { 1207 $fcp->txn_client_get ($url)->cb (sub {
1186 ... 1208 ...
1187 $quit->broadcast; 1209 $quit->send;
1188 }); 1210 });
1189 1211
1190 $quit->wait; 1212 $quit->recv;
1191 1213
1192 1214
1193=head1 BENCHMARKS 1215=head1 BENCHMARKS
1194 1216
1195To give you an idea of the performance and overheads that AnyEvent adds 1217To give you an idea of the performance and overheads that AnyEvent adds
… …
1224all watchers, to avoid adding memory overhead. That means closure creation 1246all watchers, to avoid adding memory overhead. That means closure creation
1225and memory usage is not included in the figures. 1247and memory usage is not included in the figures.
1226 1248
1227I<invoke> is the time, in microseconds, used to invoke a simple 1249I<invoke> is the time, in microseconds, used to invoke a simple
1228callback. The callback simply counts down a Perl variable and after it was 1250callback. The callback simply counts down a Perl variable and after it was
1229invoked "watcher" times, it would C<< ->broadcast >> a condvar once to 1251invoked "watcher" times, it would C<< ->send >> a condvar once to
1230signal the end of this phase. 1252signal the end of this phase.
1231 1253
1232I<destroy> is the time, in microseconds, that it takes to destroy a single 1254I<destroy> is the time, in microseconds, that it takes to destroy a single
1233watcher. 1255watcher.
1234 1256
… …
1487probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1509probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1488 1510
1489 1511
1490=head1 SEE ALSO 1512=head1 SEE ALSO
1491 1513
1514Utility functions: L<AnyEvent::Util>.
1515
1492Event modules: L<EV>, L<EV::Glib>, L<Glib::EV>, L<Event>, L<Glib::Event>, 1516Event 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>. 1517L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1494 1518
1495Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 1519Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1496L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 1520L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1497L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 1521L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1498L<AnyEvent::Impl::POE>. 1522L<AnyEvent::Impl::POE>.
1499 1523
1524Non-blocking file handles, sockets, TCP clients and
1525servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>.
1526
1527Asynchronous DNS: L<AnyEvent::DNS>.
1528
1500Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>, 1529Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,
1501 1530
1502Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>. 1531Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1503 1532
1504 1533
1505=head1 AUTHOR 1534=head1 AUTHOR
1506 1535
1507 Marc Lehmann <schmorp@schmorp.de> 1536 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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