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.206 by root, Mon Apr 20 14:34:18 2009 UTC vs.
Revision 1.231 by root, Wed Jul 8 13:46:46 2009 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 and POE are various supported
6event loops.
6 7
7=head1 SYNOPSIS 8=head1 SYNOPSIS
8 9
9 use AnyEvent; 10 use AnyEvent;
10 11
12 # file descriptor readable
11 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { ... }); 13 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
12 14
15 # one-shot or repeating timers
13 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... }); 16 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
14 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ... 17 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
15 18
16 print AnyEvent->now; # prints current event loop time 19 print AnyEvent->now; # prints current event loop time
17 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time. 20 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
18 21
22 # POSIX signal
19 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... }); 23 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
20 24
25 # child process exit
21 my $w = AnyEvent->child (pid => $pid, cb => sub { 26 my $w = AnyEvent->child (pid => $pid, cb => sub {
22 my ($pid, $status) = @_; 27 my ($pid, $status) = @_;
23 ... 28 ...
24 }); 29 });
30
31 # called when event loop idle (if applicable)
32 my $w = AnyEvent->idle (cb => sub { ... });
25 33
26 my $w = AnyEvent->condvar; # stores whether a condition was flagged 34 my $w = AnyEvent->condvar; # stores whether a condition was flagged
27 $w->send; # wake up current and all future recv's 35 $w->send; # wake up current and all future recv's
28 $w->recv; # enters "main loop" till $condvar gets ->send 36 $w->recv; # enters "main loop" till $condvar gets ->send
29 # use a condvar in callback mode: 37 # use a condvar in callback mode:
… …
168=head2 I/O WATCHERS 176=head2 I/O WATCHERS
169 177
170You 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
171with the following mandatory key-value pairs as arguments: 179with the following mandatory key-value pairs as arguments:
172 180
173C<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
174for 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
175handle). Note that only file handles pointing to things for which 183handle). Note that only file handles pointing to things for which
176non-blocking operation makes sense are allowed. This includes sockets, 184non-blocking operation makes sense are allowed. This includes sockets,
177most 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
178or block devices. 186or block devices.
… …
384 392
385There 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
386I<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
387have exited already (and no SIGCHLD will be sent anymore). 395have exited already (and no SIGCHLD will be sent anymore).
388 396
389Not 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
390event 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
391loaded 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.
392 403
393This 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
394AnyEvent 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
395C<fork> the child (alternatively, you can call C<AnyEvent::detect>). 406watcher before you C<fork> the child (alternatively, you can call
407C<AnyEvent::detect>).
396 408
397Example: fork a process and wait for it 409Example: fork a process and wait for it
398 410
399 my $done = AnyEvent->condvar; 411 my $done = AnyEvent->condvar;
400 412
… …
410 ); 422 );
411 423
412 # do something else, then wait for process exit 424 # do something else, then wait for process exit
413 $done->recv; 425 $done->recv;
414 426
427=head2 IDLE WATCHERS
428
429Sometimes there is a need to do something, but it is not so important
430to do it instantly, but only when there is nothing better to do. This
431"nothing better to do" is usually defined to be "no other events need
432attention by the event loop".
433
434Idle watchers ideally get invoked when the event loop has nothing
435better to do, just before it would block the process to wait for new
436events. Instead of blocking, the idle watcher is invoked.
437
438Most event loops unfortunately do not really support idle watchers (only
439EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
440will simply call the callback "from time to time".
441
442Example: read lines from STDIN, but only process them when the
443program is otherwise idle:
444
445 my @lines; # read data
446 my $idle_w;
447 my $io_w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
448 push @lines, scalar <STDIN>;
449
450 # start an idle watcher, if not already done
451 $idle_w ||= AnyEvent->idle (cb => sub {
452 # handle only one line, when there are lines left
453 if (my $line = shift @lines) {
454 print "handled when idle: $line";
455 } else {
456 # otherwise disable the idle watcher again
457 undef $idle_w;
458 }
459 });
460 });
461
415=head2 CONDITION VARIABLES 462=head2 CONDITION VARIABLES
416 463
417If you are familiar with some event loops you will know that all of them 464If you are familiar with some event loops you will know that all of them
418require you to run some blocking "loop", "run" or similar function that 465require you to run some blocking "loop", "run" or similar function that
419will actively watch for new events and call your callbacks. 466will actively watch for new events and call your callbacks.
… …
552 599
553=item $cv->begin ([group callback]) 600=item $cv->begin ([group callback])
554 601
555=item $cv->end 602=item $cv->end
556 603
557These two methods are EXPERIMENTAL and MIGHT CHANGE.
558
559These two methods can be used to combine many transactions/events into 604These two methods can be used to combine many transactions/events into
560one. 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
561to use a condition variable for the whole process. 606to use a condition variable for the whole process.
562 607
563Every 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
564C<< ->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
565>>, 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
566is 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
567callback was set, C<send> will be called without any arguments. 612callback was set, C<send> will be called without any arguments.
568 613
569Let'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:
570 645
571 my $cv = AnyEvent->condvar; 646 my $cv = AnyEvent->condvar;
572 647
573 my %result; 648 my %result;
574 $cv->begin (sub { $cv->send (\%result) }); 649 $cv->begin (sub { $cv->send (\%result) });
… …
594loop, which serves two important purposes: first, it sets the callback 669loop, which serves two important purposes: first, it sets the callback
595to 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
596C<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
597doesn't execute once). 672doesn't execute once).
598 673
599This is the general pattern when you "fan out" into multiple subrequests: 674This is the general pattern when you "fan out" into multiple (but
600use 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
601is 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
602C<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>.
603 679
604=back 680=back
605 681
606=head3 METHODS FOR CONSUMERS 682=head3 METHODS FOR CONSUMERS
607 683
… …
687 AnyEvent::Impl::Tk based on Tk, very bad choice. 763 AnyEvent::Impl::Tk based on Tk, very bad choice.
688 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). 764 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
689 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 765 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
690 AnyEvent::Impl::POE based on POE, not generic enough for full support. 766 AnyEvent::Impl::POE based on POE, not generic enough for full support.
691 767
768 # warning, support for IO::Async is only partial, as it is too broken
769 # and limited toe ven support the AnyEvent API. See AnyEvent::Impl::Async.
770 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed (see its docs).
771
692There is no support for WxWidgets, as WxWidgets has no support for 772There is no support for WxWidgets, as WxWidgets has no support for
693watching file handles. However, you can use WxWidgets through the 773watching file handles. However, you can use WxWidgets through the
694POE Adaptor, as POE has a Wx backend that simply polls 20 times per 774POE Adaptor, as POE has a Wx backend that simply polls 20 times per
695second, which was considered to be too horrible to even consider for 775second, which was considered to be too horrible to even consider for
696AnyEvent. Likewise, other POE backends can be used by AnyEvent by using 776AnyEvent. Likewise, other POE backends can be used by AnyEvent by using
… …
788 868
789 869
790=head1 OTHER MODULES 870=head1 OTHER MODULES
791 871
792The following is a non-exhaustive list of additional modules that use 872The following is a non-exhaustive list of additional modules that use
793AnyEvent and can therefore be mixed easily with other AnyEvent modules 873AnyEvent as a client and can therefore be mixed easily with other AnyEvent
794in 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
795available via CPAN. 875come with AnyEvent, most are available via CPAN.
796 876
797=over 4 877=over 4
798 878
799=item L<AnyEvent::Util> 879=item L<AnyEvent::Util>
800 880
… …
809 889
810=item L<AnyEvent::Handle> 890=item L<AnyEvent::Handle>
811 891
812Provide read and write buffers, manages watchers for reads and writes, 892Provide read and write buffers, manages watchers for reads and writes,
813supports 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
814non-blocking SSL/TLS. 894non-blocking SSL/TLS (via L<AnyEvent::TLS>.
815 895
816=item L<AnyEvent::DNS> 896=item L<AnyEvent::DNS>
817 897
818Provides rich asynchronous DNS resolver capabilities. 898Provides rich asynchronous DNS resolver capabilities.
819 899
… …
847 927
848=item L<AnyEvent::GPSD> 928=item L<AnyEvent::GPSD>
849 929
850A non-blocking interface to gpsd, a daemon delivering GPS information. 930A non-blocking interface to gpsd, a daemon delivering GPS information.
851 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
852=item L<AnyEvent::IGS> 941=item L<AnyEvent::IGS>
853 942
854A non-blocking interface to the Internet Go Server protocol (used by 943A non-blocking interface to the Internet Go Server protocol (used by
855L<App::IGS>). 944L<App::IGS>).
856 945
857=item L<AnyEvent::IRC>
858
859AnyEvent based IRC client module family (replacing the older Net::IRC3).
860
861=item L<Net::XMPP2>
862
863AnyEvent based XMPP (Jabber protocol) module family.
864
865=item L<Net::FCP> 946=item L<Net::FCP>
866 947
867AnyEvent-based implementation of the Freenet Client Protocol, birthplace 948AnyEvent-based implementation of the Freenet Client Protocol, birthplace
868of AnyEvent. 949of AnyEvent.
869 950
… …
873 954
874=item L<Coro> 955=item L<Coro>
875 956
876Has special support for AnyEvent via L<Coro::AnyEvent>. 957Has special support for AnyEvent via L<Coro::AnyEvent>.
877 958
878=item L<IO::Lambda>
879
880The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
881
882=back 959=back
883 960
884=cut 961=cut
885 962
886package AnyEvent; 963package AnyEvent;
… …
888no warnings; 965no warnings;
889use strict qw(vars subs); 966use strict qw(vars subs);
890 967
891use Carp; 968use Carp;
892 969
893our $VERSION = 4.352; 970our $VERSION = 4.801;
894our $MODEL; 971our $MODEL;
895 972
896our $AUTOLOAD; 973our $AUTOLOAD;
897our @ISA; 974our @ISA;
898 975
899our @REGISTRY; 976our @REGISTRY;
900 977
901our $WIN32; 978our $WIN32;
902 979
903BEGIN { 980BEGIN {
904 my $win32 = ! ! ($^O =~ /mswin32/i); 981 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }";
905 eval "sub WIN32(){ $win32 }"; 982 eval "sub TAINT(){ " . (${^TAINT}*1) . " }";
983
984 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
985 if ${^TAINT};
906} 986}
907 987
908our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 988our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
909 989
910our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 990our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
… …
928 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1008 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
929 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1009 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
930 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1010 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
931 [Wx:: => AnyEvent::Impl::POE::], 1011 [Wx:: => AnyEvent::Impl::POE::],
932 [Prima:: => AnyEvent::Impl::POE::], 1012 [Prima:: => AnyEvent::Impl::POE::],
1013 # IO::Async is just too broken - we would need workaorunds for its
1014 # byzantine signal and broken child handling, among others.
1015 # IO::Async is rather hard to detect, as it doesn't have any
1016 # obvious default class.
1017# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1018# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1019# [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
933); 1020);
934 1021
935our %method = map +($_ => 1), 1022our %method = map +($_ => 1),
936 qw(io timer time now now_update signal child condvar one_event DESTROY); 1023 qw(io timer time now now_update signal child idle condvar one_event DESTROY);
937 1024
938our @post_detect; 1025our @post_detect;
939 1026
940sub post_detect(&) { 1027sub post_detect(&) {
941 my ($cb) = @_; 1028 my ($cb) = @_;
… …
946 1 1033 1
947 } else { 1034 } else {
948 push @post_detect, $cb; 1035 push @post_detect, $cb;
949 1036
950 defined wantarray 1037 defined wantarray
951 ? bless \$cb, "AnyEvent::Util::PostDetect" 1038 ? bless \$cb, "AnyEvent::Util::postdetect"
952 : () 1039 : ()
953 } 1040 }
954} 1041}
955 1042
956sub AnyEvent::Util::PostDetect::DESTROY { 1043sub AnyEvent::Util::postdetect::DESTROY {
957 @post_detect = grep $_ != ${$_[0]}, @post_detect; 1044 @post_detect = grep $_ != ${$_[0]}, @post_detect;
958} 1045}
959 1046
960sub detect() { 1047sub detect() {
961 unless ($MODEL) { 1048 unless ($MODEL) {
… …
1029} 1116}
1030 1117
1031# utility function to dup a filehandle. this is used by many backends 1118# utility function to dup a filehandle. this is used by many backends
1032# to support binding more than one watcher per filehandle (they usually 1119# to support binding more than one watcher per filehandle (they usually
1033# 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).
1034sub _dupfh($$$$) { 1121sub _dupfh($$;$$) {
1035 my ($poll, $fh, $r, $w) = @_; 1122 my ($poll, $fh, $r, $w) = @_;
1036 1123
1037 # cygwin requires the fh mode to be matching, unix doesn't 1124 # cygwin requires the fh mode to be matching, unix doesn't
1038 my ($rw, $mode) = $poll eq "r" ? ($r, "<") 1125 my ($rw, $mode) = $poll eq "r" ? ($r, "<") : ($w, ">");
1039 : $poll eq "w" ? ($w, ">")
1040 : Carp::croak "AnyEvent->io requires poll set to either 'r' or 'w'";
1041 1126
1042 open my $fh2, "$mode&" . fileno $fh 1127 open my $fh2, "$mode&", $fh
1043 or die "cannot dup() filehandle: $!,"; 1128 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,";
1044 1129
1045 # 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
1046 1131
1047 ($fh2, $rw) 1132 ($fh2, $rw)
1048} 1133}
… …
1050package AnyEvent::Base; 1135package AnyEvent::Base;
1051 1136
1052# default implementations for many methods 1137# default implementations for many methods
1053 1138
1054BEGIN { 1139BEGIN {
1055 if (eval "use Time::HiRes (); time (); 1") { 1140 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1056 *_time = \&Time::HiRes::time; 1141 *_time = \&Time::HiRes::time;
1057 # if (eval "use POSIX (); (POSIX::times())... 1142 # if (eval "use POSIX (); (POSIX::times())...
1058 } else { 1143 } else {
1059 *_time = sub { time }; # epic fail 1144 *_time = sub { time }; # epic fail
1060 } 1145 }
… …
1065sub now_update { } 1150sub now_update { }
1066 1151
1067# default implementation for ->condvar 1152# default implementation for ->condvar
1068 1153
1069sub condvar { 1154sub condvar {
1070 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar:: 1155 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar"
1071} 1156}
1072 1157
1073# default implementation for ->signal 1158# default implementation for ->signal
1074 1159
1075our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO); 1160our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
… …
1099 AnyEvent::Util::fh_nonblocking ($SIGPIPE_W) if $SIGPIPE_W; # just in case 1184 AnyEvent::Util::fh_nonblocking ($SIGPIPE_W) if $SIGPIPE_W; # just in case
1100 } else { 1185 } else {
1101 pipe $SIGPIPE_R, $SIGPIPE_W; 1186 pipe $SIGPIPE_R, $SIGPIPE_W;
1102 fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R; 1187 fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R;
1103 fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case 1188 fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case
1189
1190 # not strictly required, as $^F is normally 2, but let's make sure...
1191 fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1192 fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1104 } 1193 }
1105 1194
1106 $SIGPIPE_R 1195 $SIGPIPE_R
1107 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n"; 1196 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1108
1109 # not strictly required, as $^F is normally 2, but let's make sure...
1110 fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1111 fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1112 1197
1113 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec); 1198 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec);
1114 } 1199 }
1115 1200
1116 my $signal = uc $arg{signal} 1201 my $signal = uc $arg{signal}
… …
1121 local $!; 1206 local $!;
1122 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV; 1207 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1123 undef $SIG_EV{$signal}; 1208 undef $SIG_EV{$signal};
1124 }; 1209 };
1125 1210
1126 bless [$signal, $arg{cb}], "AnyEvent::Base::Signal" 1211 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1127} 1212}
1128 1213
1129sub AnyEvent::Base::Signal::DESTROY { 1214sub AnyEvent::Base::signal::DESTROY {
1130 my ($signal, $cb) = @{$_[0]}; 1215 my ($signal, $cb) = @{$_[0]};
1131 1216
1132 delete $SIG_CB{$signal}{$cb}; 1217 delete $SIG_CB{$signal}{$cb};
1133 1218
1219 # delete doesn't work with older perls - they then
1220 # print weird messages, or just unconditionally exit
1221 # instead of getting the default action.
1134 delete $SIG{$signal} unless keys %{ $SIG_CB{$signal} }; 1222 undef $SIG{$signal} unless keys %{ $SIG_CB{$signal} };
1135} 1223}
1136 1224
1137# default implementation for ->child 1225# default implementation for ->child
1138 1226
1139our %PID_CB; 1227our %PID_CB;
1140our $CHLD_W; 1228our $CHLD_W;
1141our $CHLD_DELAY_W; 1229our $CHLD_DELAY_W;
1142our $PID_IDLE;
1143our $WNOHANG; 1230our $WNOHANG;
1144 1231
1145sub _child_wait { 1232sub _sigchld {
1146 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 1233 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
1147 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }), 1234 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }),
1148 (values %{ $PID_CB{0} || {} }); 1235 (values %{ $PID_CB{0} || {} });
1149 } 1236 }
1150
1151 undef $PID_IDLE;
1152}
1153
1154sub _sigchld {
1155 # make sure we deliver these changes "synchronous" with the event loop.
1156 $CHLD_DELAY_W ||= AnyEvent->timer (after => 0, cb => sub {
1157 undef $CHLD_DELAY_W;
1158 &_child_wait;
1159 });
1160} 1237}
1161 1238
1162sub child { 1239sub child {
1163 my (undef, %arg) = @_; 1240 my (undef, %arg) = @_;
1164 1241
1165 defined (my $pid = $arg{pid} + 0) 1242 defined (my $pid = $arg{pid} + 0)
1166 or Carp::croak "required option 'pid' is missing"; 1243 or Carp::croak "required option 'pid' is missing";
1167 1244
1168 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1245 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
1169 1246
1170 unless ($WNOHANG) {
1171 $WNOHANG = eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1; 1247 $WNOHANG ||= eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
1172 }
1173 1248
1174 unless ($CHLD_W) { 1249 unless ($CHLD_W) {
1175 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1250 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
1176 # child could be a zombie already, so make at least one round 1251 # child could be a zombie already, so make at least one round
1177 &_sigchld; 1252 &_sigchld;
1178 } 1253 }
1179 1254
1180 bless [$pid, $arg{cb}], "AnyEvent::Base::Child" 1255 bless [$pid, $arg{cb}], "AnyEvent::Base::child"
1181} 1256}
1182 1257
1183sub AnyEvent::Base::Child::DESTROY { 1258sub AnyEvent::Base::child::DESTROY {
1184 my ($pid, $cb) = @{$_[0]}; 1259 my ($pid, $cb) = @{$_[0]};
1185 1260
1186 delete $PID_CB{$pid}{$cb}; 1261 delete $PID_CB{$pid}{$cb};
1187 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} }; 1262 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
1188 1263
1189 undef $CHLD_W unless keys %PID_CB; 1264 undef $CHLD_W unless keys %PID_CB;
1265}
1266
1267# idle emulation is done by simply using a timer, regardless
1268# of whether the process is idle or not, and not letting
1269# the callback use more than 50% of the time.
1270sub idle {
1271 my (undef, %arg) = @_;
1272
1273 my ($cb, $w, $rcb) = $arg{cb};
1274
1275 $rcb = sub {
1276 if ($cb) {
1277 $w = _time;
1278 &$cb;
1279 $w = _time - $w;
1280
1281 # never use more then 50% of the time for the idle watcher,
1282 # within some limits
1283 $w = 0.0001 if $w < 0.0001;
1284 $w = 5 if $w > 5;
1285
1286 $w = AnyEvent->timer (after => $w, cb => $rcb);
1287 } else {
1288 # clean up...
1289 undef $w;
1290 undef $rcb;
1291 }
1292 };
1293
1294 $w = AnyEvent->timer (after => 0.05, cb => $rcb);
1295
1296 bless \\$cb, "AnyEvent::Base::idle"
1297}
1298
1299sub AnyEvent::Base::idle::DESTROY {
1300 undef $${$_[0]};
1190} 1301}
1191 1302
1192package AnyEvent::CondVar; 1303package AnyEvent::CondVar;
1193 1304
1194our @ISA = AnyEvent::CondVar::Base::; 1305our @ISA = AnyEvent::CondVar::Base::;
… …
1268so on. 1379so on.
1269 1380
1270=head1 ENVIRONMENT VARIABLES 1381=head1 ENVIRONMENT VARIABLES
1271 1382
1272The following environment variables are used by this module or its 1383The following environment variables are used by this module or its
1273submodules: 1384submodules.
1385
1386Note that AnyEvent will remove I<all> environment variables starting with
1387C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is
1388enabled.
1274 1389
1275=over 4 1390=over 4
1276 1391
1277=item C<PERL_ANYEVENT_VERBOSE> 1392=item C<PERL_ANYEVENT_VERBOSE>
1278 1393
… …
1290=item C<PERL_ANYEVENT_STRICT> 1405=item C<PERL_ANYEVENT_STRICT>
1291 1406
1292AnyEvent does not do much argument checking by default, as thorough 1407AnyEvent does not do much argument checking by default, as thorough
1293argument checking is very costly. Setting this variable to a true value 1408argument checking is very costly. Setting this variable to a true value
1294will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly 1409will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1295check the arguments passed to most method calls. If it finds any problems 1410check the arguments passed to most method calls. If it finds any problems,
1296it will croak. 1411it will croak.
1297 1412
1298In other words, enables "strict" mode. 1413In other words, enables "strict" mode.
1299 1414
1300Unlike C<use strict>, it is definitely recommended ot keep it off in 1415Unlike C<use strict>, it is definitely recommended to keep it off in
1301production. Keeping C<PERL_ANYEVENT_STRICT=1> in your environment while 1416production. Keeping C<PERL_ANYEVENT_STRICT=1> in your environment while
1302developing programs can be very useful, however. 1417developing programs can be very useful, however.
1303 1418
1304=item C<PERL_ANYEVENT_MODEL> 1419=item C<PERL_ANYEVENT_MODEL>
1305 1420
… …
1350 1465
1351=item C<PERL_ANYEVENT_MAX_FORKS> 1466=item C<PERL_ANYEVENT_MAX_FORKS>
1352 1467
1353The maximum number of child processes that C<AnyEvent::Util::fork_call> 1468The maximum number of child processes that C<AnyEvent::Util::fork_call>
1354will 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.
1355 1489
1356=back 1490=back
1357 1491
1358=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1492=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1359 1493
… …
1604 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers 1738 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
1605 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal 1739 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
1606 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation 1740 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
1607 Event/Event 16000 517 32.20 31.80 0.81 Event native interface 1741 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
1608 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers 1742 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
1743 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll
1744 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll
1609 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour 1745 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
1610 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers 1746 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
1611 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event 1747 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1612 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select 1748 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1613 1749
… …
1642performance becomes really bad with lots of file descriptors (and few of 1778performance becomes really bad with lots of file descriptors (and few of
1643them active), of course, but this was not subject of this benchmark. 1779them active), of course, but this was not subject of this benchmark.
1644 1780
1645The C<Event> module has a relatively high setup and callback invocation 1781The C<Event> module has a relatively high setup and callback invocation
1646cost, but overall scores in on the third place. 1782cost, but overall scores in on the third place.
1783
1784C<IO::Async> performs admirably well, about on par with C<Event>, even
1785when using its pure perl backend.
1647 1786
1648C<Glib>'s memory usage is quite a bit higher, but it features a 1787C<Glib>'s memory usage is quite a bit higher, but it features a
1649faster callback invocation and overall ends up in the same class as 1788faster callback invocation and overall ends up in the same class as
1650C<Event>. However, Glib scales extremely badly, doubling the number of 1789C<Event>. However, Glib scales extremely badly, doubling the number of
1651watchers increases the processing time by more than a factor of four, 1790watchers increases the processing time by more than a factor of four,
… …
1729it to another server. This includes deleting the old timeout and creating 1868it to another server. This includes deleting the old timeout and creating
1730a new one that moves the timeout into the future. 1869a new one that moves the timeout into the future.
1731 1870
1732=head3 Results 1871=head3 Results
1733 1872
1734 name sockets create request 1873 name sockets create request
1735 EV 20000 69.01 11.16 1874 EV 20000 69.01 11.16
1736 Perl 20000 73.32 35.87 1875 Perl 20000 73.32 35.87
1876 IOAsync 20000 157.00 98.14 epoll
1877 IOAsync 20000 159.31 616.06 poll
1737 Event 20000 212.62 257.32 1878 Event 20000 212.62 257.32
1738 Glib 20000 651.16 1896.30 1879 Glib 20000 651.16 1896.30
1739 POE 20000 349.67 12317.24 uses POE::Loop::Event 1880 POE 20000 349.67 12317.24 uses POE::Loop::Event
1740 1881
1741=head3 Discussion 1882=head3 Discussion
1742 1883
1743This benchmark I<does> measure scalability and overall performance of the 1884This benchmark I<does> measure scalability and overall performance of the
1744particular event loop. 1885particular event loop.
… …
1746EV is again fastest. Since it is using epoll on my system, the setup time 1887EV is again fastest. Since it is using epoll on my system, the setup time
1747is relatively high, though. 1888is relatively high, though.
1748 1889
1749Perl surprisingly comes second. It is much faster than the C-based event 1890Perl surprisingly comes second. It is much faster than the C-based event
1750loops Event and Glib. 1891loops Event and Glib.
1892
1893IO::Async performs very well when using its epoll backend, and still quite
1894good compared to Glib when using its pure perl backend.
1751 1895
1752Event suffers from high setup time as well (look at its code and you will 1896Event suffers from high setup time as well (look at its code and you will
1753understand why). Callback invocation also has a high overhead compared to 1897understand why). Callback invocation also has a high overhead compared to
1754the C<< $_->() for .. >>-style loop that the Perl event loop uses. Event 1898the C<< $_->() for .. >>-style loop that the Perl event loop uses. Event
1755uses select or poll in basically all documented configurations. 1899uses select or poll in basically all documented configurations.
… …
1818=item * C-based event loops perform very well with small number of 1962=item * C-based event loops perform very well with small number of
1819watchers, as the management overhead dominates. 1963watchers, as the management overhead dominates.
1820 1964
1821=back 1965=back
1822 1966
1967=head2 THE IO::Lambda BENCHMARK
1968
1969Recently I was told about the benchmark in the IO::Lambda manpage, which
1970could be misinterpreted to make AnyEvent look bad. In fact, the benchmark
1971simply compares IO::Lambda with POE, and IO::Lambda looks better (which
1972shouldn't come as a surprise to anybody). As such, the benchmark is
1973fine, and mostly shows that the AnyEvent backend from IO::Lambda isn't
1974very optimal. But how would AnyEvent compare when used without the extra
1975baggage? To explore this, I wrote the equivalent benchmark for AnyEvent.
1976
1977The benchmark itself creates an echo-server, and then, for 500 times,
1978connects to the echo server, sends a line, waits for the reply, and then
1979creates the next connection. This is a rather bad benchmark, as it doesn't
1980test the efficiency of the framework or much non-blocking I/O, but it is a
1981benchmark nevertheless.
1982
1983 name runtime
1984 Lambda/select 0.330 sec
1985 + optimized 0.122 sec
1986 Lambda/AnyEvent 0.327 sec
1987 + optimized 0.138 sec
1988 Raw sockets/select 0.077 sec
1989 POE/select, components 0.662 sec
1990 POE/select, raw sockets 0.226 sec
1991 POE/select, optimized 0.404 sec
1992
1993 AnyEvent/select/nb 0.085 sec
1994 AnyEvent/EV/nb 0.068 sec
1995 +state machine 0.134 sec
1996
1997The benchmark is also a bit unfair (my fault): the IO::Lambda/POE
1998benchmarks actually make blocking connects and use 100% blocking I/O,
1999defeating the purpose of an event-based solution. All of the newly
2000written AnyEvent benchmarks use 100% non-blocking connects (using
2001AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
2002resolver), so AnyEvent is at a disadvantage here, as non-blocking connects
2003generally require a lot more bookkeeping and event handling than blocking
2004connects (which involve a single syscall only).
2005
2006The last AnyEvent benchmark additionally uses L<AnyEvent::Handle>, which
2007offers similar expressive power as POE and IO::Lambda, using conventional
2008Perl syntax. This means that both the echo server and the client are 100%
2009non-blocking, further placing it at a disadvantage.
2010
2011As you can see, the AnyEvent + EV combination even beats the
2012hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
2013backend easily beats IO::Lambda and POE.
2014
2015And even the 100% non-blocking version written using the high-level (and
2016slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda by a
2017large margin, even though it does all of DNS, tcp-connect and socket I/O
2018in a non-blocking way.
2019
2020The two AnyEvent benchmarks programs can be found as F<eg/ae0.pl> and
2021F<eg/ae2.pl> in the AnyEvent distribution, the remaining benchmarks are
2022part of the IO::lambda distribution and were used without any changes.
2023
1823 2024
1824=head1 SIGNALS 2025=head1 SIGNALS
1825 2026
1826AnyEvent currently installs handlers for these signals: 2027AnyEvent currently installs handlers for these signals:
1827 2028
… …
1830=item SIGCHLD 2031=item SIGCHLD
1831 2032
1832A handler for C<SIGCHLD> is installed by AnyEvent's child watcher 2033A handler for C<SIGCHLD> is installed by AnyEvent's child watcher
1833emulation for event loops that do not support them natively. Also, some 2034emulation for event loops that do not support them natively. Also, some
1834event loops install a similar handler. 2035event loops install a similar handler.
2036
2037If, when AnyEvent is loaded, SIGCHLD is set to IGNORE, then AnyEvent will
2038reset it to default, to avoid losing child exit statuses.
1835 2039
1836=item SIGPIPE 2040=item SIGPIPE
1837 2041
1838A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef> 2042A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef>
1839when AnyEvent gets loaded. 2043when AnyEvent gets loaded.
… …
1851 2055
1852=back 2056=back
1853 2057
1854=cut 2058=cut
1855 2059
2060undef $SIG{CHLD}
2061 if $SIG{CHLD} eq 'IGNORE';
2062
1856$SIG{PIPE} = sub { } 2063$SIG{PIPE} = sub { }
1857 unless defined $SIG{PIPE}; 2064 unless defined $SIG{PIPE};
1858
1859 2065
1860=head1 FORK 2066=head1 FORK
1861 2067
1862Most event libraries are not fork-safe. The ones who are usually are 2068Most event libraries are not fork-safe. The ones who are usually are
1863because they rely on inefficient but fork-safe C<select> or C<poll> 2069because they rely on inefficient but fork-safe C<select> or C<poll>
… …
1884 use AnyEvent; 2090 use AnyEvent;
1885 2091
1886Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 2092Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1887be used to probe what backend is used and gain other information (which is 2093be used to probe what backend is used and gain other information (which is
1888probably even less useful to an attacker than PERL_ANYEVENT_MODEL), and 2094probably even less useful to an attacker than PERL_ANYEVENT_MODEL), and
1889$ENV{PERL_ANYEGENT_STRICT}. 2095$ENV{PERL_ANYEVENT_STRICT}.
2096
2097Note that AnyEvent will remove I<all> environment variables starting with
2098C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is
2099enabled.
1890 2100
1891 2101
1892=head1 BUGS 2102=head1 BUGS
1893 2103
1894Perl 5.8 has numerous memleaks that sometimes hit this module and are hard 2104Perl 5.8 has numerous memleaks that sometimes hit this module and are hard
… …
1906L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2116L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
1907 2117
1908Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2118Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
1909L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2119L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
1910L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2120L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
1911L<AnyEvent::Impl::POE>. 2121L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>.
1912 2122
1913Non-blocking file handles, sockets, TCP clients and 2123Non-blocking file handles, sockets, TCP clients and
1914servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>. 2124servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
1915 2125
1916Asynchronous DNS: L<AnyEvent::DNS>. 2126Asynchronous DNS: L<AnyEvent::DNS>.
1917 2127
1918Coroutine 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>,
1919 2130
1920Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>. 2131Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::XMPP>,
2132L<AnyEvent::HTTP>.
1921 2133
1922 2134
1923=head1 AUTHOR 2135=head1 AUTHOR
1924 2136
1925 Marc Lehmann <schmorp@schmorp.de> 2137 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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