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.233 by root, Thu Jul 9 01:22:50 2009 UTC vs.
Revision 1.242 by root, Fri Jul 17 22:05:12 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.
372
373Also note that many event loops (e.g. Glib, Tk, Qt, IO::Async) do not
374support attaching callbacks to signals, which is a pity, as you cannot do
375race-free signal handling in perl. AnyEvent will try to do it's best, but
376in some cases, signals will be delayed. The maximum time a signal might
377be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10
378seconds). This variable can be changed only before the first signal
379watcher is created, and should be left alone otherwise. Higher values
380will cause fewer spurious wake-ups, which is better for power and CPU
381saving. All these problems can be avoided by installing the optional
382L<Async::Interrupt> module.
370 383
371Example: exit on SIGINT 384Example: exit on SIGINT
372 385
373 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 386 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
374 387
… …
403 416
404This means you cannot create a child watcher as the very first 417This means you cannot create a child watcher as the very first
405thing in an AnyEvent program, you I<have> to create at least one 418thing in an AnyEvent program, you I<have> to create at least one
406watcher before you C<fork> the child (alternatively, you can call 419watcher before you C<fork> the child (alternatively, you can call
407C<AnyEvent::detect>). 420C<AnyEvent::detect>).
421
422As most event loops do not support waiting for child events, they will be
423emulated by AnyEvent in most cases, in which the latency and race problems
424mentioned in the description of signal watchers apply.
408 425
409Example: fork a process and wait for it 426Example: fork a process and wait for it
410 427
411 my $done = AnyEvent->condvar; 428 my $done = AnyEvent->condvar;
412 429
… …
463 480
464If you are familiar with some event loops you will know that all of them 481If 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 482require you to run some blocking "loop", "run" or similar function that
466will actively watch for new events and call your callbacks. 483will actively watch for new events and call your callbacks.
467 484
468AnyEvent is different, it expects somebody else to run the event loop and 485AnyEvent is slightly different: it expects somebody else to run the event
469will only block when necessary (usually when told by the user). 486loop and will only block when necessary (usually when told by the user).
470 487
471The instrument to do that is called a "condition variable", so called 488The instrument to do that is called a "condition variable", so called
472because they represent a condition that must become true. 489because they represent a condition that must become true.
473 490
491Now is probably a good time to look at the examples further below.
492
474Condition variables can be created by calling the C<< AnyEvent->condvar 493Condition variables can be created by calling the C<< AnyEvent->condvar
475>> method, usually without arguments. The only argument pair allowed is 494>> method, usually without arguments. The only argument pair allowed is
476
477C<cb>, which specifies a callback to be called when the condition variable 495C<cb>, which specifies a callback to be called when the condition variable
478becomes true, with the condition variable as the first argument (but not 496becomes true, with the condition variable as the first argument (but not
479the results). 497the results).
480 498
481After creation, the condition variable is "false" until it becomes "true" 499After creation, the condition variable is "false" until it becomes "true"
… …
530 after => 1, 548 after => 1,
531 cb => sub { $result_ready->send }, 549 cb => sub { $result_ready->send },
532 ); 550 );
533 551
534 # this "blocks" (while handling events) till the callback 552 # this "blocks" (while handling events) till the callback
535 # calls send 553 # calls -<send
536 $result_ready->recv; 554 $result_ready->recv;
537 555
538Example: wait for a timer, but take advantage of the fact that 556Example: wait for a timer, but take advantage of the fact that condition
539condition variables are also code references. 557variables are also callable directly.
540 558
541 my $done = AnyEvent->condvar; 559 my $done = AnyEvent->condvar;
542 my $delay = AnyEvent->timer (after => 5, cb => $done); 560 my $delay = AnyEvent->timer (after => 5, cb => $done);
543 $done->recv; 561 $done->recv;
544 562
… …
550 568
551 ... 569 ...
552 570
553 my @info = $couchdb->info->recv; 571 my @info = $couchdb->info->recv;
554 572
555And this is how you would just ste a callback to be called whenever the 573And this is how you would just set a callback to be called whenever the
556results are available: 574results are available:
557 575
558 $couchdb->info->cb (sub { 576 $couchdb->info->cb (sub {
559 my @info = $_[0]->recv; 577 my @info = $_[0]->recv;
560 }); 578 });
… …
578immediately from within send. 596immediately from within send.
579 597
580Any arguments passed to the C<send> call will be returned by all 598Any arguments passed to the C<send> call will be returned by all
581future C<< ->recv >> calls. 599future C<< ->recv >> calls.
582 600
583Condition variables are overloaded so one can call them directly 601Condition variables are overloaded so one can call them directly (as if
584(as a code reference). Calling them directly is the same as calling 602they 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 603C<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 604
592=item $cv->croak ($error) 605=item $cv->croak ($error)
593 606
594Similar to send, but causes all call's to C<< ->recv >> to invoke 607Similar to send, but causes all call's to C<< ->recv >> to invoke
595C<Carp::croak> with the given error message/object/scalar. 608C<Carp::croak> with the given error message/object/scalar.
596 609
597This can be used to signal any errors to the condition variable 610This can be used to signal any errors to the condition variable
598user/consumer. 611user/consumer. Doing it this way instead of calling C<croak> directly
612delays the error detetcion, but has the overwhelmign advantage that it
613diagnoses the error at the place where the result is expected, and not
614deep in some event clalback without connection to the actual code causing
615the problem.
599 616
600=item $cv->begin ([group callback]) 617=item $cv->begin ([group callback])
601 618
602=item $cv->end 619=item $cv->end
603 620
… …
699function will call C<croak>. 716function will call C<croak>.
700 717
701In list context, all parameters passed to C<send> will be returned, 718In list context, all parameters passed to C<send> will be returned,
702in scalar context only the first one will be returned. 719in scalar context only the first one will be returned.
703 720
721Note that doing a blocking wait in a callback is not supported by any
722event loop, that is, recursive invocation of a blocking C<< ->recv
723>> is not allowed, and the C<recv> call will C<croak> if such a
724condition is detected. This condition can be slightly loosened by using
725L<Coro::AnyEvent>, which allows you to do a blocking C<< ->recv >> from
726any thread that doesn't run the event loop itself.
727
704Not all event models support a blocking wait - some die in that case 728Not 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 729(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 730using 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 731caller decide whether the call will block or not (for example, by coupling
708condition variables with some kind of request results and supporting 732condition variables with some kind of request results and supporting
709callbacks so the caller knows that getting the result will not block, 733callbacks so the caller knows that getting the result will not block,
710while still supporting blocking waits if the caller so desires). 734while 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 735
723You can ensure that C<< -recv >> never blocks by setting a callback and 736You can ensure that C<< -recv >> never blocks by setting a callback and
724only calling C<< ->recv >> from within that callback (or at a later 737only calling C<< ->recv >> from within that callback (or at a later
725time). This will work even when the event loop does not support blocking 738time). This will work even when the event loop does not support blocking
726waits otherwise. 739waits otherwise.
… …
1031package AnyEvent; 1044package AnyEvent;
1032 1045
1033no warnings; 1046no warnings;
1034use strict qw(vars subs); 1047use strict qw(vars subs);
1035 1048
1036use Carp; 1049use Carp ();
1037 1050
1038our $VERSION = 4.801; 1051our $VERSION = 4.83;
1039our $MODEL; 1052our $MODEL;
1040 1053
1041our $AUTOLOAD; 1054our $AUTOLOAD;
1042our @ISA; 1055our @ISA;
1043 1056
1044our @REGISTRY; 1057our @REGISTRY;
1045 1058
1046our $WIN32; 1059our $WIN32;
1060
1061our $VERBOSE;
1047 1062
1048BEGIN { 1063BEGIN {
1049 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }"; 1064 eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }";
1050 eval "sub TAINT(){ " . (${^TAINT}*1) . " }"; 1065 eval "sub TAINT(){ " . (${^TAINT}*1) . " }";
1051 1066
1052 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1067 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1053 if ${^TAINT}; 1068 if ${^TAINT};
1054}
1055 1069
1056our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1070 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
1071
1072}
1073
1074our $MAX_SIGNAL_LATENCY = 10;
1057 1075
1058our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1076our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1059 1077
1060{ 1078{
1061 my $idx; 1079 my $idx;
… …
1072 # as the pureperl backend should work everywhere 1090 # as the pureperl backend should work everywhere
1073 # and is usually faster 1091 # and is usually faster
1074 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers 1092 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
1075 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1093 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1076 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1094 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1095 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1077 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1096 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1078 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1079 [Wx:: => AnyEvent::Impl::POE::], 1097 [Wx:: => AnyEvent::Impl::POE::],
1080 [Prima:: => AnyEvent::Impl::POE::], 1098 [Prima:: => AnyEvent::Impl::POE::],
1081 # IO::Async is just too broken - we would need workarounds for its 1099 # IO::Async is just too broken - we would need workarounds for its
1082 # byzantine signal and broken child handling, among others. 1100 # byzantine signal and broken child handling, among others.
1083 # IO::Async is rather hard to detect, as it doesn't have any 1101 # IO::Async is rather hard to detect, as it doesn't have any
… …
1119 1137
1120 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) { 1138 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
1121 my $model = "AnyEvent::Impl::$1"; 1139 my $model = "AnyEvent::Impl::$1";
1122 if (eval "require $model") { 1140 if (eval "require $model") {
1123 $MODEL = $model; 1141 $MODEL = $model;
1124 warn "AnyEvent: loaded model '$model' (forced by \$PERL_ANYEVENT_MODEL), using it.\n" if $verbose > 1; 1142 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
1125 } else { 1143 } else {
1126 warn "AnyEvent: unable to load model '$model' (from \$PERL_ANYEVENT_MODEL):\n$@" if $verbose; 1144 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE;
1127 } 1145 }
1128 } 1146 }
1129 1147
1130 # check for already loaded models 1148 # check for already loaded models
1131 unless ($MODEL) { 1149 unless ($MODEL) {
1132 for (@REGISTRY, @models) { 1150 for (@REGISTRY, @models) {
1133 my ($package, $model) = @$_; 1151 my ($package, $model) = @$_;
1134 if (${"$package\::VERSION"} > 0) { 1152 if (${"$package\::VERSION"} > 0) {
1135 if (eval "require $model") { 1153 if (eval "require $model") {
1136 $MODEL = $model; 1154 $MODEL = $model;
1137 warn "AnyEvent: autodetected model '$model', using it.\n" if $verbose > 1; 1155 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1138 last; 1156 last;
1139 } 1157 }
1140 } 1158 }
1141 } 1159 }
1142 1160
… …
1147 my ($package, $model) = @$_; 1165 my ($package, $model) = @$_;
1148 if (eval "require $package" 1166 if (eval "require $package"
1149 and ${"$package\::VERSION"} > 0 1167 and ${"$package\::VERSION"} > 0
1150 and eval "require $model") { 1168 and eval "require $model") {
1151 $MODEL = $model; 1169 $MODEL = $model;
1152 warn "AnyEvent: autoprobed model '$model', using it.\n" if $verbose > 1; 1170 warn "AnyEvent: autoprobed model '$model', using it.\n" if $VERBOSE >= 2;
1153 last; 1171 last;
1154 } 1172 }
1155 } 1173 }
1156 1174
1157 $MODEL 1175 $MODEL
… …
1173 1191
1174sub AUTOLOAD { 1192sub AUTOLOAD {
1175 (my $func = $AUTOLOAD) =~ s/.*://; 1193 (my $func = $AUTOLOAD) =~ s/.*://;
1176 1194
1177 $method{$func} 1195 $method{$func}
1178 or croak "$func: not a valid method for AnyEvent objects"; 1196 or Carp::croak "$func: not a valid method for AnyEvent objects";
1179 1197
1180 detect unless $MODEL; 1198 detect unless $MODEL;
1181 1199
1182 my $class = shift; 1200 my $class = shift;
1183 $class->$func (@_); 1201 $class->$func (@_);
… …
1188# allow only one watcher per fd, so we dup it to get a different one). 1206# allow only one watcher per fd, so we dup it to get a different one).
1189sub _dupfh($$;$$) { 1207sub _dupfh($$;$$) {
1190 my ($poll, $fh, $r, $w) = @_; 1208 my ($poll, $fh, $r, $w) = @_;
1191 1209
1192 # cygwin requires the fh mode to be matching, unix doesn't 1210 # cygwin requires the fh mode to be matching, unix doesn't
1193 my ($rw, $mode) = $poll eq "r" ? ($r, "<") : ($w, ">"); 1211 my ($rw, $mode) = $poll eq "r" ? ($r, "<&") : ($w, ">&");
1194 1212
1195 open my $fh2, "$mode&", $fh 1213 open my $fh2, $mode, $fh
1196 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,"; 1214 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,";
1197 1215
1198 # we assume CLOEXEC is already set by perl in all important cases 1216 # we assume CLOEXEC is already set by perl in all important cases
1199 1217
1200 ($fh2, $rw) 1218 ($fh2, $rw)
… …
1202 1220
1203package AnyEvent::Base; 1221package AnyEvent::Base;
1204 1222
1205# default implementations for many methods 1223# default implementations for many methods
1206 1224
1207BEGIN { 1225sub _time {
1226 # probe for availability of Time::HiRes
1208 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1227 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1228 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8;
1209 *_time = \&Time::HiRes::time; 1229 *_time = \&Time::HiRes::time;
1210 # if (eval "use POSIX (); (POSIX::times())... 1230 # if (eval "use POSIX (); (POSIX::times())...
1211 } else { 1231 } else {
1232 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE;
1212 *_time = sub { time }; # epic fail 1233 *_time = sub { time }; # epic fail
1213 } 1234 }
1235
1236 &_time
1214} 1237}
1215 1238
1216sub time { _time } 1239sub time { _time }
1217sub now { _time } 1240sub now { _time }
1218sub now_update { } 1241sub now_update { }
… …
1223 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar" 1246 bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar"
1224} 1247}
1225 1248
1226# default implementation for ->signal 1249# default implementation for ->signal
1227 1250
1251our $HAVE_ASYNC_INTERRUPT;
1228our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO); 1252our ($SIGPIPE_R, $SIGPIPE_W, %SIG_CB, %SIG_EV, $SIG_IO);
1253our (%SIG_ASY, %SIG_ASY_W);
1254our ($SIG_COUNT, $SIG_TW);
1229 1255
1230sub _signal_exec { 1256sub _signal_exec {
1257 $HAVE_ASYNC_INTERRUPT
1258 ? $SIGPIPE_R->drain
1231 sysread $SIGPIPE_R, my $dummy, 4; 1259 : sysread $SIGPIPE_R, my $dummy, 9;
1232 1260
1233 while (%SIG_EV) { 1261 while (%SIG_EV) {
1234 for (keys %SIG_EV) { 1262 for (keys %SIG_EV) {
1235 delete $SIG_EV{$_}; 1263 delete $SIG_EV{$_};
1236 $_->() for values %{ $SIG_CB{$_} || {} }; 1264 $_->() for values %{ $SIG_CB{$_} || {} };
1237 } 1265 }
1238 } 1266 }
1239} 1267}
1240 1268
1269sub _signal {
1270 my (undef, %arg) = @_;
1271
1272 my $signal = uc $arg{signal}
1273 or Carp::croak "required option 'signal' is missing";
1274
1275 $SIG_CB{$signal}{$arg{cb}} = $arg{cb};
1276
1277 if ($HAVE_ASYNC_INTERRUPT) {
1278 # async::interrupt
1279
1280 $SIG_ASY{$signal} ||= do {
1281 my $asy = new Async::Interrupt
1282 cb => sub { undef $SIG_EV{$signal} },
1283 signal => $signal,
1284 pipe => [$SIGPIPE_R->filenos],
1285 ;
1286 $asy->pipe_autodrain (0);
1287
1288 $asy
1289 };
1290
1291 } else {
1292 # pure perl
1293
1294 $SIG{$signal} ||= sub {
1295 local $!;
1296 syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV;
1297 undef $SIG_EV{$signal};
1298 };
1299
1300 # can't do signal processing without introducing races in pure perl,
1301 # so limit the signal latency.
1302 ++$SIG_COUNT;
1303 $SIG_TW ||= AnyEvent->timer (
1304 after => $MAX_SIGNAL_LATENCY,
1305 interval => $MAX_SIGNAL_LATENCY,
1306 cb => sub { }, # just for the PERL_ASYNC_CHECK
1307 );
1308 }
1309
1310 bless [$signal, $arg{cb}], "AnyEvent::Base::signal"
1311}
1312
1241sub signal { 1313sub signal {
1242 my (undef, %arg) = @_; 1314 # probe for availability of Async::Interrupt
1315 if (!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT} && eval "use Async::Interrupt 0.6 (); 1") {
1316 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8;
1243 1317
1244 unless ($SIGPIPE_R) { 1318 $HAVE_ASYNC_INTERRUPT = 1;
1319 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1320 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R->fileno, poll => "r", cb => \&_signal_exec);
1321
1322 } else {
1323 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8;
1324
1245 require Fcntl; 1325 require Fcntl;
1246 1326
1247 if (AnyEvent::WIN32) { 1327 if (AnyEvent::WIN32) {
1248 require AnyEvent::Util; 1328 require AnyEvent::Util;
1249 1329
… …
1264 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n"; 1344 or Carp::croak "AnyEvent: unable to create a signal reporting pipe: $!\n";
1265 1345
1266 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec); 1346 $SIG_IO = AnyEvent->io (fh => $SIGPIPE_R, poll => "r", cb => \&_signal_exec);
1267 } 1347 }
1268 1348
1269 my $signal = uc $arg{signal} 1349 *signal = \&_signal;
1270 or Carp::croak "required option 'signal' is missing"; 1350 &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} 1351}
1281 1352
1282sub AnyEvent::Base::signal::DESTROY { 1353sub AnyEvent::Base::signal::DESTROY {
1283 my ($signal, $cb) = @{$_[0]}; 1354 my ($signal, $cb) = @{$_[0]};
1355
1356 undef $SIG_TW
1357 unless --$SIG_COUNT;
1284 1358
1285 delete $SIG_CB{$signal}{$cb}; 1359 delete $SIG_CB{$signal}{$cb};
1286 1360
1287 # delete doesn't work with older perls - they then 1361 # delete doesn't work with older perls - they then
1288 # print weird messages, or just unconditionally exit 1362 # print weird messages, or just unconditionally exit
1289 # instead of getting the default action. 1363 # instead of getting the default action.
1364 undef $SIG{$signal}
1290 undef $SIG{$signal} unless keys %{ $SIG_CB{$signal} }; 1365 unless keys %{ $SIG_CB{$signal} };
1291} 1366}
1292 1367
1293# default implementation for ->child 1368# default implementation for ->child
1294 1369
1295our %PID_CB; 1370our %PID_CB;
… …
1297our $CHLD_DELAY_W; 1372our $CHLD_DELAY_W;
1298our $WNOHANG; 1373our $WNOHANG;
1299 1374
1300sub _sigchld { 1375sub _sigchld {
1301 while (0 < (my $pid = waitpid -1, $WNOHANG)) { 1376 while (0 < (my $pid = waitpid -1, $WNOHANG)) {
1377 $_->($pid, $?)
1302 $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }), 1378 for values %{ $PID_CB{$pid} || {} },
1303 (values %{ $PID_CB{0} || {} }); 1379 values %{ $PID_CB{0} || {} };
1304 } 1380 }
1305} 1381}
1306 1382
1307sub child { 1383sub child {
1308 my (undef, %arg) = @_; 1384 my (undef, %arg) = @_;
… …
1376 1452
1377use overload 1453use overload
1378 '&{}' => sub { my $self = shift; sub { $self->send (@_) } }, 1454 '&{}' => sub { my $self = shift; sub { $self->send (@_) } },
1379 fallback => 1; 1455 fallback => 1;
1380 1456
1457our $WAITING;
1458
1381sub _send { 1459sub _send {
1382 # nop 1460 # nop
1383} 1461}
1384 1462
1385sub send { 1463sub send {
… …
1397sub ready { 1475sub ready {
1398 $_[0]{_ae_sent} 1476 $_[0]{_ae_sent}
1399} 1477}
1400 1478
1401sub _wait { 1479sub _wait {
1480 $WAITING
1481 and !$_[0]{_ae_sent}
1482 and Carp::croak "AnyEvent::CondVar: recursive blocking wait detected";
1483
1484 local $WAITING = 1;
1402 AnyEvent->one_event while !$_[0]{_ae_sent}; 1485 AnyEvent->one_event while !$_[0]{_ae_sent};
1403} 1486}
1404 1487
1405sub recv { 1488sub recv {
1406 $_[0]->_wait; 1489 $_[0]->_wait;
… …
2100 2183
2101A handler for C<SIGCHLD> is installed by AnyEvent's child watcher 2184A handler for C<SIGCHLD> is installed by AnyEvent's child watcher
2102emulation for event loops that do not support them natively. Also, some 2185emulation for event loops that do not support them natively. Also, some
2103event loops install a similar handler. 2186event loops install a similar handler.
2104 2187
2105If, when AnyEvent is loaded, SIGCHLD is set to IGNORE, then AnyEvent will 2188Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE, then
2106reset it to default, to avoid losing child exit statuses. 2189AnyEvent will reset it to default, to avoid losing child exit statuses.
2107 2190
2108=item SIGPIPE 2191=item SIGPIPE
2109 2192
2110A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef> 2193A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef>
2111when AnyEvent gets loaded. 2194when AnyEvent gets loaded.
… …
2129 if $SIG{CHLD} eq 'IGNORE'; 2212 if $SIG{CHLD} eq 'IGNORE';
2130 2213
2131$SIG{PIPE} = sub { } 2214$SIG{PIPE} = sub { }
2132 unless defined $SIG{PIPE}; 2215 unless defined $SIG{PIPE};
2133 2216
2217=head1 RECOMMENDED/OPTIONAL MODULES
2218
2219One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
2220it's built-in modules) are required to use it.
2221
2222That does not mean that AnyEvent won't take advantage of some additional
2223modules if they are installed.
2224
2225This section epxlains which additional modules will be used, and how they
2226affect AnyEvent's operetion.
2227
2228=over 4
2229
2230=item L<Async::Interrupt>
2231
2232This slightly arcane module is used to implement fast signal handling: To
2233my knowledge, there is no way to do completely race-free and quick
2234signal handling in pure perl. To ensure that signals still get
2235delivered, AnyEvent will start an interval timer to wake up perl (and
2236catch the signals) with soemd elay (default is 10 seconds, look for
2237C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2238
2239If this module is available, then it will be used to implement signal
2240catching, which means that signals will not be delayed, and the event loop
2241will not be interrupted regularly, which is more efficient (And good for
2242battery life on laptops).
2243
2244This affects not just the pure-perl event loop, but also other event loops
2245that have no signal handling on their own (e.g. Glib, Tk, Qt).
2246
2247=item L<EV>
2248
2249This module isn't really "optional", as it is simply one of the backend
2250event loops that AnyEvent can use. However, it is simply the best event
2251loop available in terms of features, speed and stability: It supports
2252the AnyEvent API optimally, implements all the watcher types in XS, does
2253automatic timer adjustments even when no monotonic clock is available,
2254can take avdantage of advanced kernel interfaces such as C<epoll> and
2255C<kqueue>, and is the fastest backend I<by far>. You can even embed
2256L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>).
2257
2258=item L<Guard>
2259
2260The guard module, when used, will be used to implement
2261C<AnyEvent::Util::guard>. This speeds up guards considerably (and uses a
2262lot less memory), but otherwise doesn't affect guard operation much. It is
2263purely used for performance.
2264
2265=item L<JSON> and L<JSON::XS>
2266
2267This module is required when you want to read or write JSON data via
2268L<AnyEvent::Handle>. It is also written in pure-perl, but can take
2269advantage of the ulta-high-speed L<JSON::XS> module when it is installed.
2270
2271In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2272installed.
2273
2274=item L<Net::SSLeay>
2275
2276Implementing TLS/SSL in Perl is certainly interesting, but not very
2277worthwhile: If this module is installed, then L<AnyEvent::Handle> (with
2278the help of L<AnyEvent::TLS>), gains the ability to do TLS/SSL.
2279
2280=item L<Time::HiRes>
2281
2282This module is part of perl since release 5.008. It will be used when the
2283chosen event library does not come with a timing source on it's own. The
2284pure-perl event loop (L<AnyEvent::Impl::Perl>) will additionally use it to
2285try to use a monotonic clock for timing stability.
2286
2287=back
2288
2289
2134=head1 FORK 2290=head1 FORK
2135 2291
2136Most event libraries are not fork-safe. The ones who are usually are 2292Most 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> 2293because they rely on inefficient but fork-safe C<select> or C<poll>
2138calls. Only L<EV> is fully fork-aware. 2294calls. Only L<EV> is fully fork-aware.
2139 2295
2140If you have to fork, you must either do so I<before> creating your first 2296If 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. 2297watcher OR you must not use AnyEvent at all in the child OR you must do
2298something completely out of the scope of AnyEvent.
2142 2299
2143 2300
2144=head1 SECURITY CONSIDERATIONS 2301=head1 SECURITY CONSIDERATIONS
2145 2302
2146AnyEvent can be forced to load any event model via 2303AnyEvent can be forced to load any event model via

Diff Legend

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