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.370 by root, Wed Aug 17 02:50:35 2011 UTC vs.
Revision 1.389 by root, Tue Oct 4 05:34:50 2011 UTC

… …
415not restart syscalls (that includes L<Async::Interrupt> and AnyEvent's 415not restart syscalls (that includes L<Async::Interrupt> and AnyEvent's
416pure perl implementation). 416pure perl implementation).
417 417
418=head3 Safe/Unsafe Signals 418=head3 Safe/Unsafe Signals
419 419
420Perl signals can be either "safe" (synchronous to opcode handling) or 420Perl signals can be either "safe" (synchronous to opcode handling)
421"unsafe" (asynchronous) - the former might get delayed indefinitely, the 421or "unsafe" (asynchronous) - the former might delay signal delivery
422latter might corrupt your memory. 422indefinitely, the latter might corrupt your memory.
423 423
424AnyEvent signal handlers are, in addition, synchronous to the event loop, 424AnyEvent signal handlers are, in addition, synchronous to the event loop,
425i.e. they will not interrupt your running perl program but will only be 425i.e. they will not interrupt your running perl program but will only be
426called as part of the normal event handling (just like timer, I/O etc. 426called as part of the normal event handling (just like timer, I/O etc.
427callbacks, too). 427callbacks, too).
428 428
429=head3 Signal Races, Delays and Workarounds 429=head3 Signal Races, Delays and Workarounds
430 430
431Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching 431Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support
432callbacks to signals in a generic way, which is a pity, as you cannot 432attaching callbacks to signals in a generic way, which is a pity,
433do race-free signal handling in perl, requiring C libraries for 433as you cannot do race-free signal handling in perl, requiring
434this. AnyEvent will try to do its best, which means in some cases, 434C libraries for this. AnyEvent will try to do its best, which
435signals will be delayed. The maximum time a signal might be delayed is 435means in some cases, signals will be delayed. The maximum time
436specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 seconds). This 436a signal might be delayed is 10 seconds by default, but can
437variable can be changed only before the first signal watcher is created, 437be overriden via C<$ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY}> or
438and should be left alone otherwise. This variable determines how often 438C<$AnyEvent::MAX_SIGNAL_LATENCY> - see the Ö<ENVIRONMENT VARIABLES>
439AnyEvent polls for signals (in case a wake-up was missed). Higher values 439section for details.
440will cause fewer spurious wake-ups, which is better for power and CPU
441saving.
442 440
443All these problems can be avoided by installing the optional 441All these problems can be avoided by installing the optional
444L<Async::Interrupt> module, which works with most event loops. It will not 442L<Async::Interrupt> module, which works with most event loops. It will not
445work with inherently broken event loops such as L<Event> or L<Event::Lib> 443work with inherently broken event loops such as L<Event> or L<Event::Lib>
446(and not with L<POE> currently, as POE does its own workaround with 444(and not with L<POE> currently). For those, you just have to suffer the
447one-second latency). For those, you just have to suffer the delays. 445delays.
448 446
449=head2 CHILD PROCESS WATCHERS 447=head2 CHILD PROCESS WATCHERS
450 448
451 $w = AnyEvent->child (pid => <process id>, cb => <callback>); 449 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
452 450
… …
878 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 876 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
879 AnyEvent::Impl::POE based on POE, very slow, some limitations. 877 AnyEvent::Impl::POE based on POE, very slow, some limitations.
880 AnyEvent::Impl::Irssi used when running within irssi. 878 AnyEvent::Impl::Irssi used when running within irssi.
881 AnyEvent::Impl::IOAsync based on IO::Async. 879 AnyEvent::Impl::IOAsync based on IO::Async.
882 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop. 880 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop.
883 AnyEvent::Impl::FLTK2 based on FLTK (fltk 2 binding). 881 AnyEvent::Impl::FLTK based on FLTK (fltk 2 binding).
884 882
885=item Backends with special needs. 883=item Backends with special needs.
886 884
887Qt requires the Qt::Application to be instantiated first, but will 885Qt requires the Qt::Application to be instantiated first, but will
888otherwise be picked up automatically. As long as the main program 886otherwise be picked up automatically. As long as the main program
… …
1053 1051
1054=item AnyEvent::log $level, $msg[, @args] 1052=item AnyEvent::log $level, $msg[, @args]
1055 1053
1056Log the given C<$msg> at the given C<$level>. 1054Log the given C<$msg> at the given C<$level>.
1057 1055
1058Loads AnyEvent::Log on first use and calls C<AnyEvent::Log::log> - 1056If L<AnyEvent::Log> is not loaded then this function makes a simple test
1057to see whether the message will be logged. If the test succeeds it will
1058load AnyEvent::Log and call C<AnyEvent::Log::log> - consequently, look at
1059consequently, look at the L<AnyEvent::Log> documentation for details. 1059the L<AnyEvent::Log> documentation for details.
1060
1061If the test fails it will simply return. Right now this happens when a
1062numerical loglevel is used and it is larger than the level specified via
1063C<$ENV{PERL_ANYEVENT_VERBOSE}>.
1060 1064
1061If you want to sprinkle loads of logging calls around your code, consider 1065If you want to sprinkle loads of logging calls around your code, consider
1062creating a logger callback with the C<AnyEvent::Log::logger> function. 1066creating a logger callback with the C<AnyEvent::Log::logger> function,
1067which can reduce typing, codesize and can reduce the logging overhead
1068enourmously.
1063 1069
1064=back 1070=back
1065 1071
1066=head1 WHAT TO DO IN A MODULE 1072=head1 WHAT TO DO IN A MODULE
1067 1073
… …
1160 1166
1161Implement event-based interfaces to the protocols of the same name (for 1167Implement event-based interfaces to the protocols of the same name (for
1162the curious, IGS is the International Go Server and FCP is the Freenet 1168the curious, IGS is the International Go Server and FCP is the Freenet
1163Client Protocol). 1169Client Protocol).
1164 1170
1165=item L<AnyEvent::Handle::UDP>
1166
1167Here be danger!
1168
1169As Pauli would put it, "Not only is it not right, it's not even wrong!" -
1170there are so many things wrong with AnyEvent::Handle::UDP, most notably
1171its use of a stream-based API with a protocol that isn't streamable, that
1172the only way to improve it is to delete it.
1173
1174It features data corruption (but typically only under load) and general
1175confusion. On top, the author is not only clueless about UDP but also
1176fact-resistant - some gems of his understanding: "connect doesn't work
1177with UDP", "UDP packets are not IP packets", "UDP only has datagrams, not
1178packets", "I don't need to implement proper error checking as UDP doesn't
1179support error checking" and so on - he doesn't even understand what's
1180wrong with his module when it is explained to him.
1181
1182=item L<AnyEvent::DBI>
1183
1184Executes L<DBI> requests asynchronously in a proxy process for you,
1185notifying you in an event-based way when the operation is finished.
1186
1187=item L<AnyEvent::AIO> 1171=item L<AnyEvent::AIO>
1188 1172
1189Truly asynchronous (as opposed to non-blocking) I/O, should be in the 1173Truly asynchronous (as opposed to non-blocking) I/O, should be in the
1190toolbox of every event programmer. AnyEvent::AIO transparently fuses 1174toolbox of every event programmer. AnyEvent::AIO transparently fuses
1191L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based 1175L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
1192file I/O, and much more. 1176file I/O, and much more.
1193 1177
1178=item L<AnyEvent::Filesys::Notify>
1179
1180AnyEvent is good for non-blocking stuff, but it can't detect file or
1181path changes (e.g. "watch this directory for new files", "watch this
1182file for changes"). The L<AnyEvent::Filesys::Notify> module promises to
1183do just that in a portbale fashion, supporting inotify on GNU/Linux and
1184some weird, without doubt broken, stuff on OS X to monitor files. It can
1185fall back to blocking scans at regular intervals transparently on other
1186platforms, so it's about as portable as it gets.
1187
1188(I haven't used it myself, but I haven't heard anybody complaining about
1189it yet).
1190
1191=item L<AnyEvent::DBI>
1192
1193Executes L<DBI> requests asynchronously in a proxy process for you,
1194notifying you in an event-based way when the operation is finished.
1195
1194=item L<AnyEvent::HTTPD> 1196=item L<AnyEvent::HTTPD>
1195 1197
1196A simple embedded webserver. 1198A simple embedded webserver.
1197 1199
1198=item L<AnyEvent::FastPing> 1200=item L<AnyEvent::FastPing>
1199 1201
1200The fastest ping in the west. 1202The fastest ping in the west.
1201 1203
1202=item L<Coro> 1204=item L<Coro>
1203 1205
1204Has special support for AnyEvent via L<Coro::AnyEvent>. 1206Has special support for AnyEvent via L<Coro::AnyEvent>, which allows you
1207to simply invert the flow control - don't call us, we will call you:
1208
1209 async {
1210 Coro::AnyEvent::sleep 5; # creates a 5s timer and waits for it
1211 print "5 seconds later!\n";
1212
1213 Coro::AnyEvent::readable *STDIN; # uses an I/O watcher
1214 my $line = <STDIN>; # works for ttys
1215
1216 AnyEvent::HTTP::http_get "url", Coro::rouse_cb;
1217 my ($body, $hdr) = Coro::rouse_wait;
1218 };
1205 1219
1206=back 1220=back
1207 1221
1208=cut 1222=cut
1209 1223
… …
1219 1233
1220BEGIN { AnyEvent::common_sense } 1234BEGIN { AnyEvent::common_sense }
1221 1235
1222use Carp (); 1236use Carp ();
1223 1237
1224our $VERSION = '6.01'; 1238our $VERSION = '6.02';
1225our $MODEL; 1239our $MODEL;
1226
1227our @ISA; 1240our @ISA;
1228
1229our @REGISTRY; 1241our @REGISTRY;
1230
1231our $VERBOSE; 1242our $VERBOSE;
1243our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1244our $MAX_SIGNAL_LATENCY = $ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY} || 10; # executes after the BEGIN block below (tainting!)
1232 1245
1233BEGIN { 1246BEGIN {
1234 require "AnyEvent/constants.pl"; 1247 require "AnyEvent/constants.pl";
1235 1248
1236 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1249 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1237 1250
1238 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1251 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1239 if ${^TAINT}; 1252 if ${^TAINT};
1240 1253
1241 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1254 $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
1242} 1255 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1243 1256
1244our $MAX_SIGNAL_LATENCY = 10; 1257 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1258 if ${^TAINT};
1245 1259
1246our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1260 # $ENV{PERL_ANYEVENT_xxx} now valid
1247 1261
1248{ 1262 $VERBOSE = length $ENV{PERL_ANYEVENT_VERBOSE} ? $ENV{PERL_ANYEVENT_VERBOSE}*1 : 4;
1263
1249 my $idx; 1264 my $idx;
1250 $PROTOCOL{$_} = ++$idx 1265 $PROTOCOL{$_} = ++$idx
1251 for reverse split /\s*,\s*/, 1266 for reverse split /\s*,\s*/,
1252 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1267 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1253} 1268}
… …
1285 1300
1286 () 1301 ()
1287} 1302}
1288 1303
1289sub log($$;@) { 1304sub log($$;@) {
1290 require AnyEvent::Log; 1305 # only load the big bloated module when we actually are about to log something
1306 if ($_[0] <= ($VERBOSE || 1)) { # also catches non-numeric levels(!) and fatal
1307 local ($!, $@);
1308 require AnyEvent::Log; # among other things, sets $VERBOSE to 9
1291 # AnyEvent::Log overwrites this function 1309 # AnyEvent::Log overwrites this function
1292 goto &log; 1310 goto &log;
1311 }
1312
1313 0 # not logged
1314}
1315
1316sub _logger($;$) {
1317 my ($level, $renabled) = @_;
1318
1319 $$renabled = $level <= $VERBOSE;
1320
1321 my $logger = [(caller)[0], $level, $renabled];
1322
1323 $AnyEvent::Log::LOGGER{$logger+0} = $logger;
1324
1325# return unless defined wantarray;
1326#
1327# require AnyEvent::Util;
1328# my $guard = AnyEvent::Util::guard (sub {
1329# # "clean up"
1330# delete $LOGGER{$logger+0};
1331# });
1332#
1333# sub {
1334# return 0 unless $$renabled;
1335#
1336# $guard if 0; # keep guard alive, but don't cause runtime overhead
1337# require AnyEvent::Log unless $AnyEvent::Log::VERSION;
1338# package AnyEvent::Log;
1339# _log ($logger->[0], $level, @_) # logger->[0] has been converted at load time
1340# }
1341}
1342
1343if (length $ENV{PERL_ANYEVENT_LOG}) {
1344 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1293} 1345}
1294 1346
1295our @models = ( 1347our @models = (
1296 [EV:: => AnyEvent::Impl::EV:: , 1], 1348 [EV:: => AnyEvent::Impl::EV::],
1297 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1349 [AnyEvent::Loop:: => AnyEvent::Impl::Perl::],
1298 # everything below here will not (normally) be autoprobed 1350 # everything below here will not (normally) be autoprobed
1299 # as the pure perl backend should work everywhere 1351 # as the pure perl backend should work everywhere
1300 # and is usually faster 1352 # and is usually faster
1353 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package, so msut be near the top
1301 [Event:: => AnyEvent::Impl::Event::, 1], 1354 [Event:: => AnyEvent::Impl::Event::], # slow, stable
1302 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers 1355 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
1356 # everything below here should not be autoloaded
1303 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1357 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1304 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1305 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1358 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1306 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1359 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1307 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1360 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1308 [Wx:: => AnyEvent::Impl::POE::], 1361 [Wx:: => AnyEvent::Impl::POE::],
1309 [Prima:: => AnyEvent::Impl::POE::], 1362 [Prima:: => AnyEvent::Impl::POE::],
1310 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect 1363 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1311 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::], 1364 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1312 [FLTK:: => AnyEvent::Impl::FLTK2::], 1365 [FLTK:: => AnyEvent::Impl::FLTK::],
1313); 1366);
1314 1367
1315our @isa_hook; 1368our @isa_hook;
1316 1369
1317sub _isa_set { 1370sub _isa_set {
… …
1337# due to bugs in perls method cache implementation. 1390# due to bugs in perls method cache implementation.
1338our @methods = qw(io timer time now now_update signal child idle condvar); 1391our @methods = qw(io timer time now now_update signal child idle condvar);
1339 1392
1340sub detect() { 1393sub detect() {
1341 return $MODEL if $MODEL; # some programs keep references to detect 1394 return $MODEL if $MODEL; # some programs keep references to detect
1395
1396 # IO::Async::Loop::AnyEvent is extremely evil, refuse to work with it
1397 # the author knows about the problems and what it does to AnyEvent as a whole
1398 # (and the ability of others to use AnyEvent), but simply wants to abuse AnyEvent
1399 # anyway.
1400 AnyEvent::log fatal => "AnyEvent: IO::Async::Loop::AnyEvent detected - this module is broken by design,\n"
1401 . "abuses internals and breaks AnyEvent, will not continue."
1402 if exists $INC{"IO/Async/Loop/AnyEvent.pm"};
1342 1403
1343 local $!; # for good measure 1404 local $!; # for good measure
1344 local $SIG{__DIE__}; # we use eval 1405 local $SIG{__DIE__}; # we use eval
1345 1406
1346 # free some memory 1407 # free some memory
… …
1355 1416
1356 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) { 1417 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1357 my $model = $1; 1418 my $model = $1;
1358 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//; 1419 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1359 if (eval "require $model") { 1420 if (eval "require $model") {
1421 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1360 $MODEL = $model; 1422 $MODEL = $model;
1361 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it."
1362 if $VERBOSE >= 7;
1363 } else { 1423 } else {
1364 AnyEvent::log warn => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@"; 1424 AnyEvent::log 4 => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1365 } 1425 }
1366 } 1426 }
1367 1427
1368 # check for already loaded models 1428 # check for already loaded models
1369 unless ($MODEL) { 1429 unless ($MODEL) {
1370 for (@REGISTRY, @models) { 1430 for (@REGISTRY, @models) {
1371 my ($package, $model) = @$_; 1431 my ($package, $model) = @$_;
1372 if (${"$package\::VERSION"} > 0) { 1432 if (${"$package\::VERSION"} > 0) {
1373 if (eval "require $model") { 1433 if (eval "require $model") {
1434 AnyEvent::log 7 => "autodetected model '$model', using it.";
1374 $MODEL = $model; 1435 $MODEL = $model;
1375 AnyEvent::log 7 => "autodetected model '$model', using it."
1376 if $VERBOSE >= 7;
1377 last; 1436 last;
1378 } 1437 }
1379 } 1438 }
1380 } 1439 }
1381 1440
1382 unless ($MODEL) { 1441 unless ($MODEL) {
1383 # try to autoload a model 1442 # try to autoload a model
1384 for (@REGISTRY, @models) { 1443 for (@REGISTRY, @models) {
1385 my ($package, $model, $autoload) = @$_; 1444 my ($package, $model) = @$_;
1386 if ( 1445 if (
1387 $autoload
1388 and eval "require $package" 1446 eval "require $package"
1389 and ${"$package\::VERSION"} > 0 1447 and ${"$package\::VERSION"} > 0
1390 and eval "require $model" 1448 and eval "require $model"
1391 ) { 1449 ) {
1450 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1392 $MODEL = $model; 1451 $MODEL = $model;
1393 AnyEvent::log 7 => "autoloaded model '$model', using it."
1394 if $VERBOSE >= 7;
1395 last; 1452 last;
1396 } 1453 }
1397 } 1454 }
1398 1455
1399 $MODEL 1456 $MODEL
1400 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?"; 1457 or AnyEvent::log fatal => "AnyEvent: backend autodetection failed - did you properly install AnyEvent?";
1401 } 1458 }
1402 } 1459 }
1403 1460
1404 # free memory only needed for probing 1461 # free memory only needed for probing
1405 undef @models; 1462 undef @models;
… …
1549 1606
1550sub time { 1607sub time {
1551 eval q{ # poor man's autoloading {} 1608 eval q{ # poor man's autoloading {}
1552 # probe for availability of Time::HiRes 1609 # probe for availability of Time::HiRes
1553 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1610 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1554 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy."
1555 if $AnyEvent::VERBOSE >= 8;
1556 *time = sub { Time::HiRes::time () }; 1611 *time = sub { Time::HiRes::time () };
1557 *AE::time = \& Time::HiRes::time ; 1612 *AE::time = \& Time::HiRes::time ;
1613 *now = \&time;
1614 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy.";
1558 # if (eval "use POSIX (); (POSIX::times())... 1615 # if (eval "use POSIX (); (POSIX::times())...
1559 } else { 1616 } else {
1560 AnyEvent::log critical => "using built-in time(), WARNING, no sub-second resolution!";
1561 *time = sub { CORE::time }; 1617 *time = sub { CORE::time };
1562 *AE::time = sub (){ CORE::time }; 1618 *AE::time = sub (){ CORE::time };
1619 *now = \&time;
1620 AnyEvent::log 3 => "using built-in time(), WARNING, no sub-second resolution!";
1563 } 1621 }
1564
1565 *now = \&time;
1566 }; 1622 };
1567 die if $@; 1623 die if $@;
1568 1624
1569 &time 1625 &time
1570} 1626}
… …
1663 1719
1664sub signal { 1720sub signal {
1665 eval q{ # poor man's autoloading {} 1721 eval q{ # poor man's autoloading {}
1666 # probe for availability of Async::Interrupt 1722 # probe for availability of Async::Interrupt
1667 if (_have_async_interrupt) { 1723 if (_have_async_interrupt) {
1668 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling." 1724 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling.";
1669 if $AnyEvent::VERBOSE >= 8;
1670 1725
1671 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1726 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1672 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1727 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1673 1728
1674 } else { 1729 } else {
1675 AnyEvent::log 8 => "using emulated perl signal handling with latency timer." 1730 AnyEvent::log 8 => "using emulated perl signal handling with latency timer.";
1676 if $AnyEvent::VERBOSE >= 8;
1677 1731
1678 if (AnyEvent::WIN32) { 1732 if (AnyEvent::WIN32) {
1679 require AnyEvent::Util; 1733 require AnyEvent::Util;
1680 1734
1681 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1735 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
… …
1975$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 2029$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1976so on. 2030so on.
1977 2031
1978=head1 ENVIRONMENT VARIABLES 2032=head1 ENVIRONMENT VARIABLES
1979 2033
1980The following environment variables are used by this module or its 2034AnyEvent supports a number of environment variables that tune the
1981submodules. 2035runtime behaviour. They are usually evaluated when AnyEvent is
2036loaded, initialised, or a submodule that uses them is loaded. Many of
2037them also cause AnyEvent to load additional modules - for example,
2038C<PERL_ANYEVENT_DEBUG_WRAP> causes the L<AnyEvent::Debug> module to be
2039loaded.
1982 2040
1983Note that AnyEvent will remove I<all> environment variables starting with 2041All the environment variables documented here start with
1984C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 2042C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1985enabled. 2043namespace. Other modules are encouraged (but by no means required) to use
2044C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
2045namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
2046be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
2047variables starting with C<AE_>, see below).
2048
2049All variables can also be set via the C<AE_> prefix, that is, instead
2050of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
2051case there is a clash btween anyevent and another program that uses
2052C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
2053variable to the empty string, as those variables take precedence.
2054
2055When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
2056to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
2057exists. If taint mode is on, then AnyEvent will remove I<all> environment
2058variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
2059with C<undef> or the empty string, if the corresaponding C<AE_> variable
2060is set).
2061
2062The exact algorithm is currently:
2063
2064 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
2065 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
2066 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
2067
2068This ensures that child processes will not see the C<AE_> variables.
2069
2070The following environment variables are currently known to AnyEvent:
1986 2071
1987=over 4 2072=over 4
1988 2073
1989=item C<PERL_ANYEVENT_VERBOSE> 2074=item C<PERL_ANYEVENT_VERBOSE>
1990 2075
1991By default, AnyEvent will be completely silent except in fatal 2076By default, AnyEvent will only log messages with loglevel C<3>
1992conditions. You can set this environment variable to make AnyEvent more 2077(C<critical>) or higher (see L<AnyEvent::Log>). You can set this
2078environment variable to a numerical loglevel to make AnyEvent more (or
1993talkative. 2079less) talkative.
1994 2080
2081If you want to do more than just set the global logging level
2082you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
2083complex specifications.
2084
2085When set to C<0> (C<off>), then no messages whatsoever will be logged with
2086the default logging settings.
2087
1995When set to C<5> or higher, causes AnyEvent to warn about unexpected 2088When set to C<5> or higher (C<warn>), causes AnyEvent to warn about
1996conditions, such as not being able to load the event model specified by 2089unexpected conditions, such as not being able to load the event model
1997C<PERL_ANYEVENT_MODEL>. 2090specified by C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an
2091exception - this is the minimum recommended level.
1998 2092
1999When set to C<7> or higher, cause AnyEvent to report to STDERR which event 2093When set to C<7> or higher (info), cause AnyEvent to report which event model it
2000model it chooses. 2094chooses.
2001 2095
2002When set to C<8> or higher, then AnyEvent will report extra information on 2096When set to C<8> or higher (debug), then AnyEvent will report extra information on
2003which optional modules it loads and how it implements certain features. 2097which optional modules it loads and how it implements certain features.
2098
2099=item C<PERL_ANYEVENT_LOG>
2100
2101Accepts rather complex logging specifications. For example, you could log
2102all C<debug> messages of some module to stderr, warnings and above to
2103stderr, and errors and above to syslog, with:
2104
2105 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
2106
2107For the rather extensive details, see L<AnyEvent::Log>.
2108
2109This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
2110so will take effect even before AnyEvent has initialised itself.
2111
2112Note that specifying this environment variable causes the L<AnyEvent::Log>
2113module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
2114using the latter saves a few hundred kB of memory until the first message
2115is being logged.
2004 2116
2005=item C<PERL_ANYEVENT_STRICT> 2117=item C<PERL_ANYEVENT_STRICT>
2006 2118
2007AnyEvent does not do much argument checking by default, as thorough 2119AnyEvent does not do much argument checking by default, as thorough
2008argument checking is very costly. Setting this variable to a true value 2120argument checking is very costly. Setting this variable to a true value
… …
2017C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs 2129C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
2018can be very useful, however. 2130can be very useful, however.
2019 2131
2020=item C<PERL_ANYEVENT_DEBUG_SHELL> 2132=item C<PERL_ANYEVENT_DEBUG_SHELL>
2021 2133
2022If this env variable is set, then its contents will be interpreted by 2134If this env variable is nonempty, then its contents will be interpreted by
2023C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of 2135C<AnyEvent::Socket::parse_hostport> and C<AnyEvent::Debug::shell> (after
2024C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on 2136replacing every occurance of C<$$> by the process pid). The shell object
2025that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>. 2137is saved in C<$AnyEvent::Debug::SHELL>.
2026 2138
2027This takes place when the first watcher is created. 2139This happens when the first watcher is created.
2028 2140
2029For example, to bind a debug shell on a unix domain socket in 2141For example, to bind a debug shell on a unix domain socket in
2030F<< /tmp/debug<pid>.sock >>, you could use this: 2142F<< /tmp/debug<pid>.sock >>, you could use this:
2031 2143
2032 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog 2144 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
2145 # connect with e.g.: socat readline /tmp/debug123.sock
2033 2146
2147Or to bind to tcp port 4545 on localhost:
2148
2149 PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
2150 # connect with e.g.: telnet localhost 4545
2151
2034Note that creating sockets in F</tmp> is very unsafe on multiuser 2152Note that creating sockets in F</tmp> or on localhost is very unsafe on
2035systems. 2153multiuser systems.
2036 2154
2037=item C<PERL_ANYEVENT_DEBUG_WRAP> 2155=item C<PERL_ANYEVENT_DEBUG_WRAP>
2038 2156
2039Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for 2157Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for
2040debugging purposes. See C<AnyEvent::Debug::wrap> for details. 2158debugging purposes. See C<AnyEvent::Debug::wrap> for details.
… …
2078but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4> 2196but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
2079- only support IPv4, never try to resolve or contact IPv6 2197- only support IPv4, never try to resolve or contact IPv6
2080addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2198addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
2081IPv6, but prefer IPv6 over IPv4. 2199IPv6, but prefer IPv6 over IPv4.
2082 2200
2201=item C<PERL_ANYEVENT_HOSTS>
2202
2203This variable, if specified, overrides the F</etc/hosts> file used by
2204L<AnyEvent::Socket>C<::resolve_sockaddr>, i.e. hosts aliases will be read
2205from that file instead.
2206
2083=item C<PERL_ANYEVENT_EDNS0> 2207=item C<PERL_ANYEVENT_EDNS0>
2084 2208
2085Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension 2209Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension for
2086for DNS. This extension is generally useful to reduce DNS traffic, but 2210DNS. This extension is generally useful to reduce DNS traffic, especially
2087some (broken) firewalls drop such DNS packets, which is why it is off by 2211when DNSSEC is involved, but some (broken) firewalls drop such DNS
2088default. 2212packets, which is why it is off by default.
2089 2213
2090Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 2214Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
2091EDNS0 in its DNS requests. 2215EDNS0 in its DNS requests.
2092 2216
2093=item C<PERL_ANYEVENT_MAX_FORKS> 2217=item C<PERL_ANYEVENT_MAX_FORKS>
… …
2099 2223
2100The default value for the C<max_outstanding> parameter for the default DNS 2224The default value for the C<max_outstanding> parameter for the default DNS
2101resolver - this is the maximum number of parallel DNS requests that are 2225resolver - this is the maximum number of parallel DNS requests that are
2102sent to the DNS server. 2226sent to the DNS server.
2103 2227
2228=item C<PERL_ANYEVENT_MAX_SIGNAL_LATENCY>
2229
2230Perl has inherently racy signal handling (you can basically choose between
2231losing signals and memory corruption) - pure perl event loops (including
2232C<AnyEvent::Loop>, when C<Async::Interrupt> isn't available) therefore
2233have to poll regularly to avoid losing signals.
2234
2235Some event loops are racy, but don't poll regularly, and some event loops
2236are written in C but are still racy. For those event loops, AnyEvent
2237installs a timer that regularly wakes up the event loop.
2238
2239By default, the interval for this timer is C<10> seconds, but you can
2240override this delay with this environment variable (or by setting
2241the C<$AnyEvent::MAX_SIGNAL_LATENCY> variable before creating signal
2242watchers).
2243
2244Lower values increase CPU (and energy) usage, higher values can introduce
2245long delays when reaping children or waiting for signals.
2246
2247The L<AnyEvent::Async> module, if available, will be used to avoid this
2248polling (with most event loops).
2249
2104=item C<PERL_ANYEVENT_RESOLV_CONF> 2250=item C<PERL_ANYEVENT_RESOLV_CONF>
2105 2251
2106The file to use instead of F</etc/resolv.conf> (or OS-specific 2252The absolute path to a F<resolv.conf>-style file to use instead of
2107configuration) in the default resolver. When set to the empty string, no 2253F</etc/resolv.conf> (or the OS-specific configuration) in the default
2108default config will be used. 2254resolver, or the empty string to select the default configuration.
2109 2255
2110=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2256=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
2111 2257
2112When neither C<ca_file> nor C<ca_path> was specified during 2258When neither C<ca_file> nor C<ca_path> was specified during
2113L<AnyEvent::TLS> context creation, and either of these environment 2259L<AnyEvent::TLS> context creation, and either of these environment
2114variables exist, they will be used to specify CA certificate locations 2260variables are nonempty, they will be used to specify CA certificate
2115instead of a system-dependent default. 2261locations instead of a system-dependent default.
2116 2262
2117=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT> 2263=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
2118 2264
2119When these are set to C<1>, then the respective modules are not 2265When these are set to C<1>, then the respective modules are not
2120loaded. Mostly good for testing AnyEvent itself. 2266loaded. Mostly good for testing AnyEvent itself.

Diff Legend

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