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.239 by root, Thu Jul 16 20:55:38 2009 UTC vs.
Revision 1.261 by root, Tue Jul 28 12:56:17 2009 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - provide framework for multiple event loops 3AnyEvent - the DBI of event loop programming
4 4
5EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported 5EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt
6event loops. 6and POE are various supported event loops/environments.
7 7
8=head1 SYNOPSIS 8=head1 SYNOPSIS
9 9
10 use AnyEvent; 10 use AnyEvent;
11 11
… …
40=head1 INTRODUCTION/TUTORIAL 40=head1 INTRODUCTION/TUTORIAL
41 41
42This manpage is mainly a reference manual. If you are interested 42This manpage is mainly a reference manual. If you are interested
43in a tutorial or some gentle introduction, have a look at the 43in a tutorial or some gentle introduction, have a look at the
44L<AnyEvent::Intro> manpage. 44L<AnyEvent::Intro> manpage.
45
46=head1 SUPPORT
47
48There is a mailinglist for discussing all things AnyEvent, and an IRC
49channel, too.
50
51See the AnyEvent project page at the B<Schmorpforge Ta-Sa Software
52Repository>, at L<http://anyevent.schmorp.de>, for more info.
45 53
46=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT) 54=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
47 55
48Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 56Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
49nowadays. So what is different about AnyEvent? 57nowadays. So what is different about AnyEvent?
… …
361invocation, and callback invocation will be synchronous. Synchronous means 369invocation, and callback invocation will be synchronous. Synchronous means
362that it might take a while until the signal gets handled by the process, 370that it might take a while until the signal gets handled by the process,
363but it is guaranteed not to interrupt any other callbacks. 371but it is guaranteed not to interrupt any other callbacks.
364 372
365The main advantage of using these watchers is that you can share a signal 373The main advantage of using these watchers is that you can share a signal
366between multiple watchers. 374between multiple watchers, and AnyEvent will ensure that signals will not
375interrupt your program at bad times.
367 376
368This watcher might use C<%SIG>, so programs overwriting those signals 377This watcher might use C<%SIG> (depending on the event loop used),
369directly will likely not work correctly. 378so programs overwriting those signals directly will likely not work
379correctly.
370 380
371Example: exit on SIGINT 381Example: exit on SIGINT
372 382
373 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 383 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
374 384
385=head3 Signal Races, Delays and Workarounds
386
387Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
388callbacks to signals in a generic way, which is a pity, as you cannot do
389race-free signal handling in perl. AnyEvent will try to do it's best, but
390in some cases, signals will be delayed. The maximum time a signal might
391be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10
392seconds). This variable can be changed only before the first signal
393watcher is created, and should be left alone otherwise. Higher values
394will cause fewer spurious wake-ups, which is better for power and CPU
395saving. All these problems can be avoided by installing the optional
396L<Async::Interrupt> module. This will not work with inherently broken
397event loops such as L<Event> or L<Event::Lib> (and not with L<POE>
398currently, as POE does it's own workaround with one-second latency). With
399those, you just have to suffer the delays.
400
375=head2 CHILD PROCESS WATCHERS 401=head2 CHILD PROCESS WATCHERS
376 402
377You can also watch on a child process exit and catch its exit status. 403You can also watch on a child process exit and catch its exit status.
378 404
379The child process is specified by the C<pid> argument (if set to C<0>, it 405The child process is specified by the C<pid> argument (one some backends,
380watches for any child process exit). The watcher will triggered only when 406using C<0> watches for any child process exit, on others this will
381the child process has finished and an exit status is available, not on 407croak). The watcher will be triggered only when the child process has
382any trace events (stopped/continued). 408finished and an exit status is available, not on any trace events
409(stopped/continued).
383 410
384The callback will be called with the pid and exit status (as returned by 411The callback will be called with the pid and exit status (as returned by
385waitpid), so unlike other watcher types, you I<can> rely on child watcher 412waitpid), so unlike other watcher types, you I<can> rely on child watcher
386callback arguments. 413callback arguments.
387 414
… …
403 430
404This means you cannot create a child watcher as the very first 431This means you cannot create a child watcher as the very first
405thing in an AnyEvent program, you I<have> to create at least one 432thing in an AnyEvent program, you I<have> to create at least one
406watcher before you C<fork> the child (alternatively, you can call 433watcher before you C<fork> the child (alternatively, you can call
407C<AnyEvent::detect>). 434C<AnyEvent::detect>).
435
436As most event loops do not support waiting for child events, they will be
437emulated by AnyEvent in most cases, in which the latency and race problems
438mentioned in the description of signal watchers apply.
408 439
409Example: fork a process and wait for it 440Example: fork a process and wait for it
410 441
411 my $done = AnyEvent->condvar; 442 my $done = AnyEvent->condvar;
412 443
… …
487Condition variables are similar to callbacks, except that you can 518Condition variables are similar to callbacks, except that you can
488optionally wait for them. They can also be called merge points - points 519optionally wait for them. They can also be called merge points - points
489in time where multiple outstanding events have been processed. And yet 520in time where multiple outstanding events have been processed. And yet
490another way to call them is transactions - each condition variable can be 521another way to call them is transactions - each condition variable can be
491used to represent a transaction, which finishes at some point and delivers 522used to represent a transaction, which finishes at some point and delivers
492a result. 523a result. And yet some people know them as "futures" - a promise to
524compute/deliver something that you can wait for.
493 525
494Condition variables are very useful to signal that something has finished, 526Condition variables are very useful to signal that something has finished,
495for example, if you write a module that does asynchronous http requests, 527for example, if you write a module that does asynchronous http requests,
496then a condition variable would be the ideal candidate to signal the 528then a condition variable would be the ideal candidate to signal the
497availability of results. The user can either act when the callback is 529availability of results. The user can either act when the callback is
… …
765 797
766 AnyEvent::Impl::Glib based on Glib, slow but very stable. 798 AnyEvent::Impl::Glib based on Glib, slow but very stable.
767 AnyEvent::Impl::Tk based on Tk, very broken. 799 AnyEvent::Impl::Tk based on Tk, very broken.
768 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 800 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
769 AnyEvent::Impl::POE based on POE, very slow, some limitations. 801 AnyEvent::Impl::POE based on POE, very slow, some limitations.
802 AnyEvent::Impl::Irssi used when running within irssi.
770 803
771=item Backends with special needs. 804=item Backends with special needs.
772 805
773Qt requires the Qt::Application to be instantiated first, but will 806Qt requires the Qt::Application to be instantiated first, but will
774otherwise be picked up automatically. As long as the main program 807otherwise be picked up automatically. As long as the main program
… …
848event module detection too early, for example, L<AnyEvent::AIO> creates 881event module detection too early, for example, L<AnyEvent::AIO> creates
849and installs the global L<IO::AIO> watcher in a C<post_detect> block to 882and installs the global L<IO::AIO> watcher in a C<post_detect> block to
850avoid autodetecting the event module at load time. 883avoid autodetecting the event module at load time.
851 884
852If called in scalar or list context, then it creates and returns an object 885If called in scalar or list context, then it creates and returns an object
853that automatically removes the callback again when it is destroyed. See 886that automatically removes the callback again when it is destroyed (or
887C<undef> when the hook was immediately executed). See L<AnyEvent::AIO> for
854L<Coro::BDB> for a case where this is useful. 888a case where this is useful.
889
890Example: Create a watcher for the IO::AIO module and store it in
891C<$WATCHER>. Only do so after the event loop is initialised, though.
892
893 our WATCHER;
894
895 my $guard = AnyEvent::post_detect {
896 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
897 };
898
899 # the ||= is important in case post_detect immediately runs the block,
900 # as to not clobber the newly-created watcher. assigning both watcher and
901 # post_detect guard to the same variable has the advantage of users being
902 # able to just C<undef $WATCHER> if the watcher causes them grief.
903
904 $WATCHER ||= $guard;
855 905
856=item @AnyEvent::post_detect 906=item @AnyEvent::post_detect
857 907
858If there are any code references in this array (you can C<push> to it 908If there are any code references in this array (you can C<push> to it
859before or after loading AnyEvent), then they will called directly after 909before or after loading AnyEvent), then they will called directly after
… …
1024 1074
1025=cut 1075=cut
1026 1076
1027package AnyEvent; 1077package AnyEvent;
1028 1078
1079# basically a tuned-down version of common::sense
1080sub common_sense {
1029no warnings; 1081 # no warnings
1082 ${^WARNING_BITS} ^= ${^WARNING_BITS};
1030use strict qw(vars subs); 1083 # use strict vars subs
1084 $^H |= 0x00000600;
1085}
1086
1087BEGIN { AnyEvent::common_sense }
1031 1088
1032use Carp (); 1089use Carp ();
1033 1090
1034our $VERSION = 4.82; 1091our $VERSION = 4.881;
1035our $MODEL; 1092our $MODEL;
1036 1093
1037our $AUTOLOAD; 1094our $AUTOLOAD;
1038our @ISA; 1095our @ISA;
1039 1096
1040our @REGISTRY; 1097our @REGISTRY;
1041 1098
1042our $WIN32; 1099our $WIN32;
1100
1101our $VERBOSE;
1043 1102
1044BEGIN { 1103BEGIN {
1045 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }"; 1104 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }";
1046 eval "sub TAINT(){ " . (${^TAINT}*1) . " }"; 1105 eval "sub TAINT(){ " . (${^TAINT}*1) . " }";
1047 1106
1048 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1107 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1049 if ${^TAINT}; 1108 if ${^TAINT};
1050}
1051 1109
1052our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1110 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
1111
1112}
1113
1114our $MAX_SIGNAL_LATENCY = 10;
1053 1115
1054our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1116our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1055 1117
1056{ 1118{
1057 my $idx; 1119 my $idx;
… …
1059 for reverse split /\s*,\s*/, 1121 for reverse split /\s*,\s*/,
1060 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1122 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1061} 1123}
1062 1124
1063my @models = ( 1125my @models = (
1064 [EV:: => AnyEvent::Impl::EV::], 1126 [EV:: => AnyEvent::Impl::EV:: , 1],
1065 [Event:: => AnyEvent::Impl::Event::], 1127 [Event:: => AnyEvent::Impl::Event::, 1],
1066 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::], 1128 [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1],
1067 # everything below here will not be autoprobed 1129 # everything below here will not (normally) be autoprobed
1068 # as the pureperl backend should work everywhere 1130 # as the pureperl backend should work everywhere
1069 # and is usually faster 1131 # and is usually faster
1070 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers 1132 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers
1071 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1133 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1134 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1072 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1135 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1073 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1136 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1074 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1137 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1075 [Wx:: => AnyEvent::Impl::POE::], 1138 [Wx:: => AnyEvent::Impl::POE::],
1076 [Prima:: => AnyEvent::Impl::POE::], 1139 [Prima:: => AnyEvent::Impl::POE::],
1077 # IO::Async is just too broken - we would need workarounds for its 1140 # IO::Async is just too broken - we would need workarounds for its
1078 # byzantine signal and broken child handling, among others. 1141 # byzantine signal and broken child handling, among others.
1079 # IO::Async is rather hard to detect, as it doesn't have any 1142 # IO::Async is rather hard to detect, as it doesn't have any
1080 # obvious default class. 1143 # obvious default class.
1081# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program 1144# [0, IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1082# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program 1145# [0, IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
1083# [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program 1146# [0, IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program
1084); 1147);
1085 1148
1086our %method = map +($_ => 1), 1149our %method = map +($_ => 1),
1087 qw(io timer time now now_update signal child idle condvar one_event DESTROY); 1150 qw(io timer time now now_update signal child idle condvar one_event DESTROY);
1088 1151
… …
1092 my ($cb) = @_; 1155 my ($cb) = @_;
1093 1156
1094 if ($MODEL) { 1157 if ($MODEL) {
1095 $cb->(); 1158 $cb->();
1096 1159
1097 1 1160 undef
1098 } else { 1161 } else {
1099 push @post_detect, $cb; 1162 push @post_detect, $cb;
1100 1163
1101 defined wantarray 1164 defined wantarray
1102 ? bless \$cb, "AnyEvent::Util::postdetect" 1165 ? bless \$cb, "AnyEvent::Util::postdetect"
… …
1108 @post_detect = grep $_ != ${$_[0]}, @post_detect; 1171 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1109} 1172}
1110 1173
1111sub detect() { 1174sub detect() {
1112 unless ($MODEL) { 1175 unless ($MODEL) {
1113 no strict 'refs';
1114 local $SIG{__DIE__}; 1176 local $SIG{__DIE__};
1115 1177
1116 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 1178 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
1117 my $model = "AnyEvent::Impl::$1"; 1179 my $model = "AnyEvent::Impl::$1";
1118 if (eval "require $model") { 1180 if (eval "require $model") {
1119 $MODEL = $model; 1181 $MODEL = $model;
1120 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $verbose > 1; 1182 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
1121 } else { 1183 } else {
1122 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $verbose; 1184 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE;
1123 } 1185 }
1124 } 1186 }
1125 1187
1126 # check for already loaded models 1188 # check for already loaded models
1127 unless ($MODEL) { 1189 unless ($MODEL) {
1128 for (@REGISTRY, @models) { 1190 for (@REGISTRY, @models) {
1129 my ($package, $model) = @$_; 1191 my ($package, $model) = @$_;
1130 if (${"$package\::VERSION"} > 0) { 1192 if (${"$package\::VERSION"} > 0) {
1131 if (eval "require $model") { 1193 if (eval "require $model") {
1132 $MODEL = $model; 1194 $MODEL = $model;
1133 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1; 1195 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1134 last; 1196 last;
1135 } 1197 }
1136 } 1198 }
1137 } 1199 }
1138 1200
1139 unless ($MODEL) { 1201 unless ($MODEL) {
1140 # try to load a model 1202 # try to autoload a model
1141
1142 for (@REGISTRY, @models) { 1203 for (@REGISTRY, @models) {
1143 my ($package, $model) = @$_; 1204 my ($package, $model, $autoload) = @$_;
1205 if (
1206 $autoload
1144 if (eval "require $package" 1207 and eval "require $package"
1145 and ${"$package\::VERSION"} > 0 1208 and ${"$package\::VERSION"} > 0
1146 and eval "require $model") { 1209 and eval "require $model"
1210 ) {
1147 $MODEL = $model; 1211 $MODEL = $model;
1148 warn "AnyEvent: autoprobed model '$model', using it.\n" if $verbose > 1; 1212 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1149 last; 1213 last;
1150 } 1214 }
1151 } 1215 }
1152 1216
1153 $MODEL 1217 $MODEL
… …
1184# allow only one watcher per fd, so we dup it to get a different one). 1248# allow only one watcher per fd, so we dup it to get a different one).
1185sub _dupfh($$;$$) { 1249sub _dupfh($$;$$) {
1186 my ($poll, $fh, $r, $w) = @_; 1250 my ($poll, $fh, $r, $w) = @_;
1187 1251
1188 # cygwin requires the fh mode to be matching, unix doesn't 1252 # cygwin requires the fh mode to be matching, unix doesn't
1189 my ($rw, $mode) = $poll eq "r" ? ($r, "<") : ($w, ">"); 1253 my ($rw, $mode) = $poll eq "r" ? ($r, "<&") : ($w, ">&");
1190 1254
1191 open my $fh2, "$mode&", $fh 1255 open my $fh2, $mode, $fh
1192 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,"; 1256 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,";
1193 1257
1194 # we assume CLOEXEC is already set by perl in all important cases 1258 # we assume CLOEXEC is already set by perl in all important cases
1195 1259
1196 ($fh2, $rw) 1260 ($fh2, $rw)
… …
1198 1262
1199package AnyEvent::Base; 1263package AnyEvent::Base;
1200 1264
1201# default implementations for many methods 1265# default implementations for many methods
1202 1266
1203BEGIN { 1267sub _time {
1268 # probe for availability of Time::HiRes
1204 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1269 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1270 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8;
1205 *_time = \&Time::HiRes::time; 1271 *_time = \&Time::HiRes::time;
1206 # if (eval "use POSIX (); (POSIX::times())... 1272 # if (eval "use POSIX (); (POSIX::times())...
1207 } else { 1273 } else {
1274 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE;
1208 *_time = sub { time }; # epic fail 1275 *_time = sub { time }; # epic fail
1209 } 1276 }
1277
1278 &_time
1210} 1279}
1211 1280
1212sub time { _time } 1281sub time { _time }
1213sub now { _time } 1282sub now { _time }
1214sub now_update { } 1283sub now_update { }
… …
1219 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar" 1288 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar"
1220} 1289}
1221 1290
1222# default implementation for ->signal 1291# default implementation for ->signal
1223 1292
1293our $HAVE_ASYNC_INTERRUPT;
1224our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO); 1294our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1295our (%SIG_ASY, %SIG_ASY_W);
1296our ($SIG_COUNT, $SIG_TW);
1225 1297
1226sub _signal_exec { 1298sub _signal_exec {
1299 $HAVE_ASYNC_INTERRUPT
1300 ? $SIGPIPE_R->drain
1227 sysread $SIGPIPE_R, my $dummy, 4; 1301 : sysread $SIGPIPE_R, my $dummy, 9;
1228 1302
1229 while (%SIG_EV) { 1303 while (%SIG_EV) {
1230 for (keys %SIG_EV) { 1304 for (keys %SIG_EV) {
1231 delete $SIG_EV{$_}; 1305 delete $SIG_EV{$_};
1232 $_->() for values %{ $SIG_CB{$_} || {} }; 1306 $_->() for values %{ $SIG_CB{$_} || {} };
1233 } 1307 }
1234 } 1308 }
1235} 1309}
1236 1310
1311# install a dummy wakeup watcher to reduce signal catching latency
1312sub _sig_add() {
1313 unless ($SIG_COUNT++) {
1314 # try to align timer on a full-second boundary, if possible
1315 my $NOW = AnyEvent->now;
1316
1317 $SIG_TW = AnyEvent->timer (
1318 after => $MAX_SIGNAL_LATENCY - ($NOW - int $NOW),
1319 interval => $MAX_SIGNAL_LATENCY,
1320 cb => sub { }, # just for the PERL_ASYNC_CHECK
1321 );
1322 }
1323}
1324
1325sub _sig_del {
1326 undef $SIG_TW
1327 unless --$SIG_COUNT;
1328}
1329
1330sub _signal {
1331 my (undef, %arg) = @_;
1332
1333 my $signal = uc $arg{signal}
1334 or Carp::croak "required option 'signal' is missing";
1335
1336 if ($HAVE_ASYNC_INTERRUPT) {
1337 # async::interrupt
1338
1339 $signal = Async::Interrupt::sig2num ($signal);
1340 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1341
1342 $SIG_ASY{$signal} ||= do {
1343 my $asy = new Async::Interrupt
1344 cb => sub { undef $SIG_EV{$signal} },
1345 signal => $signal,
1346 pipe => [$SIGPIPE_R->filenos],
1347 ;
1348 $asy->pipe_autodrain (0);
1349
1350 $asy
1351 };
1352
1353 } else {
1354 # pure perl
1355
1356 # AE::Util has been loaded in signal
1357 $signal = AnyEvent::Util::sig2name ($signal);
1358 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1359
1360 $SIG{$signal} ||= sub {
1361 local $!;
1362 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1363 undef $SIG_EV{$signal};
1364 };
1365
1366 # can't do signal processing without introducing races in pure perl,
1367 # so limit the signal latency.
1368 _sig_add;
1369 }
1370
1371 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1372}
1373
1237sub signal { 1374sub signal {
1238 my (undef, %arg) = @_; 1375 # probe for availability of Async::Interrupt
1376 if (!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT} && eval "use Async::Interrupt 1.0 (); 1") {
1377 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
1239 1378
1240 unless ($SIGPIPE_R) { 1379 $HAVE_ASYNC_INTERRUPT = 1;
1380 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1381 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec);
1382
1383 } else {
1384 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
1385
1241 require Fcntl; 1386 require Fcntl;
1242 1387
1243 if (AnyEvent::WIN32) { 1388 if (AnyEvent::WIN32) {
1244 require AnyEvent::Util; 1389 require AnyEvent::Util;
1245 1390
… …
1260 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n"; 1405 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1261 1406
1262 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec); 1407 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec);
1263 } 1408 }
1264 1409
1265 my $signal = uc $arg{signal} 1410 *signal = \&_signal;
1266 or Carp::croak "required option 'signal' is missing"; 1411 &signal
1267
1268 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1269 $SIG{$signal} ||= sub {
1270 local $!;
1271 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1272 undef $SIG_EV{$signal};
1273 };
1274
1275 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1276} 1412}
1277 1413
1278sub AnyEvent::Base::signal::DESTROY { 1414sub AnyEvent::Base::signal::DESTROY {
1279 my ($signal, $cb) = @{$_[0]}; 1415 my ($signal, $cb) = @{$_[0]};
1280 1416
1417 _sig_del;
1418
1281 delete $SIG_CB{$signal}{$cb}; 1419 delete $SIG_CB{$signal}{$cb};
1282 1420
1421 $HAVE_ASYNC_INTERRUPT
1422 ? delete $SIG_ASY{$signal}
1283 # delete doesn't work with older perls - they then 1423 : # delete doesn't work with older perls - they then
1284 # print weird messages, or just unconditionally exit 1424 # print weird messages, or just unconditionally exit
1285 # instead of getting the default action. 1425 # instead of getting the default action.
1426 undef $SIG{$signal}
1286 undef $SIG{$signal} unless keys %{ $SIG_CB{$signal} }; 1427 unless keys %{ $SIG_CB{$signal} };
1287} 1428}
1288 1429
1289# default implementation for ->child 1430# default implementation for ->child
1290 1431
1291our %PID_CB; 1432our %PID_CB;
1292our $CHLD_W; 1433our $CHLD_W;
1293our $CHLD_DELAY_W; 1434our $CHLD_DELAY_W;
1294our $WNOHANG; 1435our $WNOHANG;
1295 1436
1437sub _emit_childstatus($$) {
1438 my (undef, $rpid, $rstatus) = @_;
1439
1440 $_->($rpid, $rstatus)
1441 for values %{ $PID_CB{$rpid} || {} },
1442 values %{ $PID_CB{0} || {} };
1443}
1444
1296sub _sigchld { 1445sub _sigchld {
1446 my $pid;
1447
1448 AnyEvent->_emit_childstatus ($pid, $?)
1297 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 1449 while ($pid = waitpid -1, $WNOHANG) > 0;
1298 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }),
1299 (values %{ $PID_CB{0} || {} });
1300 }
1301} 1450}
1302 1451
1303sub child { 1452sub child {
1304 my (undef, %arg) = @_; 1453 my (undef, %arg) = @_;
1305 1454
1306 defined (my $pid = $arg{pid} + 0) 1455 defined (my $pid = $arg{pid} + 0)
1307 or Carp::croak "required option 'pid' is missing"; 1456 or Carp::croak "required option 'pid' is missing";
1308 1457
1309 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1458 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
1310 1459
1460 # WNOHANG is almost cetrainly 1 everywhere
1461 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/
1462 ? 1
1311 $WNOHANG ||= eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1; 1463 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
1312 1464
1313 unless ($CHLD_W) { 1465 unless ($CHLD_W) {
1314 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1466 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
1315 # child could be a zombie already, so make at least one round 1467 # child could be a zombie already, so make at least one round
1316 &_sigchld; 1468 &_sigchld;
… …
1368 1520
1369our @ISA = AnyEvent::CondVar::Base::; 1521our @ISA = AnyEvent::CondVar::Base::;
1370 1522
1371package AnyEvent::CondVar::Base; 1523package AnyEvent::CondVar::Base;
1372 1524
1373use overload 1525#use overload
1374 '&{}' => sub { my $self = shift; sub { $self->send (@_) } }, 1526# '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
1375 fallback => 1; 1527# fallback => 1;
1528
1529# save 300+ kilobytes by dirtily hardcoding overloading
1530${"AnyEvent::CondVar::Base::OVERLOAD"}{dummy}++; # Register with magic by touching.
1531*{'AnyEvent::CondVar::Base::()'} = sub { }; # "Make it findable via fetchmethod."
1532*{'AnyEvent::CondVar::Base::(&{}'} = sub { my $self = shift; sub { $self->send (@_) } }; # &{}
1533${'AnyEvent::CondVar::Base::()'} = 1; # fallback
1376 1534
1377our $WAITING; 1535our $WAITING;
1378 1536
1379sub _send { 1537sub _send {
1380 # nop 1538 # nop
… …
1471C<PERL_ANYEVENT_MODEL>. 1629C<PERL_ANYEVENT_MODEL>.
1472 1630
1473When set to C<2> or higher, cause AnyEvent to report to STDERR which event 1631When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1474model it chooses. 1632model it chooses.
1475 1633
1634When set to C<8> or higher, then AnyEvent will report extra information on
1635which optional modules it loads and how it implements certain features.
1636
1476=item C<PERL_ANYEVENT_STRICT> 1637=item C<PERL_ANYEVENT_STRICT>
1477 1638
1478AnyEvent does not do much argument checking by default, as thorough 1639AnyEvent does not do much argument checking by default, as thorough
1479argument checking is very costly. Setting this variable to a true value 1640argument checking is very costly. Setting this variable to a true value
1480will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly 1641will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1481check the arguments passed to most method calls. If it finds any problems, 1642check the arguments passed to most method calls. If it finds any problems,
1482it will croak. 1643it will croak.
1483 1644
1484In other words, enables "strict" mode. 1645In other words, enables "strict" mode.
1485 1646
1486Unlike C<use strict>, it is definitely recommended to keep it off in 1647Unlike C<use strict> (or it's modern cousin, C<< use L<common::sense>
1487production. Keeping C<PERL_ANYEVENT_STRICT=1> in your environment while 1648>>, it is definitely recommended to keep it off in production. Keeping
1488developing programs can be very useful, however. 1649C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
1650can be very useful, however.
1489 1651
1490=item C<PERL_ANYEVENT_MODEL> 1652=item C<PERL_ANYEVENT_MODEL>
1491 1653
1492This can be used to specify the event model to be used by AnyEvent, before 1654This can be used to specify the event model to be used by AnyEvent, before
1493auto detection and -probing kicks in. It must be a string consisting 1655auto detection and -probing kicks in. It must be a string consisting
… …
1555 1717
1556When neither C<ca_file> nor C<ca_path> was specified during 1718When neither C<ca_file> nor C<ca_path> was specified during
1557L<AnyEvent::TLS> context creation, and either of these environment 1719L<AnyEvent::TLS> context creation, and either of these environment
1558variables exist, they will be used to specify CA certificate locations 1720variables exist, they will be used to specify CA certificate locations
1559instead of a system-dependent default. 1721instead of a system-dependent default.
1722
1723=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
1724
1725When these are set to C<1>, then the respective modules are not
1726loaded. Mostly good for testing AnyEvent itself.
1560 1727
1561=back 1728=back
1562 1729
1563=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1730=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1564 1731
… …
2132 if $SIG{CHLD} eq 'IGNORE'; 2299 if $SIG{CHLD} eq 'IGNORE';
2133 2300
2134$SIG{PIPE} = sub { } 2301$SIG{PIPE} = sub { }
2135 unless defined $SIG{PIPE}; 2302 unless defined $SIG{PIPE};
2136 2303
2304=head1 RECOMMENDED/OPTIONAL MODULES
2305
2306One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
2307it's built-in modules) are required to use it.
2308
2309That does not mean that AnyEvent won't take advantage of some additional
2310modules if they are installed.
2311
2312This section epxlains which additional modules will be used, and how they
2313affect AnyEvent's operetion.
2314
2315=over 4
2316
2317=item L<Async::Interrupt>
2318
2319This slightly arcane module is used to implement fast signal handling: To
2320my knowledge, there is no way to do completely race-free and quick
2321signal handling in pure perl. To ensure that signals still get
2322delivered, AnyEvent will start an interval timer to wake up perl (and
2323catch the signals) with some delay (default is 10 seconds, look for
2324C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2325
2326If this module is available, then it will be used to implement signal
2327catching, which means that signals will not be delayed, and the event loop
2328will not be interrupted regularly, which is more efficient (And good for
2329battery life on laptops).
2330
2331This affects not just the pure-perl event loop, but also other event loops
2332that have no signal handling on their own (e.g. Glib, Tk, Qt).
2333
2334Some event loops (POE, Event, Event::Lib) offer signal watchers natively,
2335and either employ their own workarounds (POE) or use AnyEvent's workaround
2336(using C<$AnyEvent::MAX_SIGNAL_LATENCY>). Installing L<Async::Interrupt>
2337does nothing for those backends.
2338
2339=item L<EV>
2340
2341This module isn't really "optional", as it is simply one of the backend
2342event loops that AnyEvent can use. However, it is simply the best event
2343loop available in terms of features, speed and stability: It supports
2344the AnyEvent API optimally, implements all the watcher types in XS, does
2345automatic timer adjustments even when no monotonic clock is available,
2346can take avdantage of advanced kernel interfaces such as C<epoll> and
2347C<kqueue>, and is the fastest backend I<by far>. You can even embed
2348L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>).
2349
2350=item L<Guard>
2351
2352The guard module, when used, will be used to implement
2353C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a
2354lot less memory), but otherwise doesn't affect guard operation much. It is
2355purely used for performance.
2356
2357=item L<JSON> and L<JSON::XS>
2358
2359This module is required when you want to read or write JSON data via
2360L<AnyEvent::Handle>. It is also written in pure-perl, but can take
2361advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2362
2363In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2364installed.
2365
2366=item L<Net::SSLeay>
2367
2368Implementing TLS/SSL in Perl is certainly interesting, but not very
2369worthwhile: If this module is installed, then L<AnyEvent::Handle> (with
2370the help of L<AnyEvent::TLS>), gains the ability to do TLS/SSL.
2371
2372=item L<Time::HiRes>
2373
2374This module is part of perl since release 5.008. It will be used when the
2375chosen event library does not come with a timing source on it's own. The
2376pure-perl event loop (L<AnyEvent::Impl::Perl>) will additionally use it to
2377try to use a monotonic clock for timing stability.
2378
2379=back
2380
2381
2137=head1 FORK 2382=head1 FORK
2138 2383
2139Most event libraries are not fork-safe. The ones who are usually are 2384Most event libraries are not fork-safe. The ones who are usually are
2140because they rely on inefficient but fork-safe C<select> or C<poll> 2385because they rely on inefficient but fork-safe C<select> or C<poll>
2141calls. Only L<EV> is fully fork-aware. 2386calls. Only L<EV> is fully fork-aware.
2142 2387
2143If you have to fork, you must either do so I<before> creating your first 2388If you have to fork, you must either do so I<before> creating your first
2144watcher OR you must not use AnyEvent at all in the child. 2389watcher OR you must not use AnyEvent at all in the child OR you must do
2390something completely out of the scope of AnyEvent.
2145 2391
2146 2392
2147=head1 SECURITY CONSIDERATIONS 2393=head1 SECURITY CONSIDERATIONS
2148 2394
2149AnyEvent can be forced to load any event model via 2395AnyEvent can be forced to load any event model via
… …
2187L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2433L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
2188 2434
2189Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2435Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2190L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2436L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2191L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2437L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2192L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>. 2438L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>.
2193 2439
2194Non-blocking file handles, sockets, TCP clients and 2440Non-blocking file handles, sockets, TCP clients and
2195servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2441servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2196 2442
2197Asynchronous DNS: L<AnyEvent::DNS>. 2443Asynchronous DNS: L<AnyEvent::DNS>.

Diff Legend

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