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.238 by root, Thu Jul 16 03:48:33 2009 UTC vs.
Revision 1.247 by root, Sat Jul 18 22:24:17 2009 UTC

… …
361invocation, and callback invocation will be synchronous. Synchronous means 361invocation, and callback invocation will be synchronous. Synchronous means
362that it might take a while until the signal gets handled by the process, 362that it might take a while until the signal gets handled by the process,
363but it is guaranteed not to interrupt any other callbacks. 363but it is guaranteed not to interrupt any other callbacks.
364 364
365The main advantage of using these watchers is that you can share a signal 365The main advantage of using these watchers is that you can share a signal
366between multiple watchers. 366between multiple watchers, and AnyEvent will ensure that signals will not
367interrupt your program at bad times.
367 368
368This watcher might use C<%SIG>, so programs overwriting those signals 369This watcher might use C<%SIG> (depending on the event loop used),
369directly will likely not work correctly. 370so programs overwriting those signals directly will likely not work
371correctly.
370 372
371Example: exit on SIGINT 373Example: exit on SIGINT
372 374
373 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 375 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
376
377=head3 Signal Races, Delays and Workarounds
378
379Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
380callbacks to signals in a generic way, which is a pity, as you cannot do
381race-free signal handling in perl. AnyEvent will try to do it's best, but
382in some cases, signals will be delayed. The maximum time a signal might
383be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10
384seconds). This variable can be changed only before the first signal
385watcher is created, and should be left alone otherwise. Higher values
386will cause fewer spurious wake-ups, which is better for power and CPU
387saving. All these problems can be avoided by installing the optional
388L<Async::Interrupt> module. This will not work with inherently broken
389event loops such as L<Event> or L<Event::Lib> (and not with L<POE>
390currently, as POE does it's own workaround with one-second latency). With
391those, you just have to suffer the delays.
374 392
375=head2 CHILD PROCESS WATCHERS 393=head2 CHILD PROCESS WATCHERS
376 394
377You can also watch on a child process exit and catch its exit status. 395You can also watch on a child process exit and catch its exit status.
378 396
… …
403 421
404This means you cannot create a child watcher as the very first 422This means you cannot create a child watcher as the very first
405thing in an AnyEvent program, you I<have> to create at least one 423thing in an AnyEvent program, you I<have> to create at least one
406watcher before you C<fork> the child (alternatively, you can call 424watcher before you C<fork> the child (alternatively, you can call
407C<AnyEvent::detect>). 425C<AnyEvent::detect>).
426
427As most event loops do not support waiting for child events, they will be
428emulated by AnyEvent in most cases, in which the latency and race problems
429mentioned in the description of signal watchers apply.
408 430
409Example: fork a process and wait for it 431Example: fork a process and wait for it
410 432
411 my $done = AnyEvent->condvar; 433 my $done = AnyEvent->condvar;
412 434
… …
463 485
464If you are familiar with some event loops you will know that all of them 486If you are familiar with some event loops you will know that all of them
465require you to run some blocking "loop", "run" or similar function that 487require you to run some blocking "loop", "run" or similar function that
466will actively watch for new events and call your callbacks. 488will actively watch for new events and call your callbacks.
467 489
468AnyEvent is different, it expects somebody else to run the event loop and 490AnyEvent is slightly different: it expects somebody else to run the event
469will only block when necessary (usually when told by the user). 491loop and will only block when necessary (usually when told by the user).
470 492
471The instrument to do that is called a "condition variable", so called 493The instrument to do that is called a "condition variable", so called
472because they represent a condition that must become true. 494because they represent a condition that must become true.
473 495
496Now is probably a good time to look at the examples further below.
497
474Condition variables can be created by calling the C<< AnyEvent->condvar 498Condition variables can be created by calling the C<< AnyEvent->condvar
475>> method, usually without arguments. The only argument pair allowed is 499>> method, usually without arguments. The only argument pair allowed is
476
477C<cb>, which specifies a callback to be called when the condition variable 500C<cb>, which specifies a callback to be called when the condition variable
478becomes true, with the condition variable as the first argument (but not 501becomes true, with the condition variable as the first argument (but not
479the results). 502the results).
480 503
481After creation, the condition variable is "false" until it becomes "true" 504After creation, the condition variable is "false" until it becomes "true"
… …
530 after => 1, 553 after => 1,
531 cb => sub { $result_ready->send }, 554 cb => sub { $result_ready->send },
532 ); 555 );
533 556
534 # this "blocks" (while handling events) till the callback 557 # this "blocks" (while handling events) till the callback
535 # calls send 558 # calls -<send
536 $result_ready->recv; 559 $result_ready->recv;
537 560
538Example: wait for a timer, but take advantage of the fact that 561Example: wait for a timer, but take advantage of the fact that condition
539condition variables are also code references. 562variables are also callable directly.
540 563
541 my $done = AnyEvent->condvar; 564 my $done = AnyEvent->condvar;
542 my $delay = AnyEvent->timer (after => 5, cb => $done); 565 my $delay = AnyEvent->timer (after => 5, cb => $done);
543 $done->recv; 566 $done->recv;
544 567
… …
550 573
551 ... 574 ...
552 575
553 my @info = $couchdb->info->recv; 576 my @info = $couchdb->info->recv;
554 577
555And this is how you would just ste a callback to be called whenever the 578And this is how you would just set a callback to be called whenever the
556results are available: 579results are available:
557 580
558 $couchdb->info->cb (sub { 581 $couchdb->info->cb (sub {
559 my @info = $_[0]->recv; 582 my @info = $_[0]->recv;
560 }); 583 });
… …
578immediately from within send. 601immediately from within send.
579 602
580Any arguments passed to the C<send> call will be returned by all 603Any arguments passed to the C<send> call will be returned by all
581future C<< ->recv >> calls. 604future C<< ->recv >> calls.
582 605
583Condition variables are overloaded so one can call them directly 606Condition variables are overloaded so one can call them directly (as if
584(as a code reference). Calling them directly is the same as calling 607they were a code reference). Calling them directly is the same as calling
585C<send>. Note, however, that many C-based event loops do not handle 608C<send>.
586overloading, so as tempting as it may be, passing a condition variable
587instead of a callback does not work. Both the pure perl and EV loops
588support overloading, however, as well as all functions that use perl to
589invoke a callback (as in L<AnyEvent::Socket> and L<AnyEvent::DNS> for
590example).
591 609
592=item $cv->croak ($error) 610=item $cv->croak ($error)
593 611
594Similar to send, but causes all call's to C<< ->recv >> to invoke 612Similar to send, but causes all call's to C<< ->recv >> to invoke
595C<Carp::croak> with the given error message/object/scalar. 613C<Carp::croak> with the given error message/object/scalar.
596 614
597This can be used to signal any errors to the condition variable 615This can be used to signal any errors to the condition variable
598user/consumer. 616user/consumer. Doing it this way instead of calling C<croak> directly
617delays the error detetcion, but has the overwhelmign advantage that it
618diagnoses the error at the place where the result is expected, and not
619deep in some event clalback without connection to the actual code causing
620the problem.
599 621
600=item $cv->begin ([group callback]) 622=item $cv->begin ([group callback])
601 623
602=item $cv->end 624=item $cv->end
603 625
… …
699function will call C<croak>. 721function will call C<croak>.
700 722
701In list context, all parameters passed to C<send> will be returned, 723In list context, all parameters passed to C<send> will be returned,
702in scalar context only the first one will be returned. 724in scalar context only the first one will be returned.
703 725
726Note that doing a blocking wait in a callback is not supported by any
727event loop, that is, recursive invocation of a blocking C<< ->recv
728>> is not allowed, and the C<recv> call will C<croak> if such a
729condition is detected. This condition can be slightly loosened by using
730L<Coro::AnyEvent>, which allows you to do a blocking C<< ->recv >> from
731any thread that doesn't run the event loop itself.
732
704Not all event models support a blocking wait - some die in that case 733Not all event models support a blocking wait - some die in that case
705(programs might want to do that to stay interactive), so I<if you are 734(programs might want to do that to stay interactive), so I<if you are
706using this from a module, never require a blocking wait>, but let the 735using this from a module, never require a blocking wait>. Instead, let the
707caller decide whether the call will block or not (for example, by coupling 736caller decide whether the call will block or not (for example, by coupling
708condition variables with some kind of request results and supporting 737condition variables with some kind of request results and supporting
709callbacks so the caller knows that getting the result will not block, 738callbacks so the caller knows that getting the result will not block,
710while still supporting blocking waits if the caller so desires). 739while still supporting blocking waits if the caller so desires).
711
712Another reason I<never> to C<< ->recv >> in a module is that you cannot
713sensibly have two C<< ->recv >>'s in parallel, as that would require
714multiple interpreters or coroutines/threads, none of which C<AnyEvent>
715can supply.
716
717The L<Coro> module, however, I<can> and I<does> supply coroutines and, in
718fact, L<Coro::AnyEvent> replaces AnyEvent's condvars by coroutine-safe
719versions and also integrates coroutines into AnyEvent, making blocking
720C<< ->recv >> calls perfectly safe as long as they are done from another
721coroutine (one that doesn't run the event loop).
722 740
723You can ensure that C<< -recv >> never blocks by setting a callback and 741You can ensure that C<< -recv >> never blocks by setting a callback and
724only calling C<< ->recv >> from within that callback (or at a later 742only calling C<< ->recv >> from within that callback (or at a later
725time). This will work even when the event loop does not support blocking 743time). This will work even when the event loop does not support blocking
726waits otherwise. 744waits otherwise.
… …
1028 1046
1029=cut 1047=cut
1030 1048
1031package AnyEvent; 1049package AnyEvent;
1032 1050
1051# basically a tuned-down version of common::sense
1052sub common_sense {
1033no warnings; 1053 # no warnings
1054 ${^WARNING_BITS} ^= ${^WARNING_BITS};
1034use strict qw(vars subs); 1055 # use strict vars subs
1056 $^H |= 0x00000600;
1057}
1035 1058
1059BEGIN { AnyEvent::common_sense }
1060
1036use Carp; 1061use Carp ();
1037 1062
1038our $VERSION = 4.82; 1063our $VERSION = 4.85;
1039our $MODEL; 1064our $MODEL;
1040 1065
1041our $AUTOLOAD; 1066our $AUTOLOAD;
1042our @ISA; 1067our @ISA;
1043 1068
1044our @REGISTRY; 1069our @REGISTRY;
1045 1070
1046our $WIN32; 1071our $WIN32;
1072
1073our $VERBOSE;
1047 1074
1048BEGIN { 1075BEGIN {
1049 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }"; 1076 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }";
1050 eval "sub TAINT(){ " . (${^TAINT}*1) . " }"; 1077 eval "sub TAINT(){ " . (${^TAINT}*1) . " }";
1051 1078
1052 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1079 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1053 if ${^TAINT}; 1080 if ${^TAINT};
1054}
1055 1081
1056our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1082 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
1083
1084}
1085
1086our $MAX_SIGNAL_LATENCY = 10;
1057 1087
1058our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1088our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1059 1089
1060{ 1090{
1061 my $idx; 1091 my $idx;
… …
1112 @post_detect = grep $_ != ${$_[0]}, @post_detect; 1142 @post_detect = grep $_ != ${$_[0]}, @post_detect;
1113} 1143}
1114 1144
1115sub detect() { 1145sub detect() {
1116 unless ($MODEL) { 1146 unless ($MODEL) {
1117 no strict 'refs';
1118 local $SIG{__DIE__}; 1147 local $SIG{__DIE__};
1119 1148
1120 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 1149 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
1121 my $model = "AnyEvent::Impl::$1"; 1150 my $model = "AnyEvent::Impl::$1";
1122 if (eval "require $model") { 1151 if (eval "require $model") {
1123 $MODEL = $model; 1152 $MODEL = $model;
1124 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $verbose > 1; 1153 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
1125 } else { 1154 } else {
1126 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $verbose; 1155 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE;
1127 } 1156 }
1128 } 1157 }
1129 1158
1130 # check for already loaded models 1159 # check for already loaded models
1131 unless ($MODEL) { 1160 unless ($MODEL) {
1132 for (@REGISTRY, @models) { 1161 for (@REGISTRY, @models) {
1133 my ($package, $model) = @$_; 1162 my ($package, $model) = @$_;
1134 if (${"$package\::VERSION"} > 0) { 1163 if (${"$package\::VERSION"} > 0) {
1135 if (eval "require $model") { 1164 if (eval "require $model") {
1136 $MODEL = $model; 1165 $MODEL = $model;
1137 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1; 1166 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1138 last; 1167 last;
1139 } 1168 }
1140 } 1169 }
1141 } 1170 }
1142 1171
… …
1147 my ($package, $model) = @$_; 1176 my ($package, $model) = @$_;
1148 if (eval "require $package" 1177 if (eval "require $package"
1149 and ${"$package\::VERSION"} > 0 1178 and ${"$package\::VERSION"} > 0
1150 and eval "require $model") { 1179 and eval "require $model") {
1151 $MODEL = $model; 1180 $MODEL = $model;
1152 warn "AnyEvent: autoprobed model '$model', using it.\n" if $verbose > 1; 1181 warn "AnyEvent: autoprobed model '$model', using it.\n" if $VERBOSE >= 2;
1153 last; 1182 last;
1154 } 1183 }
1155 } 1184 }
1156 1185
1157 $MODEL 1186 $MODEL
… …
1173 1202
1174sub AUTOLOAD { 1203sub AUTOLOAD {
1175 (my $func = $AUTOLOAD) =~ s/.*://; 1204 (my $func = $AUTOLOAD) =~ s/.*://;
1176 1205
1177 $method{$func} 1206 $method{$func}
1178 or croak "$func: not a valid method for AnyEvent objects"; 1207 or Carp::croak "$func: not a valid method for AnyEvent objects";
1179 1208
1180 detect unless $MODEL; 1209 detect unless $MODEL;
1181 1210
1182 my $class = shift; 1211 my $class = shift;
1183 $class->$func (@_); 1212 $class->$func (@_);
… …
1188# allow only one watcher per fd, so we dup it to get a different one). 1217# allow only one watcher per fd, so we dup it to get a different one).
1189sub _dupfh($$;$$) { 1218sub _dupfh($$;$$) {
1190 my ($poll, $fh, $r, $w) = @_; 1219 my ($poll, $fh, $r, $w) = @_;
1191 1220
1192 # cygwin requires the fh mode to be matching, unix doesn't 1221 # cygwin requires the fh mode to be matching, unix doesn't
1193 my ($rw, $mode) = $poll eq "r" ? ($r, "<") : ($w, ">"); 1222 my ($rw, $mode) = $poll eq "r" ? ($r, "<&") : ($w, ">&");
1194 1223
1195 open my $fh2, "$mode&", $fh 1224 open my $fh2, $mode, $fh
1196 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,"; 1225 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,";
1197 1226
1198 # we assume CLOEXEC is already set by perl in all important cases 1227 # we assume CLOEXEC is already set by perl in all important cases
1199 1228
1200 ($fh2, $rw) 1229 ($fh2, $rw)
… …
1202 1231
1203package AnyEvent::Base; 1232package AnyEvent::Base;
1204 1233
1205# default implementations for many methods 1234# default implementations for many methods
1206 1235
1207BEGIN { 1236sub _time {
1237 # probe for availability of Time::HiRes
1208 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1238 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1239 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8;
1209 *_time = \&Time::HiRes::time; 1240 *_time = \&Time::HiRes::time;
1210 # if (eval "use POSIX (); (POSIX::times())... 1241 # if (eval "use POSIX (); (POSIX::times())...
1211 } else { 1242 } else {
1243 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE;
1212 *_time = sub { time }; # epic fail 1244 *_time = sub { time }; # epic fail
1213 } 1245 }
1246
1247 &_time
1214} 1248}
1215 1249
1216sub time { _time } 1250sub time { _time }
1217sub now { _time } 1251sub now { _time }
1218sub now_update { } 1252sub now_update { }
… …
1223 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar" 1257 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar"
1224} 1258}
1225 1259
1226# default implementation for ->signal 1260# default implementation for ->signal
1227 1261
1262our $HAVE_ASYNC_INTERRUPT;
1228our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO); 1263our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1264our (%SIG_ASY, %SIG_ASY_W);
1265our ($SIG_COUNT, $SIG_TW);
1229 1266
1230sub _signal_exec { 1267sub _signal_exec {
1268 $HAVE_ASYNC_INTERRUPT
1269 ? $SIGPIPE_R->drain
1231 sysread $SIGPIPE_R, my $dummy, 4; 1270 : sysread $SIGPIPE_R, my $dummy, 9;
1232 1271
1233 while (%SIG_EV) { 1272 while (%SIG_EV) {
1234 for (keys %SIG_EV) { 1273 for (keys %SIG_EV) {
1235 delete $SIG_EV{$_}; 1274 delete $SIG_EV{$_};
1236 $_->() for values %{ $SIG_CB{$_} || {} }; 1275 $_->() for values %{ $SIG_CB{$_} || {} };
1237 } 1276 }
1238 } 1277 }
1239} 1278}
1240 1279
1280# install a dumym wakeupw atcher to reduce signal catching latency
1281sub _sig_add() {
1282 unless ($SIG_COUNT++) {
1283 # try to align timer on a full-second boundary, if possible
1284 my $NOW = AnyEvent->now;
1285
1286 $SIG_TW = AnyEvent->timer (
1287 after => $MAX_SIGNAL_LATENCY - ($NOW - int $NOW),
1288 interval => $MAX_SIGNAL_LATENCY,
1289 cb => sub { }, # just for the PERL_ASYNC_CHECK
1290 );
1291 }
1292}
1293
1294sub _sig_del {
1295 undef $SIG_TW
1296 unless --$SIG_COUNT;
1297}
1298
1299sub _signal {
1300 my (undef, %arg) = @_;
1301
1302 my $signal = uc $arg{signal}
1303 or Carp::croak "required option 'signal' is missing";
1304
1305 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1306
1307 if ($HAVE_ASYNC_INTERRUPT) {
1308 # async::interrupt
1309
1310 $SIG_ASY{$signal} ||= do {
1311 my $asy = new Async::Interrupt
1312 cb => sub { undef $SIG_EV{$signal} },
1313 signal => $signal,
1314 pipe => [$SIGPIPE_R->filenos],
1315 ;
1316 $asy->pipe_autodrain (0);
1317
1318 $asy
1319 };
1320
1321 } else {
1322 # pure perl
1323
1324 $SIG{$signal} ||= sub {
1325 local $!;
1326 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1327 undef $SIG_EV{$signal};
1328 };
1329
1330 # can't do signal processing without introducing races in pure perl,
1331 # so limit the signal latency.
1332 _sig_add;
1333 }
1334
1335 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1336}
1337
1241sub signal { 1338sub signal {
1242 my (undef, %arg) = @_; 1339 # probe for availability of Async::Interrupt
1340 if (!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT} && eval "use Async::Interrupt 0.6 (); 1") {
1341 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
1243 1342
1244 unless ($SIGPIPE_R) { 1343 $HAVE_ASYNC_INTERRUPT = 1;
1344 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1345 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec);
1346
1347 } else {
1348 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
1349
1245 require Fcntl; 1350 require Fcntl;
1246 1351
1247 if (AnyEvent::WIN32) { 1352 if (AnyEvent::WIN32) {
1248 require AnyEvent::Util; 1353 require AnyEvent::Util;
1249 1354
… …
1264 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n"; 1369 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1265 1370
1266 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec); 1371 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec);
1267 } 1372 }
1268 1373
1269 my $signal = uc $arg{signal} 1374 *signal = \&_signal;
1270 or Carp::croak "required option 'signal' is missing"; 1375 &signal
1271
1272 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1273 $SIG{$signal} ||= sub {
1274 local $!;
1275 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1276 undef $SIG_EV{$signal};
1277 };
1278
1279 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1280} 1376}
1281 1377
1282sub AnyEvent::Base::signal::DESTROY { 1378sub AnyEvent::Base::signal::DESTROY {
1283 my ($signal, $cb) = @{$_[0]}; 1379 my ($signal, $cb) = @{$_[0]};
1284 1380
1381 _sig_del;
1382
1285 delete $SIG_CB{$signal}{$cb}; 1383 delete $SIG_CB{$signal}{$cb};
1286 1384
1385 $HAVE_ASYNC_INTERRUPT
1386 ? delete $SIG_ASY{$signal}
1287 # delete doesn't work with older perls - they then 1387 : # delete doesn't work with older perls - they then
1288 # print weird messages, or just unconditionally exit 1388 # print weird messages, or just unconditionally exit
1289 # instead of getting the default action. 1389 # instead of getting the default action.
1390 undef $SIG{$signal}
1290 undef $SIG{$signal} unless keys %{ $SIG_CB{$signal} }; 1391 unless keys %{ $SIG_CB{$signal} };
1291} 1392}
1292 1393
1293# default implementation for ->child 1394# default implementation for ->child
1294 1395
1295our %PID_CB; 1396our %PID_CB;
… …
1297our $CHLD_DELAY_W; 1398our $CHLD_DELAY_W;
1298our $WNOHANG; 1399our $WNOHANG;
1299 1400
1300sub _sigchld { 1401sub _sigchld {
1301 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 1402 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
1403 $_->($pid, $?)
1302 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }), 1404 for values %{ $PID_CB{$pid} || {} },
1303 (values %{ $PID_CB{0} || {} }); 1405 values %{ $PID_CB{0} || {} };
1304 } 1406 }
1305} 1407}
1306 1408
1307sub child { 1409sub child {
1308 my (undef, %arg) = @_; 1410 my (undef, %arg) = @_;
… …
1310 defined (my $pid = $arg{pid} + 0) 1412 defined (my $pid = $arg{pid} + 0)
1311 or Carp::croak "required option 'pid' is missing"; 1413 or Carp::croak "required option 'pid' is missing";
1312 1414
1313 $PID_CB{$pid}{$arg{cb}} = $arg{cb}; 1415 $PID_CB{$pid}{$arg{cb}} = $arg{cb};
1314 1416
1417 # WNOHANG is almost cetrainly 1 everywhere
1418 $WNOHANG ||= $^O =~ /^(?:openbsd|netbsd|linux|freebsd|cygwin|MSWin32)$/
1419 ? 1
1315 $WNOHANG ||= eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1; 1420 : eval { local $SIG{__DIE__}; require POSIX; &POSIX::WNOHANG } || 1;
1316 1421
1317 unless ($CHLD_W) { 1422 unless ($CHLD_W) {
1318 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); 1423 $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
1319 # child could be a zombie already, so make at least one round 1424 # child could be a zombie already, so make at least one round
1320 &_sigchld; 1425 &_sigchld;
… …
1372 1477
1373our @ISA = AnyEvent::CondVar::Base::; 1478our @ISA = AnyEvent::CondVar::Base::;
1374 1479
1375package AnyEvent::CondVar::Base; 1480package AnyEvent::CondVar::Base;
1376 1481
1377use overload 1482#use overload
1378 '&{}' => sub { my $self = shift; sub { $self->send (@_) } }, 1483# '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
1379 fallback => 1; 1484# fallback => 1;
1485
1486# save 300+ kilobytes by dirtily hardcoding overloading
1487${"AnyEvent::CondVar::Base::OVERLOAD"}{dummy}++; # Register with magic by touching.
1488*{'AnyEvent::CondVar::Base::()'} = sub { }; # "Make it findable via fetchmethod."
1489*{'AnyEvent::CondVar::Base::(&{}'} = sub { my $self = shift; sub { $self->send (@_) } }; # &{}
1490${'AnyEvent::CondVar::Base::()'} = 1; # fallback
1491
1492our $WAITING;
1380 1493
1381sub _send { 1494sub _send {
1382 # nop 1495 # nop
1383} 1496}
1384 1497
… …
1397sub ready { 1510sub ready {
1398 $_[0]{_ae_sent} 1511 $_[0]{_ae_sent}
1399} 1512}
1400 1513
1401sub _wait { 1514sub _wait {
1515 $WAITING
1516 and !$_[0]{_ae_sent}
1517 and Carp::croak "AnyEvent::CondVar: recursive blocking wait detected";
1518
1519 local $WAITING = 1;
1402 AnyEvent->one_event while !$_[0]{_ae_sent}; 1520 AnyEvent->one_event while !$_[0]{_ae_sent};
1403} 1521}
1404 1522
1405sub recv { 1523sub recv {
1406 $_[0]->_wait; 1524 $_[0]->_wait;
… …
1468C<PERL_ANYEVENT_MODEL>. 1586C<PERL_ANYEVENT_MODEL>.
1469 1587
1470When set to C<2> or higher, cause AnyEvent to report to STDERR which event 1588When set to C<2> or higher, cause AnyEvent to report to STDERR which event
1471model it chooses. 1589model it chooses.
1472 1590
1591When set to C<8> or higher, then AnyEvent will report extra information on
1592which optional modules it loads and how it implements certain features.
1593
1473=item C<PERL_ANYEVENT_STRICT> 1594=item C<PERL_ANYEVENT_STRICT>
1474 1595
1475AnyEvent does not do much argument checking by default, as thorough 1596AnyEvent does not do much argument checking by default, as thorough
1476argument checking is very costly. Setting this variable to a true value 1597argument checking is very costly. Setting this variable to a true value
1477will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly 1598will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
1478check the arguments passed to most method calls. If it finds any problems, 1599check the arguments passed to most method calls. If it finds any problems,
1479it will croak. 1600it will croak.
1480 1601
1481In other words, enables "strict" mode. 1602In other words, enables "strict" mode.
1482 1603
1483Unlike C<use strict>, it is definitely recommended to keep it off in 1604Unlike C<use strict> (or it's modern cousin, C<< use L<common::sense>
1484production. Keeping C<PERL_ANYEVENT_STRICT=1> in your environment while 1605>>, it is definitely recommended to keep it off in production. Keeping
1485developing programs can be very useful, however. 1606C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
1607can be very useful, however.
1486 1608
1487=item C<PERL_ANYEVENT_MODEL> 1609=item C<PERL_ANYEVENT_MODEL>
1488 1610
1489This can be used to specify the event model to be used by AnyEvent, before 1611This can be used to specify the event model to be used by AnyEvent, before
1490auto detection and -probing kicks in. It must be a string consisting 1612auto detection and -probing kicks in. It must be a string consisting
… …
1552 1674
1553When neither C<ca_file> nor C<ca_path> was specified during 1675When neither C<ca_file> nor C<ca_path> was specified during
1554L<AnyEvent::TLS> context creation, and either of these environment 1676L<AnyEvent::TLS> context creation, and either of these environment
1555variables exist, they will be used to specify CA certificate locations 1677variables exist, they will be used to specify CA certificate locations
1556instead of a system-dependent default. 1678instead of a system-dependent default.
1679
1680=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
1681
1682When these are set to C<1>, then the respective modules are not
1683loaded. Mostly good for testing AnyEvent itself.
1557 1684
1558=back 1685=back
1559 1686
1560=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1687=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1561 1688
… …
2129 if $SIG{CHLD} eq 'IGNORE'; 2256 if $SIG{CHLD} eq 'IGNORE';
2130 2257
2131$SIG{PIPE} = sub { } 2258$SIG{PIPE} = sub { }
2132 unless defined $SIG{PIPE}; 2259 unless defined $SIG{PIPE};
2133 2260
2261=head1 RECOMMENDED/OPTIONAL MODULES
2262
2263One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
2264it's built-in modules) are required to use it.
2265
2266That does not mean that AnyEvent won't take advantage of some additional
2267modules if they are installed.
2268
2269This section epxlains which additional modules will be used, and how they
2270affect AnyEvent's operetion.
2271
2272=over 4
2273
2274=item L<Async::Interrupt>
2275
2276This slightly arcane module is used to implement fast signal handling: To
2277my knowledge, there is no way to do completely race-free and quick
2278signal handling in pure perl. To ensure that signals still get
2279delivered, AnyEvent will start an interval timer to wake up perl (and
2280catch the signals) with some delay (default is 10 seconds, look for
2281C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2282
2283If this module is available, then it will be used to implement signal
2284catching, which means that signals will not be delayed, and the event loop
2285will not be interrupted regularly, which is more efficient (And good for
2286battery life on laptops).
2287
2288This affects not just the pure-perl event loop, but also other event loops
2289that have no signal handling on their own (e.g. Glib, Tk, Qt).
2290
2291Some event loops (POE, Event, Event::Lib) offer signal watchers natively,
2292and either employ their own workarounds (POE) or use AnyEvent's workaround
2293(using C<$AnyEvent::MAX_SIGNAL_LATENCY>). Installing L<Async::Interrupt>
2294does nothing for those backends.
2295
2296=item L<EV>
2297
2298This module isn't really "optional", as it is simply one of the backend
2299event loops that AnyEvent can use. However, it is simply the best event
2300loop available in terms of features, speed and stability: It supports
2301the AnyEvent API optimally, implements all the watcher types in XS, does
2302automatic timer adjustments even when no monotonic clock is available,
2303can take avdantage of advanced kernel interfaces such as C<epoll> and
2304C<kqueue>, and is the fastest backend I<by far>. You can even embed
2305L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>).
2306
2307=item L<Guard>
2308
2309The guard module, when used, will be used to implement
2310C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a
2311lot less memory), but otherwise doesn't affect guard operation much. It is
2312purely used for performance.
2313
2314=item L<JSON> and L<JSON::XS>
2315
2316This module is required when you want to read or write JSON data via
2317L<AnyEvent::Handle>. It is also written in pure-perl, but can take
2318advantage of the ulta-high-speed L<JSON::XS> module when it is installed.
2319
2320In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2321installed.
2322
2323=item L<Net::SSLeay>
2324
2325Implementing TLS/SSL in Perl is certainly interesting, but not very
2326worthwhile: If this module is installed, then L<AnyEvent::Handle> (with
2327the help of L<AnyEvent::TLS>), gains the ability to do TLS/SSL.
2328
2329=item L<Time::HiRes>
2330
2331This module is part of perl since release 5.008. It will be used when the
2332chosen event library does not come with a timing source on it's own. The
2333pure-perl event loop (L<AnyEvent::Impl::Perl>) will additionally use it to
2334try to use a monotonic clock for timing stability.
2335
2336=back
2337
2338
2134=head1 FORK 2339=head1 FORK
2135 2340
2136Most event libraries are not fork-safe. The ones who are usually are 2341Most event libraries are not fork-safe. The ones who are usually are
2137because they rely on inefficient but fork-safe C<select> or C<poll> 2342because they rely on inefficient but fork-safe C<select> or C<poll>
2138calls. Only L<EV> is fully fork-aware. 2343calls. Only L<EV> is fully fork-aware.
2139 2344
2140If you have to fork, you must either do so I<before> creating your first 2345If you have to fork, you must either do so I<before> creating your first
2141watcher OR you must not use AnyEvent at all in the child. 2346watcher OR you must not use AnyEvent at all in the child OR you must do
2347something completely out of the scope of AnyEvent.
2142 2348
2143 2349
2144=head1 SECURITY CONSIDERATIONS 2350=head1 SECURITY CONSIDERATIONS
2145 2351
2146AnyEvent can be forced to load any event model via 2352AnyEvent can be forced to load any event model via

Diff Legend

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