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.201 by root, Wed Apr 1 14:08:27 2009 UTC vs.
Revision 1.221 by root, Fri Jun 26 06:33:17 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:
320In either case, if you care (and in most cases, you don't), then you 328In either case, if you care (and in most cases, you don't), then you
321can get whatever behaviour you want with any event loop, by taking the 329can get whatever behaviour you want with any event loop, by taking the
322difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into 330difference between C<< AnyEvent->time >> and C<< AnyEvent->now >> into
323account. 331account.
324 332
333=item AnyEvent->now_update
334
335Some event loops (such as L<EV> or L<AnyEvent::Impl::Perl>) cache
336the current time for each loop iteration (see the discussion of L<<
337AnyEvent->now >>, above).
338
339When a callback runs for a long time (or when the process sleeps), then
340this "current" time will differ substantially from the real time, which
341might affect timers and time-outs.
342
343When this is the case, you can call this method, which will update the
344event loop's idea of "current time".
345
346Note that updating the time I<might> cause some events to be handled.
347
325=back 348=back
326 349
327=head2 SIGNAL WATCHERS 350=head2 SIGNAL WATCHERS
328 351
329You can watch for signals using a signal watcher, C<signal> is the signal 352You can watch for signals using a signal watcher, C<signal> is the signal
369 392
370There 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
371I<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
372have exited already (and no SIGCHLD will be sent anymore). 395have exited already (and no SIGCHLD will be sent anymore).
373 396
374Not 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
375event 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
376loaded 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.
377 403
378This 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
379AnyEvent 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
380C<fork> the child (alternatively, you can call C<AnyEvent::detect>). 406watcher before you C<fork> the child (alternatively, you can call
407C<AnyEvent::detect>).
381 408
382Example: fork a process and wait for it 409Example: fork a process and wait for it
383 410
384 my $done = AnyEvent->condvar; 411 my $done = AnyEvent->condvar;
385 412
395 ); 422 );
396 423
397 # do something else, then wait for process exit 424 # do something else, then wait for process exit
398 $done->recv; 425 $done->recv;
399 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
400=head2 CONDITION VARIABLES 462=head2 CONDITION VARIABLES
401 463
402If 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
403require you to run some blocking "loop", "run" or similar function that 465require you to run some blocking "loop", "run" or similar function that
404will actively watch for new events and call your callbacks. 466will actively watch for new events and call your callbacks.
672 AnyEvent::Impl::Tk based on Tk, very bad choice. 734 AnyEvent::Impl::Tk based on Tk, very bad choice.
673 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). 735 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
674 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 736 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
675 AnyEvent::Impl::POE based on POE, not generic enough for full support. 737 AnyEvent::Impl::POE based on POE, not generic enough for full support.
676 738
739 # warning, support for IO::Async is only partial, as it is too broken
740 # and limited toe ven support the AnyEvent API. See AnyEvent::Impl::Async.
741 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed (see its docs).
742
677There is no support for WxWidgets, as WxWidgets has no support for 743There is no support for WxWidgets, as WxWidgets has no support for
678watching file handles. However, you can use WxWidgets through the 744watching file handles. However, you can use WxWidgets through the
679POE Adaptor, as POE has a Wx backend that simply polls 20 times per 745POE Adaptor, as POE has a Wx backend that simply polls 20 times per
680second, which was considered to be too horrible to even consider for 746second, which was considered to be too horrible to even consider for
681AnyEvent. Likewise, other POE backends can be used by AnyEvent by using 747AnyEvent. Likewise, other POE backends can be used by AnyEvent by using
873no warnings; 939no warnings;
874use strict qw(vars subs); 940use strict qw(vars subs);
875 941
876use Carp; 942use Carp;
877 943
878our $VERSION = 4.35; 944our $VERSION = 4.42;
879our $MODEL; 945our $MODEL;
880 946
881our $AUTOLOAD; 947our $AUTOLOAD;
882our @ISA; 948our @ISA;
883 949
884our @REGISTRY; 950our @REGISTRY;
885 951
886our $WIN32; 952our $WIN32;
887 953
888BEGIN { 954BEGIN {
889 my $win32 = ! ! ($^O =~ /mswin32/i); 955 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }";
890 eval "sub WIN32(){ $win32 }"; 956 eval "sub TAINT(){ " . (${^TAINT}*1) . " }";
957
958 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
959 if ${^TAINT};
891} 960}
892 961
893our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 962our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
894 963
895our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 964our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
913 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 982 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
914 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 983 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
915 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 984 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
916 [Wx:: => AnyEvent::Impl::POE::], 985 [Wx:: => AnyEvent::Impl::POE::],
917 [Prima:: => AnyEvent::Impl::POE::], 986 [Prima:: => AnyEvent::Impl::POE::],
987 # IO::Async is just too broken - we would need workaorunds for its
988 # byzantine signal and broken child handling, among others.
989 # IO::Async is rather hard to detect, as it doesn't have any
990 # obvious default class.
991# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
992# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
993# [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
918); 994);
919 995
920our %method = map +($_ => 1), qw(io timer time now signal child condvar one_event DESTROY); 996our %method = map +($_ => 1),
997 qw(io timer time now now_update signal child idle condvar one_event DESTROY);
921 998
922our @post_detect; 999our @post_detect;
923 1000
924sub post_detect(&) { 1001sub post_detect(&) {
925 my ($cb) = @_; 1002 my ($cb) = @_;
930 1 1007 1
931 } else { 1008 } else {
932 push @post_detect, $cb; 1009 push @post_detect, $cb;
933 1010
934 defined wantarray 1011 defined wantarray
935 ? bless \$cb, "AnyEvent::Util::PostDetect" 1012 ? bless \$cb, "AnyEvent::Util::postdetect"
936 : () 1013 : ()
937 } 1014 }
938} 1015}
939 1016
940sub AnyEvent::Util::PostDetect::DESTROY { 1017sub AnyEvent::Util::postdetect::DESTROY {
941 @post_detect = grep $_ != ${$_[0]}, @post_detect; 1018 @post_detect = grep $_ != ${$_[0]}, @post_detect;
942} 1019}
943 1020
944sub detect() { 1021sub detect() {
945 unless ($MODEL) { 1022 unless ($MODEL) {
982 last; 1059 last;
983 } 1060 }
984 } 1061 }
985 1062
986 $MODEL 1063 $MODEL
987 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib."; 1064 or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV, Event or Glib.\n";
988 } 1065 }
989 } 1066 }
990 1067
991 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 1068 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
992 1069
1013} 1090}
1014 1091
1015# utility function to dup a filehandle. this is used by many backends 1092# utility function to dup a filehandle. this is used by many backends
1016# to support binding more than one watcher per filehandle (they usually 1093# to support binding more than one watcher per filehandle (they usually
1017# allow only one watcher per fd, so we dup it to get a different one). 1094# allow only one watcher per fd, so we dup it to get a different one).
1018sub _dupfh($$$$) { 1095sub _dupfh($$;$$) {
1019 my ($poll, $fh, $r, $w) = @_; 1096 my ($poll, $fh, $r, $w) = @_;
1020 1097
1021 # cygwin requires the fh mode to be matching, unix doesn't 1098 # cygwin requires the fh mode to be matching, unix doesn't
1022 my ($rw, $mode) = $poll eq "r" ? ($r, "<") 1099 my ($rw, $mode) = $poll eq "r" ? ($r, "<")
1023 : $poll eq "w" ? ($w, ">") 1100 : $poll eq "w" ? ($w, ">")
1024 : Carp::croak "AnyEvent->io requires poll set to either 'r' or 'w'"; 1101 : Carp::croak "AnyEvent->io requires poll set to either 'r' or 'w'";
1025 1102
1026 open my $fh2, "$mode&" . fileno $fh 1103 open my $fh2, "$mode&" . fileno $fh
1027 or die "cannot dup() filehandle: $!"; 1104 or die "cannot dup() filehandle: $!,";
1028 1105
1029 # we assume CLOEXEC is already set by perl in all important cases 1106 # we assume CLOEXEC is already set by perl in all important cases
1030 1107
1031 ($fh2, $rw) 1108 ($fh2, $rw)
1032} 1109}
1033 1110
1034package AnyEvent::Base; 1111package AnyEvent::Base;
1035 1112
1036# default implementation for now and time 1113# default implementations for many methods
1037 1114
1038BEGIN { 1115BEGIN {
1039 if (eval "use Time::HiRes (); time (); 1") { 1116 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1040 *_time = \&Time::HiRes::time; 1117 *_time = \&Time::HiRes::time;
1041 # if (eval "use POSIX (); (POSIX::times())... 1118 # if (eval "use POSIX (); (POSIX::times())...
1042 } else { 1119 } else {
1043 *_time = sub { time }; # epic fail 1120 *_time = sub { time }; # epic fail
1044 } 1121 }
1045} 1122}
1046 1123
1047sub time { _time } 1124sub time { _time }
1048sub now { _time } 1125sub now { _time }
1126sub now_update { }
1049 1127
1050# default implementation for ->condvar 1128# default implementation for ->condvar
1051 1129
1052sub condvar { 1130sub condvar {
1053 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, AnyEvent::CondVar:: 1131 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar"
1054} 1132}
1055 1133
1056# default implementation for ->signal 1134# default implementation for ->signal
1057 1135
1058our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO); 1136our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1082 AnyEvent::Util::fh_nonblocking ($SIGPIPE_W) if $SIGPIPE_W; # just in case 1160 AnyEvent::Util::fh_nonblocking ($SIGPIPE_W) if $SIGPIPE_W; # just in case
1083 } else { 1161 } else {
1084 pipe $SIGPIPE_R, $SIGPIPE_W; 1162 pipe $SIGPIPE_R, $SIGPIPE_W;
1085 fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R; 1163 fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R;
1086 fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case 1164 fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case
1165
1166 # not strictly required, as $^F is normally 2, but let's make sure...
1167 fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1168 fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1087 } 1169 }
1088 1170
1089 $SIGPIPE_R 1171 $SIGPIPE_R
1090 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n"; 1172 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1091 1173
1092 # not strictly required, as $^F is normally 2, but let's make sure...
1093 fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1094 fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC;
1095
1096 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec); 1174 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec);
1097 } 1175 }
1098 1176
1099 my $signal = uc $arg{signal} 1177 my $signal = uc $arg{signal}
1100 or Carp::croak "required option 'signal' is missing"; 1178 or Carp::croak "required option 'signal' is missing";
1101 1179
1102 $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; 1180 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1103 $SIG{$signal} ||= sub { 1181 $SIG{$signal} ||= sub {
1182 local $!;
1104 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV; 1183 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1105 undef $SIG_EV{$signal}; 1184 undef $SIG_EV{$signal};
1106 }; 1185 };
1107 1186
1108 bless [$signal, $arg{cb}], "AnyEvent::Base::Signal" 1187 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1109} 1188}
1110 1189
1111sub AnyEvent::Base::Signal::DESTROY { 1190sub AnyEvent::Base::signal::DESTROY {
1112 my ($signal, $cb) = @{$_[0]}; 1191 my ($signal, $cb) = @{$_[0]};
1113 1192
1114 delete $SIG_CB{$signal}{$cb}; 1193 delete $SIG_CB{$signal}{$cb};
1115 1194
1195 # delete doesn't work with older perls - they then
1196 # print weird messages, or just unconditionally exit
1197 # instead of getting the default action.
1116 delete $SIG{$signal} unless keys %{ $SIG_CB{$signal} }; 1198 undef $SIG{$signal} unless keys %{ $SIG_CB{$signal} };
1117} 1199}
1118 1200
1119# default implementation for ->child 1201# default implementation for ->child
1120 1202
1121our %PID_CB; 1203our %PID_CB;
1122our $CHLD_W; 1204our $CHLD_W;
1123our $CHLD_DELAY_W; 1205our $CHLD_DELAY_W;
1124our $PID_IDLE;
1125our $WNOHANG; 1206our $WNOHANG;
1126 1207
1127sub _child_wait { 1208sub _sigchld {
1128 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 1209 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
1129 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }), 1210 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }),
1130 (values %{ $PID_CB{0} || {} }); 1211 (values %{ $PID_CB{0} || {} });
1131 } 1212 }
1132
1133 undef $PID_IDLE;
1134}
1135
1136sub _sigchld {
1137 # make sure we deliver these changes "synchronous" with the event loop.
1138 $CHLD_DELAY_W ||= AnyEvent->timer (after => 0, cb => sub {
1139 undef $CHLD_DELAY_W;
1140 &_child_wait;
1141 });
1142} 1213}
1143 1214
1144sub child { 1215sub child {
1145 my (undef, %arg) = @_; 1216 my (undef, %arg) = @_;
1146 1217
1147 defined (my $pid = $arg{pid} + 0) 1218 defined (my $pid = $arg{pid} + 0)
1148 or Carp::croak "required option 'pid' is missing"; 1219 or Carp::croak "required option 'pid' is missing";
1149 1220
1150 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1221 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
1151 1222
1152 unless ($WNOHANG) {
1153 $WNOHANG = eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1; 1223 $WNOHANG ||= eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
1154 }
1155 1224
1156 unless ($CHLD_W) { 1225 unless ($CHLD_W) {
1157 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1226 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
1158 # child could be a zombie already, so make at least one round 1227 # child could be a zombie already, so make at least one round
1159 &_sigchld; 1228 &_sigchld;
1160 } 1229 }
1161 1230
1162 bless [$pid, $arg{cb}], "AnyEvent::Base::Child" 1231 bless [$pid, $arg{cb}], "AnyEvent::Base::child"
1163} 1232}
1164 1233
1165sub AnyEvent::Base::Child::DESTROY { 1234sub AnyEvent::Base::child::DESTROY {
1166 my ($pid, $cb) = @{$_[0]}; 1235 my ($pid, $cb) = @{$_[0]};
1167 1236
1168 delete $PID_CB{$pid}{$cb}; 1237 delete $PID_CB{$pid}{$cb};
1169 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} }; 1238 delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
1170 1239
1171 undef $CHLD_W unless keys %PID_CB; 1240 undef $CHLD_W unless keys %PID_CB;
1241}
1242
1243# idle emulation is done by simply using a timer, regardless
1244# of whether the process is idle or not, and not letting
1245# the callback use more than 50% of the time.
1246sub idle {
1247 my (undef, %arg) = @_;
1248
1249 my ($cb, $w, $rcb) = $arg{cb};
1250
1251 $rcb = sub {
1252 if ($cb) {
1253 $w = _time;
1254 &$cb;
1255 $w = _time - $w;
1256
1257 # never use more then 50% of the time for the idle watcher,
1258 # within some limits
1259 $w = 0.0001 if $w < 0.0001;
1260 $w = 5 if $w > 5;
1261
1262 $w = AnyEvent->timer (after => $w, cb => $rcb);
1263 } else {
1264 # clean up...
1265 undef $w;
1266 undef $rcb;
1267 }
1268 };
1269
1270 $w = AnyEvent->timer (after => 0.05, cb => $rcb);
1271
1272 bless \\$cb, "AnyEvent::Base::idle"
1273}
1274
1275sub AnyEvent::Base::idle::DESTROY {
1276 undef $${$_[0]};
1172} 1277}
1173 1278
1174package AnyEvent::CondVar; 1279package AnyEvent::CondVar;
1175 1280
1176our @ISA = AnyEvent::CondVar::Base::; 1281our @ISA = AnyEvent::CondVar::Base::;
1250so on. 1355so on.
1251 1356
1252=head1 ENVIRONMENT VARIABLES 1357=head1 ENVIRONMENT VARIABLES
1253 1358
1254The following environment variables are used by this module or its 1359The following environment variables are used by this module or its
1255submodules: 1360submodules.
1361
1362Note that AnyEvent will remove I<all> environment variables starting with
1363C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is
1364enabled.
1256 1365
1257=over 4 1366=over 4
1258 1367
1259=item C<PERL_ANYEVENT_VERBOSE> 1368=item C<PERL_ANYEVENT_VERBOSE>
1260 1369
1272=item C<PERL_ANYEVENT_STRICT> 1381=item C<PERL_ANYEVENT_STRICT>
1273 1382
1274AnyEvent does not do much argument checking by default, as thorough 1383AnyEvent does not do much argument checking by default, as thorough
1275argument checking is very costly. Setting this variable to a true value 1384argument checking is very costly. Setting this variable to a true value
1276will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly 1385will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1277check the arguments passed to most method calls. If it finds any problems 1386check the arguments passed to most method calls. If it finds any problems,
1278it will croak. 1387it will croak.
1279 1388
1280In other words, enables "strict" mode. 1389In other words, enables "strict" mode.
1281 1390
1282Unlike C<use strict>, it is definitely recommended ot keep it off in 1391Unlike C<use strict>, it is definitely recommended to keep it off in
1283production. Keeping C<PERL_ANYEVENT_STRICT=1> in your environment while 1392production. Keeping C<PERL_ANYEVENT_STRICT=1> in your environment while
1284developing programs can be very useful, however. 1393developing programs can be very useful, however.
1285 1394
1286=item C<PERL_ANYEVENT_MODEL> 1395=item C<PERL_ANYEVENT_MODEL>
1287 1396
1586 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers 1695 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
1587 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal 1696 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
1588 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation 1697 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
1589 Event/Event 16000 517 32.20 31.80 0.81 Event native interface 1698 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
1590 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers 1699 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
1700 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll
1701 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll
1591 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour 1702 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
1592 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers 1703 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
1593 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event 1704 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1594 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select 1705 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1595 1706
1624performance becomes really bad with lots of file descriptors (and few of 1735performance becomes really bad with lots of file descriptors (and few of
1625them active), of course, but this was not subject of this benchmark. 1736them active), of course, but this was not subject of this benchmark.
1626 1737
1627The C<Event> module has a relatively high setup and callback invocation 1738The C<Event> module has a relatively high setup and callback invocation
1628cost, but overall scores in on the third place. 1739cost, but overall scores in on the third place.
1740
1741C<IO::Async> performs admirably well, about on par with C<Event>, even
1742when using its pure perl backend.
1629 1743
1630C<Glib>'s memory usage is quite a bit higher, but it features a 1744C<Glib>'s memory usage is quite a bit higher, but it features a
1631faster callback invocation and overall ends up in the same class as 1745faster callback invocation and overall ends up in the same class as
1632C<Event>. However, Glib scales extremely badly, doubling the number of 1746C<Event>. However, Glib scales extremely badly, doubling the number of
1633watchers increases the processing time by more than a factor of four, 1747watchers increases the processing time by more than a factor of four,
1711it to another server. This includes deleting the old timeout and creating 1825it to another server. This includes deleting the old timeout and creating
1712a new one that moves the timeout into the future. 1826a new one that moves the timeout into the future.
1713 1827
1714=head3 Results 1828=head3 Results
1715 1829
1716 name sockets create request 1830 name sockets create request
1717 EV 20000 69.01 11.16 1831 EV 20000 69.01 11.16
1718 Perl 20000 73.32 35.87 1832 Perl 20000 73.32 35.87
1833 IOAsync 20000 157.00 98.14 epoll
1834 IOAsync 20000 159.31 616.06 poll
1719 Event 20000 212.62 257.32 1835 Event 20000 212.62 257.32
1720 Glib 20000 651.16 1896.30 1836 Glib 20000 651.16 1896.30
1721 POE 20000 349.67 12317.24 uses POE::Loop::Event 1837 POE 20000 349.67 12317.24 uses POE::Loop::Event
1722 1838
1723=head3 Discussion 1839=head3 Discussion
1724 1840
1725This benchmark I<does> measure scalability and overall performance of the 1841This benchmark I<does> measure scalability and overall performance of the
1726particular event loop. 1842particular event loop.
1728EV is again fastest. Since it is using epoll on my system, the setup time 1844EV is again fastest. Since it is using epoll on my system, the setup time
1729is relatively high, though. 1845is relatively high, though.
1730 1846
1731Perl surprisingly comes second. It is much faster than the C-based event 1847Perl surprisingly comes second. It is much faster than the C-based event
1732loops Event and Glib. 1848loops Event and Glib.
1849
1850IO::Async performs very well when using its epoll backend, and still quite
1851good compared to Glib when using its pure perl backend.
1733 1852
1734Event suffers from high setup time as well (look at its code and you will 1853Event suffers from high setup time as well (look at its code and you will
1735understand why). Callback invocation also has a high overhead compared to 1854understand why). Callback invocation also has a high overhead compared to
1736the C<< $_->() for .. >>-style loop that the Perl event loop uses. Event 1855the C<< $_->() for .. >>-style loop that the Perl event loop uses. Event
1737uses select or poll in basically all documented configurations. 1856uses select or poll in basically all documented configurations.
1800=item * C-based event loops perform very well with small number of 1919=item * C-based event loops perform very well with small number of
1801watchers, as the management overhead dominates. 1920watchers, as the management overhead dominates.
1802 1921
1803=back 1922=back
1804 1923
1924=head2 THE IO::Lambda BENCHMARK
1925
1926Recently I was told about the benchmark in the IO::Lambda manpage, which
1927could be misinterpreted to make AnyEvent look bad. In fact, the benchmark
1928simply compares IO::Lambda with POE, and IO::Lambda looks better (which
1929shouldn't come as a surprise to anybody). As such, the benchmark is
1930fine, and mostly shows that the AnyEvent backend from IO::Lambda isn't
1931very optimal. But how would AnyEvent compare when used without the extra
1932baggage? To explore this, I wrote the equivalent benchmark for AnyEvent.
1933
1934The benchmark itself creates an echo-server, and then, for 500 times,
1935connects to the echo server, sends a line, waits for the reply, and then
1936creates the next connection. This is a rather bad benchmark, as it doesn't
1937test the efficiency of the framework or much non-blocking I/O, but it is a
1938benchmark nevertheless.
1939
1940 name runtime
1941 Lambda/select 0.330 sec
1942 + optimized 0.122 sec
1943 Lambda/AnyEvent 0.327 sec
1944 + optimized 0.138 sec
1945 Raw sockets/select 0.077 sec
1946 POE/select, components 0.662 sec
1947 POE/select, raw sockets 0.226 sec
1948 POE/select, optimized 0.404 sec
1949
1950 AnyEvent/select/nb 0.085 sec
1951 AnyEvent/EV/nb 0.068 sec
1952 +state machine 0.134 sec
1953
1954The benchmark is also a bit unfair (my fault): the IO::Lambda/POE
1955benchmarks actually make blocking connects and use 100% blocking I/O,
1956defeating the purpose of an event-based solution. All of the newly
1957written AnyEvent benchmarks use 100% non-blocking connects (using
1958AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
1959resolver), so AnyEvent is at a disadvantage here, as non-blocking connects
1960generally require a lot more bookkeeping and event handling than blocking
1961connects (which involve a single syscall only).
1962
1963The last AnyEvent benchmark additionally uses L<AnyEvent::Handle>, which
1964offers similar expressive power as POE and IO::Lambda, using conventional
1965Perl syntax. This means that both the echo server and the client are 100%
1966non-blocking, further placing it at a disadvantage.
1967
1968As you can see, the AnyEvent + EV combination even beats the
1969hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
1970backend easily beats IO::Lambda and POE.
1971
1972And even the 100% non-blocking version written using the high-level (and
1973slow :) L<AnyEvent::Handle> abstraction beats both POE and IO::Lambda by a
1974large margin, even though it does all of DNS, tcp-connect and socket I/O
1975in a non-blocking way.
1976
1977The two AnyEvent benchmarks programs can be found as F<eg/ae0.pl> and
1978F<eg/ae2.pl> in the AnyEvent distribution, the remaining benchmarks are
1979part of the IO::lambda distribution and were used without any changes.
1980
1805 1981
1806=head1 SIGNALS 1982=head1 SIGNALS
1807 1983
1808AnyEvent currently installs handlers for these signals: 1984AnyEvent currently installs handlers for these signals:
1809 1985
1812=item SIGCHLD 1988=item SIGCHLD
1813 1989
1814A handler for C<SIGCHLD> is installed by AnyEvent's child watcher 1990A handler for C<SIGCHLD> is installed by AnyEvent's child watcher
1815emulation for event loops that do not support them natively. Also, some 1991emulation for event loops that do not support them natively. Also, some
1816event loops install a similar handler. 1992event loops install a similar handler.
1993
1994If, when AnyEvent is loaded, SIGCHLD is set to IGNORE, then AnyEvent will
1995reset it to default, to avoid losing child exit statuses.
1817 1996
1818=item SIGPIPE 1997=item SIGPIPE
1819 1998
1820A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef> 1999A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef>
1821when AnyEvent gets loaded. 2000when AnyEvent gets loaded.
1833 2012
1834=back 2013=back
1835 2014
1836=cut 2015=cut
1837 2016
2017undef $SIG{CHLD}
2018 if $SIG{CHLD} eq 'IGNORE';
2019
1838$SIG{PIPE} = sub { } 2020$SIG{PIPE} = sub { }
1839 unless defined $SIG{PIPE}; 2021 unless defined $SIG{PIPE};
1840
1841 2022
1842=head1 FORK 2023=head1 FORK
1843 2024
1844Most event libraries are not fork-safe. The ones who are usually are 2025Most event libraries are not fork-safe. The ones who are usually are
1845because they rely on inefficient but fork-safe C<select> or C<poll> 2026because they rely on inefficient but fork-safe C<select> or C<poll>
1866 use AnyEvent; 2047 use AnyEvent;
1867 2048
1868Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 2049Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1869be used to probe what backend is used and gain other information (which is 2050be used to probe what backend is used and gain other information (which is
1870probably even less useful to an attacker than PERL_ANYEVENT_MODEL), and 2051probably even less useful to an attacker than PERL_ANYEVENT_MODEL), and
1871$ENV{PERL_ANYEGENT_STRICT}. 2052$ENV{PERL_ANYEVENT_STRICT}.
2053
2054Note that AnyEvent will remove I<all> environment variables starting with
2055C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is
2056enabled.
1872 2057
1873 2058
1874=head1 BUGS 2059=head1 BUGS
1875 2060
1876Perl 5.8 has numerous memleaks that sometimes hit this module and are hard 2061Perl 5.8 has numerous memleaks that sometimes hit this module and are hard

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines