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.215 by root, Tue Jun 23 12:19:33 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.
392 392
393There is a slight catch to child watchers, however: you usually start them 393There is a slight catch to child watchers, however: you usually start them
394I<after> the child process was created, and this means the process could 394I<after> the child process was created, and this means the process could
395have exited already (and no SIGCHLD will be sent anymore). 395have exited already (and no SIGCHLD will be sent anymore).
396 396
397Not all event models handle this correctly (POE doesn't), but even for 397Not all event models handle this correctly (neither POE nor IO::Async do,
398see their AnyEvent::Impl manpages for details), but even for event models
398event models that I<do> handle this correctly, they usually need to be 399that I<do> handle this correctly, they usually need to be loaded before
399loaded before the process exits (i.e. before you fork in the first place). 400the process exits (i.e. before you fork in the first place). AnyEvent's
401pure perl event loop handles all cases correctly regardless of when you
402start the watcher.
400 403
401This means you cannot create a child watcher as the very first thing in an 404This means you cannot create a child watcher as the very first
402AnyEvent program, you I<have> to create at least one watcher before you 405thing in an AnyEvent program, you I<have> to create at least one
403C<fork> the child (alternatively, you can call C<AnyEvent::detect>). 406watcher before you C<fork> the child (alternatively, you can call
407C<AnyEvent::detect>).
404 408
405Example: fork a process and wait for it 409Example: fork a process and wait for it
406 410
407 my $done = AnyEvent->condvar; 411 my $done = AnyEvent->condvar;
408 412
595 599
596=item $cv->begin ([group callback]) 600=item $cv->begin ([group callback])
597 601
598=item $cv->end 602=item $cv->end
599 603
600These two methods are EXPERIMENTAL and MIGHT CHANGE.
601
602These two methods can be used to combine many transactions/events into 604These two methods can be used to combine many transactions/events into
603one. 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
604to use a condition variable for the whole process. 606to use a condition variable for the whole process.
605 607
606Every 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
607C<< ->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
608>>, 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
609is 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
610callback was set, C<send> will be called without any arguments. 612callback was set, C<send> will be called without any arguments.
611 613
612Let'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:
613 645
614 my $cv = AnyEvent->condvar; 646 my $cv = AnyEvent->condvar;
615 647
616 my %result; 648 my %result;
617 $cv->begin (sub { $cv->send (\%result) }); 649 $cv->begin (sub { $cv->send (\%result) });
637loop, which serves two important purposes: first, it sets the callback 669loop, which serves two important purposes: first, it sets the callback
638to 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
639C<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
640doesn't execute once). 672doesn't execute once).
641 673
642This is the general pattern when you "fan out" into multiple subrequests: 674This is the general pattern when you "fan out" into multiple (but
643use 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
644is 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
645C<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>.
646 679
647=back 680=back
648 681
649=head3 METHODS FOR CONSUMERS 682=head3 METHODS FOR CONSUMERS
650 683
707variable 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
708is guaranteed not to block. 741is guaranteed not to block.
709 742
710=back 743=back
711 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
712=head1 GLOBAL VARIABLES AND FUNCTIONS 812=head1 GLOBAL VARIABLES AND FUNCTIONS
713 813
714=over 4 814=over 4
715 815
716=item $AnyEvent::MODEL 816=item $AnyEvent::MODEL
718Contains C<undef> until the first watcher is being created. Then it 818Contains C<undef> until the first watcher is being created. Then it
719contains 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
720Perl class implementing the model. This class is usually one of the 820Perl class implementing the model. This class is usually one of the
721C<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
722AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>). 822AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
723
724The known classes so far are:
725
726 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
727 AnyEvent::Impl::Event based on Event, second best choice.
728 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
729 AnyEvent::Impl::Glib based on Glib, third-best choice.
730 AnyEvent::Impl::Tk based on Tk, very bad choice.
731 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
732 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
733 AnyEvent::Impl::POE based on POE, not generic enough for full support.
734
735There is no support for WxWidgets, as WxWidgets has no support for
736watching file handles. However, you can use WxWidgets through the
737POE Adaptor, as POE has a Wx backend that simply polls 20 times per
738second, which was considered to be too horrible to even consider for
739AnyEvent. Likewise, other POE backends can be used by AnyEvent by using
740it's adaptor.
741
742AnyEvent knows about L<Prima> and L<Wx> and will try to use L<POE> when
743autodetecting them.
744 823
745=item AnyEvent::detect 824=item AnyEvent::detect
746 825
747Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model 826Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
748if necessary. You should only call this function right before you would 827if necessary. You should only call this function right before you would
831 910
832 911
833=head1 OTHER MODULES 912=head1 OTHER MODULES
834 913
835The following is a non-exhaustive list of additional modules that use 914The following is a non-exhaustive list of additional modules that use
836AnyEvent and can therefore be mixed easily with other AnyEvent modules 915AnyEvent as a client and can therefore be mixed easily with other AnyEvent
837in 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
838available via CPAN. 917come with AnyEvent, most are available via CPAN.
839 918
840=over 4 919=over 4
841 920
842=item L<AnyEvent::Util> 921=item L<AnyEvent::Util>
843 922
852 931
853=item L<AnyEvent::Handle> 932=item L<AnyEvent::Handle>
854 933
855Provide read and write buffers, manages watchers for reads and writes, 934Provide read and write buffers, manages watchers for reads and writes,
856supports 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
857non-blocking SSL/TLS. 936non-blocking SSL/TLS (via L<AnyEvent::TLS>.
858 937
859=item L<AnyEvent::DNS> 938=item L<AnyEvent::DNS>
860 939
861Provides rich asynchronous DNS resolver capabilities. 940Provides rich asynchronous DNS resolver capabilities.
862 941
890 969
891=item L<AnyEvent::GPSD> 970=item L<AnyEvent::GPSD>
892 971
893A non-blocking interface to gpsd, a daemon delivering GPS information. 972A non-blocking interface to gpsd, a daemon delivering GPS information.
894 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
895=item L<AnyEvent::IGS> 983=item L<AnyEvent::IGS>
896 984
897A non-blocking interface to the Internet Go Server protocol (used by 985A non-blocking interface to the Internet Go Server protocol (used by
898L<App::IGS>). 986L<App::IGS>).
899 987
900=item L<AnyEvent::IRC>
901
902AnyEvent based IRC client module family (replacing the older Net::IRC3).
903
904=item L<Net::XMPP2>
905
906AnyEvent based XMPP (Jabber protocol) module family.
907
908=item L<Net::FCP> 988=item L<Net::FCP>
909 989
910AnyEvent-based implementation of the Freenet Client Protocol, birthplace 990AnyEvent-based implementation of the Freenet Client Protocol, birthplace
911of AnyEvent. 991of AnyEvent.
912 992
916 996
917=item L<Coro> 997=item L<Coro>
918 998
919Has special support for AnyEvent via L<Coro::AnyEvent>. 999Has special support for AnyEvent via L<Coro::AnyEvent>.
920 1000
921=item L<IO::Lambda>
922
923The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
924
925=back 1001=back
926 1002
927=cut 1003=cut
928 1004
929package AnyEvent; 1005package AnyEvent;
931no warnings; 1007no warnings;
932use strict qw(vars subs); 1008use strict qw(vars subs);
933 1009
934use Carp; 1010use Carp;
935 1011
936our $VERSION = 4.411; 1012our $VERSION = 4.801;
937our $MODEL; 1013our $MODEL;
938 1014
939our $AUTOLOAD; 1015our $AUTOLOAD;
940our @ISA; 1016our @ISA;
941 1017
967 [Event:: => AnyEvent::Impl::Event::], 1043 [Event:: => AnyEvent::Impl::Event::],
968 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 1044 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
969 # everything below here will not be autoprobed 1045 # everything below here will not be autoprobed
970 # as the pureperl backend should work everywhere 1046 # as the pureperl backend should work everywhere
971 # and is usually faster 1047 # and is usually faster
972 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
973 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers 1048 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
974 [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
975 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1052 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
976 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
977 [Wx:: => AnyEvent::Impl::POE::], 1053 [Wx:: => AnyEvent::Impl::POE::],
978 [Prima:: => AnyEvent::Impl::POE::], 1054 [Prima:: => AnyEvent::Impl::POE::],
1055 # IO::Async is just too broken - we would need workarounds for its
1056 # byzantine signal and broken child handling, among others.
1057 # IO::Async is rather hard to detect, as it doesn't have any
1058 # obvious default class.
1059# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1060# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1061# [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
979); 1062);
980 1063
981our %method = map +($_ => 1), 1064our %method = map +($_ => 1),
982 qw(io timer time now now_update signal child idle condvar one_event DESTROY); 1065 qw(io timer time now now_update signal child idle condvar one_event DESTROY);
983 1066
1075} 1158}
1076 1159
1077# utility function to dup a filehandle. this is used by many backends 1160# utility function to dup a filehandle. this is used by many backends
1078# to support binding more than one watcher per filehandle (they usually 1161# to support binding more than one watcher per filehandle (they usually
1079# 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).
1080sub _dupfh($$$$) { 1163sub _dupfh($$;$$) {
1081 my ($poll, $fh, $r, $w) = @_; 1164 my ($poll, $fh, $r, $w) = @_;
1082 1165
1083 # cygwin requires the fh mode to be matching, unix doesn't 1166 # cygwin requires the fh mode to be matching, unix doesn't
1084 my ($rw, $mode) = $poll eq "r" ? ($r, "<") 1167 my ($rw, $mode) = $poll eq "r" ? ($r, "<") : ($w, ">");
1085 : $poll eq "w" ? ($w, ">")
1086 : Carp::croak "AnyEvent->io requires poll set to either 'r' or 'w'";
1087 1168
1088 open my $fh2, "$mode&" . fileno $fh 1169 open my $fh2, "$mode&", $fh
1089 or die "cannot dup() filehandle: $!,"; 1170 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,";
1090 1171
1091 # 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
1092 1173
1093 ($fh2, $rw) 1174 ($fh2, $rw)
1094} 1175}
1366=item C<PERL_ANYEVENT_STRICT> 1447=item C<PERL_ANYEVENT_STRICT>
1367 1448
1368AnyEvent does not do much argument checking by default, as thorough 1449AnyEvent does not do much argument checking by default, as thorough
1369argument checking is very costly. Setting this variable to a true value 1450argument checking is very costly. Setting this variable to a true value
1370will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly 1451will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1371check the arguments passed to most method calls. If it finds any problems 1452check the arguments passed to most method calls. If it finds any problems,
1372it will croak. 1453it will croak.
1373 1454
1374In other words, enables "strict" mode. 1455In other words, enables "strict" mode.
1375 1456
1376Unlike C<use strict>, it is definitely recommended ot keep it off in 1457Unlike C<use strict>, it is definitely recommended to keep it off in
1377production. Keeping C<PERL_ANYEVENT_STRICT=1> in your environment while 1458production. Keeping C<PERL_ANYEVENT_STRICT=1> in your environment while
1378developing programs can be very useful, however. 1459developing programs can be very useful, however.
1379 1460
1380=item C<PERL_ANYEVENT_MODEL> 1461=item C<PERL_ANYEVENT_MODEL>
1381 1462
1426 1507
1427=item C<PERL_ANYEVENT_MAX_FORKS> 1508=item C<PERL_ANYEVENT_MAX_FORKS>
1428 1509
1429The maximum number of child processes that C<AnyEvent::Util::fork_call> 1510The maximum number of child processes that C<AnyEvent::Util::fork_call>
1430will 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.
1431 1531
1432=back 1532=back
1433 1533
1434=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1534=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1435 1535
1680 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers 1780 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
1681 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal 1781 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
1682 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation 1782 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
1683 Event/Event 16000 517 32.20 31.80 0.81 Event native interface 1783 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
1684 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers 1784 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
1785 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll
1786 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll
1685 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour 1787 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
1686 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers 1788 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
1687 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event 1789 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1688 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select 1790 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1689 1791
1718performance becomes really bad with lots of file descriptors (and few of 1820performance becomes really bad with lots of file descriptors (and few of
1719them active), of course, but this was not subject of this benchmark. 1821them active), of course, but this was not subject of this benchmark.
1720 1822
1721The C<Event> module has a relatively high setup and callback invocation 1823The C<Event> module has a relatively high setup and callback invocation
1722cost, but overall scores in on the third place. 1824cost, but overall scores in on the third place.
1825
1826C<IO::Async> performs admirably well, about on par with C<Event>, even
1827when using its pure perl backend.
1723 1828
1724C<Glib>'s memory usage is quite a bit higher, but it features a 1829C<Glib>'s memory usage is quite a bit higher, but it features a
1725faster callback invocation and overall ends up in the same class as 1830faster callback invocation and overall ends up in the same class as
1726C<Event>. However, Glib scales extremely badly, doubling the number of 1831C<Event>. However, Glib scales extremely badly, doubling the number of
1727watchers increases the processing time by more than a factor of four, 1832watchers increases the processing time by more than a factor of four,
1805it to another server. This includes deleting the old timeout and creating 1910it to another server. This includes deleting the old timeout and creating
1806a new one that moves the timeout into the future. 1911a new one that moves the timeout into the future.
1807 1912
1808=head3 Results 1913=head3 Results
1809 1914
1810 name sockets create request 1915 name sockets create request
1811 EV 20000 69.01 11.16 1916 EV 20000 69.01 11.16
1812 Perl 20000 73.32 35.87 1917 Perl 20000 73.32 35.87
1918 IOAsync 20000 157.00 98.14 epoll
1919 IOAsync 20000 159.31 616.06 poll
1813 Event 20000 212.62 257.32 1920 Event 20000 212.62 257.32
1814 Glib 20000 651.16 1896.30 1921 Glib 20000 651.16 1896.30
1815 POE 20000 349.67 12317.24 uses POE::Loop::Event 1922 POE 20000 349.67 12317.24 uses POE::Loop::Event
1816 1923
1817=head3 Discussion 1924=head3 Discussion
1818 1925
1819This benchmark I<does> measure scalability and overall performance of the 1926This benchmark I<does> measure scalability and overall performance of the
1820particular event loop. 1927particular event loop.
1822EV is again fastest. Since it is using epoll on my system, the setup time 1929EV is again fastest. Since it is using epoll on my system, the setup time
1823is relatively high, though. 1930is relatively high, though.
1824 1931
1825Perl surprisingly comes second. It is much faster than the C-based event 1932Perl surprisingly comes second. It is much faster than the C-based event
1826loops Event and Glib. 1933loops Event and Glib.
1934
1935IO::Async performs very well when using its epoll backend, and still quite
1936good compared to Glib when using its pure perl backend.
1827 1937
1828Event suffers from high setup time as well (look at its code and you will 1938Event suffers from high setup time as well (look at its code and you will
1829understand why). Callback invocation also has a high overhead compared to 1939understand why). Callback invocation also has a high overhead compared to
1830the C<< $_->() for .. >>-style loop that the Perl event loop uses. Event 1940the C<< $_->() for .. >>-style loop that the Perl event loop uses. Event
1831uses select or poll in basically all documented configurations. 1941uses select or poll in basically all documented configurations.
1900 2010
1901Recently I was told about the benchmark in the IO::Lambda manpage, which 2011Recently I was told about the benchmark in the IO::Lambda manpage, which
1902could be misinterpreted to make AnyEvent look bad. In fact, the benchmark 2012could be misinterpreted to make AnyEvent look bad. In fact, the benchmark
1903simply compares IO::Lambda with POE, and IO::Lambda looks better (which 2013simply compares IO::Lambda with POE, and IO::Lambda looks better (which
1904shouldn't come as a surprise to anybody). As such, the benchmark is 2014shouldn't come as a surprise to anybody). As such, the benchmark is
1905fine, and shows that the AnyEvent backend from IO::Lambda isn't very 2015fine, and mostly shows that the AnyEvent backend from IO::Lambda isn't
1906optimal. But how would AnyEvent compare when used without the extra 2016very optimal. But how would AnyEvent compare when used without the extra
1907baggage? To explore this, I wrote the equivalent benchmark for AnyEvent. 2017baggage? To explore this, I wrote the equivalent benchmark for AnyEvent.
1908 2018
1909The benchmark itself creates an echo-server, and then, for 500 times, 2019The benchmark itself creates an echo-server, and then, for 500 times,
1910connects to the echo server, sends a line, waits for the reply, and then 2020connects to the echo server, sends a line, waits for the reply, and then
1911creates the next connection. This is a rather bad benchmark, as it doesn't 2021creates the next connection. This is a rather bad benchmark, as it doesn't
1912test the efficiency of the framework, but it is a benchmark nevertheless. 2022test the efficiency of the framework or much non-blocking I/O, but it is a
2023benchmark nevertheless.
1913 2024
1914 name runtime 2025 name runtime
1915 Lambda/select 0.330 sec 2026 Lambda/select 0.330 sec
1916 + optimized 0.122 sec 2027 + optimized 0.122 sec
1917 Lambda/AnyEvent 0.327 sec 2028 Lambda/AnyEvent 0.327 sec
1923 2034
1924 AnyEvent/select/nb 0.085 sec 2035 AnyEvent/select/nb 0.085 sec
1925 AnyEvent/EV/nb 0.068 sec 2036 AnyEvent/EV/nb 0.068 sec
1926 +state machine 0.134 sec 2037 +state machine 0.134 sec
1927 2038
1928The benchmark is also a bit unfair (my fault) - the IO::Lambda 2039The benchmark is also a bit unfair (my fault): the IO::Lambda/POE
1929benchmarks actually make blocking connects and use 100% blocking I/O, 2040benchmarks actually make blocking connects and use 100% blocking I/O,
1930defeating the purpose of an event-based solution. All of the newly 2041defeating the purpose of an event-based solution. All of the newly
1931written AnyEvent benchmarks use 100% non-blocking connects (using 2042written AnyEvent benchmarks use 100% non-blocking connects (using
1932AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS 2043AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
1933resolver), so AnyEvent is at a disadvantage here as non-blocking connects 2044resolver), so AnyEvent is at a disadvantage here, as non-blocking connects
1934generally require a lot more bookkeeping and event handling than blocking 2045generally require a lot more bookkeeping and event handling than blocking
1935connects (which involve a single syscall only). 2046connects (which involve a single syscall only).
1936 2047
1937The last AnyEvent benchmark additionally uses L<AnyEvent::Handle>, which 2048The last AnyEvent benchmark additionally uses L<AnyEvent::Handle>, which
1938offers similar expressive power as POE and IO::Lambda (using conventional 2049offers similar expressive power as POE and IO::Lambda, using conventional
1939Perl syntax), which means both the echo server and the client are 100% 2050Perl syntax. This means that both the echo server and the client are 100%
1940non-blocking w.r.t. I/O, further placing it at a disadvantage. 2051non-blocking, further placing it at a disadvantage.
1941 2052
1942As you can see, AnyEvent + EV even beats the hand-optimised "raw sockets 2053As you can see, the AnyEvent + EV combination even beats the
1943benchmark", while AnyEvent + its pure perl backend easily beats 2054hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
1944IO::Lambda and POE. 2055backend easily beats IO::Lambda and POE.
1945 2056
1946And even the 100% non-blocking version written using the high-level (and 2057And even the 100% non-blocking version written using the high-level (and
1947slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda, 2058slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda by a
1948even thought it does all of DNS, tcp-connect and socket I/O in a 2059large margin, even though it does all of DNS, tcp-connect and socket I/O
1949non-blocking way. 2060in a non-blocking way.
2061
2062The two AnyEvent benchmarks programs can be found as F<eg/ae0.pl> and
2063F<eg/ae2.pl> in the AnyEvent distribution, the remaining benchmarks are
2064part of the IO::lambda distribution and were used without any changes.
1950 2065
1951 2066
1952=head1 SIGNALS 2067=head1 SIGNALS
1953 2068
1954AnyEvent currently installs handlers for these signals: 2069AnyEvent currently installs handlers for these signals:
1958=item SIGCHLD 2073=item SIGCHLD
1959 2074
1960A handler for C<SIGCHLD> is installed by AnyEvent's child watcher 2075A handler for C<SIGCHLD> is installed by AnyEvent's child watcher
1961emulation for event loops that do not support them natively. Also, some 2076emulation for event loops that do not support them natively. Also, some
1962event loops install a similar handler. 2077event loops install a similar handler.
2078
2079If, when AnyEvent is loaded, SIGCHLD is set to IGNORE, then AnyEvent will
2080reset it to default, to avoid losing child exit statuses.
1963 2081
1964=item SIGPIPE 2082=item SIGPIPE
1965 2083
1966A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef> 2084A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef>
1967when AnyEvent gets loaded. 2085when AnyEvent gets loaded.
1979 2097
1980=back 2098=back
1981 2099
1982=cut 2100=cut
1983 2101
2102undef $SIG{CHLD}
2103 if $SIG{CHLD} eq 'IGNORE';
2104
1984$SIG{PIPE} = sub { } 2105$SIG{PIPE} = sub { }
1985 unless defined $SIG{PIPE}; 2106 unless defined $SIG{PIPE};
1986
1987 2107
1988=head1 FORK 2108=head1 FORK
1989 2109
1990Most event libraries are not fork-safe. The ones who are usually are 2110Most event libraries are not fork-safe. The ones who are usually are
1991because they rely on inefficient but fork-safe C<select> or C<poll> 2111because they rely on inefficient but fork-safe C<select> or C<poll>
2014Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 2134Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
2015be used to probe what backend is used and gain other information (which is 2135be used to probe what backend is used and gain other information (which is
2016probably even less useful to an attacker than PERL_ANYEVENT_MODEL), and 2136probably even less useful to an attacker than PERL_ANYEVENT_MODEL), and
2017$ENV{PERL_ANYEVENT_STRICT}. 2137$ENV{PERL_ANYEVENT_STRICT}.
2018 2138
2139Note that AnyEvent will remove I<all> environment variables starting with
2140C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is
2141enabled.
2142
2019 2143
2020=head1 BUGS 2144=head1 BUGS
2021 2145
2022Perl 5.8 has numerous memleaks that sometimes hit this module and are hard 2146Perl 5.8 has numerous memleaks that sometimes hit this module and are hard
2023to work around. If you suffer from memleaks, first upgrade to Perl 5.10 2147to work around. If you suffer from memleaks, first upgrade to Perl 5.10
2034L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2158L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
2035 2159
2036Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2160Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2037L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2161L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2038L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2162L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2039L<AnyEvent::Impl::POE>. 2163L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>.
2040 2164
2041Non-blocking file handles, sockets, TCP clients and 2165Non-blocking file handles, sockets, TCP clients and
2042servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>. 2166servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2043 2167
2044Asynchronous DNS: L<AnyEvent::DNS>. 2168Asynchronous DNS: L<AnyEvent::DNS>.
2045 2169
2046Coroutine 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>,
2047 2172
2048Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>. 2173Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::XMPP>,
2174L<AnyEvent::HTTP>.
2049 2175
2050 2176
2051=head1 AUTHOR 2177=head1 AUTHOR
2052 2178
2053 Marc Lehmann <schmorp@schmorp.de> 2179 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines