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.365 by root, Tue Aug 16 14:47:26 2011 UTC vs.
Revision 1.384 by root, Mon Sep 5 07:21:54 2011 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - the DBI of event loop programming 3AnyEvent - the DBI of event loop programming
4 4
5EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt 5EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt,
6and POE are various supported event loops/environments. 6FLTK and POE are various supported event loops/environments.
7 7
8=head1 SYNOPSIS 8=head1 SYNOPSIS
9 9
10 use AnyEvent; 10 use AnyEvent;
11 11
… …
878 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 878 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
879 AnyEvent::Impl::POE based on POE, very slow, some limitations. 879 AnyEvent::Impl::POE based on POE, very slow, some limitations.
880 AnyEvent::Impl::Irssi used when running within irssi. 880 AnyEvent::Impl::Irssi used when running within irssi.
881 AnyEvent::Impl::IOAsync based on IO::Async. 881 AnyEvent::Impl::IOAsync based on IO::Async.
882 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop. 882 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop.
883 AnyEvent::Impl::FLTK2 based on FLTK (fltk 2 binding). 883 AnyEvent::Impl::FLTK based on FLTK (fltk 2 binding).
884 884
885=item Backends with special needs. 885=item Backends with special needs.
886 886
887Qt requires the Qt::Application to be instantiated first, but will 887Qt requires the Qt::Application to be instantiated first, but will
888otherwise be picked up automatically. As long as the main program 888otherwise be picked up automatically. As long as the main program
… …
1053 1053
1054=item AnyEvent::log $level, $msg[, @args] 1054=item AnyEvent::log $level, $msg[, @args]
1055 1055
1056Log the given C<$msg> at the given C<$level>. 1056Log the given C<$msg> at the given C<$level>.
1057 1057
1058Loads AnyEvent::Log on first use and calls C<AnyEvent::Log::log> - 1058If L<AnyEvent::Log> is not loaded then this function makes a simple test
1059to see whether the message will be logged. If the test succeeds it will
1060load AnyEvent::Log and call C<AnyEvent::Log::log> - consequently, look at
1059consequently, look at the L<AnyEvent::Log> documentation for details. 1061the L<AnyEvent::Log> documentation for details.
1062
1063If the test fails it will simply return. Right now this happens when a
1064numerical loglevel is used and it is larger than the level specified via
1065C<$ENV{PERL_ANYEVENT_VERBOSE}>.
1066
1067If you want to sprinkle loads of logging calls around your code, consider
1068creating a logger callback with the C<AnyEvent::Log::logger> function,
1069which can reduce typing, codesize and can reduce the logging overhead
1070enourmously.
1060 1071
1061=back 1072=back
1062 1073
1063=head1 WHAT TO DO IN A MODULE 1074=head1 WHAT TO DO IN A MODULE
1064 1075
… …
1121 1132
1122 1133
1123=head1 OTHER MODULES 1134=head1 OTHER MODULES
1124 1135
1125The following is a non-exhaustive list of additional modules that use 1136The following is a non-exhaustive list of additional modules that use
1126AnyEvent as a client and can therefore be mixed easily with other AnyEvent 1137AnyEvent as a client and can therefore be mixed easily with other
1127modules and other event loops in the same program. Some of the modules 1138AnyEvent modules and other event loops in the same program. Some of the
1128come as part of AnyEvent, the others are available via CPAN. 1139modules come as part of AnyEvent, the others are available via CPAN (see
1140L<http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for
1141a longer non-exhaustive list), and the list is heavily biased towards
1142modules of the AnyEvent author himself :)
1129 1143
1130=over 4 1144=over 4
1131 1145
1132=item L<AnyEvent::Util> 1146=item L<AnyEvent::Util>
1133 1147
… …
1153=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP> 1167=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP>
1154 1168
1155Implement event-based interfaces to the protocols of the same name (for 1169Implement event-based interfaces to the protocols of the same name (for
1156the curious, IGS is the International Go Server and FCP is the Freenet 1170the curious, IGS is the International Go Server and FCP is the Freenet
1157Client Protocol). 1171Client Protocol).
1158
1159=item L<AnyEvent::Handle::UDP>
1160
1161Here be danger!
1162
1163As Pauli would put it, "Not only is it not right, it's not even wrong!" -
1164there are so many things wrong with AnyEvent::Handle::UDP, most notably
1165its use of a stream-based API with a protocol that isn't streamable, that
1166the only way to improve it is to delete it.
1167
1168It features data corruption (but typically only under load) and general
1169confusion. On top, the author is not only clueless about UDP but also
1170fact-resistant - some gems of his understanding: "connect doesn't work
1171with UDP", "UDP packets are not IP packets", "UDP only has datagrams, not
1172packets", "I don't need to implement proper error checking as UDP doesn't
1173support error checking" and so on - he doesn't even understand what's
1174wrong with his module when it is explained to him.
1175
1176=item L<AnyEvent::DBI>
1177
1178Executes L<DBI> requests asynchronously in a proxy process for you,
1179notifying you in an event-based way when the operation is finished.
1180 1172
1181=item L<AnyEvent::AIO> 1173=item L<AnyEvent::AIO>
1182 1174
1183Truly asynchronous (as opposed to non-blocking) I/O, should be in the 1175Truly asynchronous (as opposed to non-blocking) I/O, should be in the
1184toolbox of every event programmer. AnyEvent::AIO transparently fuses 1176toolbox of every event programmer. AnyEvent::AIO transparently fuses
1185L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based 1177L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
1186file I/O, and much more. 1178file I/O, and much more.
1187 1179
1180=item L<AnyEvent::Filesys::Notify>
1181
1182AnyEvent is good for non-blocking stuff, but it can't detect file or
1183path changes (e.g. "watch this directory for new files", "watch this
1184file for changes"). The L<AnyEvent::Filesys::Notify> module promises to
1185do just that in a portbale fashion, supporting inotify on GNU/Linux and
1186some weird, without doubt broken, stuff on OS X to monitor files. It can
1187fall back to blocking scans at regular intervals transparently on other
1188platforms, so it's about as portable as it gets.
1189
1190(I haven't used it myself, but I haven't heard anybody complaining about
1191it yet).
1192
1193=item L<AnyEvent::DBI>
1194
1195Executes L<DBI> requests asynchronously in a proxy process for you,
1196notifying you in an event-based way when the operation is finished.
1197
1188=item L<AnyEvent::HTTPD> 1198=item L<AnyEvent::HTTPD>
1189 1199
1190A simple embedded webserver. 1200A simple embedded webserver.
1191 1201
1192=item L<AnyEvent::FastPing> 1202=item L<AnyEvent::FastPing>
1193 1203
1194The fastest ping in the west. 1204The fastest ping in the west.
1195 1205
1196=item L<Coro> 1206=item L<Coro>
1197 1207
1198Has special support for AnyEvent via L<Coro::AnyEvent>. 1208Has special support for AnyEvent via L<Coro::AnyEvent>, which allows you
1209to simply invert the flow control - don't call us, we will call you:
1210
1211 async {
1212 Coro::AnyEvent::sleep 5; # creates a 5s timer and waits for it
1213 print "5 seconds later!\n";
1214
1215 Coro::AnyEvent::readable *STDIN; # uses an I/O watcher
1216 my $line = <STDIN>; # works for ttys
1217
1218 AnyEvent::HTTP::http_get "url", Coro::rouse_cb;
1219 my ($body, $hdr) = Coro::rouse_wait;
1220 };
1199 1221
1200=back 1222=back
1201 1223
1202=cut 1224=cut
1203 1225
… …
1213 1235
1214BEGIN { AnyEvent::common_sense } 1236BEGIN { AnyEvent::common_sense }
1215 1237
1216use Carp (); 1238use Carp ();
1217 1239
1218our $VERSION = '6.01'; 1240our $VERSION = '6.02';
1219our $MODEL; 1241our $MODEL;
1220
1221our @ISA; 1242our @ISA;
1222
1223our @REGISTRY; 1243our @REGISTRY;
1224
1225our $VERBOSE; 1244our $VERBOSE;
1245our $MAX_SIGNAL_LATENCY = 10;
1246our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1226 1247
1227BEGIN { 1248BEGIN {
1228 require "AnyEvent/constants.pl"; 1249 require "AnyEvent/constants.pl";
1229 1250
1230 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1251 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1231 1252
1232 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1253 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1233 if ${^TAINT}; 1254 if ${^TAINT};
1234 1255
1235 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1256 $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
1236} 1257 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1237 1258
1238our $MAX_SIGNAL_LATENCY = 10; 1259 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1260 if ${^TAINT};
1239 1261
1240our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1262 # $ENV{PERL_ANYEVENT_xxx} now valid
1241 1263
1242{ 1264 $VERBOSE = length $ENV{PERL_ANYEVENT_VERBOSE} ? $ENV{PERL_ANYEVENT_VERBOSE}*1 : 4;
1265
1243 my $idx; 1266 my $idx;
1244 $PROTOCOL{$_} = ++$idx 1267 $PROTOCOL{$_} = ++$idx
1245 for reverse split /\s*,\s*/, 1268 for reverse split /\s*,\s*/,
1246 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1269 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1247} 1270}
… …
1279 1302
1280 () 1303 ()
1281} 1304}
1282 1305
1283sub log($$;@) { 1306sub log($$;@) {
1284 require AnyEvent::Log; 1307 # only load the big bloated module when we actually are about to log something
1308 if ($_[0] <= ($VERBOSE || 1)) { # also catches non-numeric levels(!) and fatal
1309 require AnyEvent::Log; # among other things, sets $VERBOSE to 9
1285 # AnyEvent::Log overwrites this function 1310 # AnyEvent::Log overwrites this function
1286 goto &log; 1311 goto &log;
1312 }
1313
1314 0 # not logged
1315}
1316
1317sub logger($;$) {
1318 package AnyEvent::Log;
1319
1320 my ($level, $renabled) = @_;
1321
1322 $$renabled = $level <= $VERBOSE;
1323
1324 my $pkg = (caller)[0];
1325
1326 my $logger = [$pkg, $level, $renabled];
1327
1328 our %LOGGER;
1329 $LOGGER{$logger+0} = $logger;
1330
1331 require AnyEvent::Util;
1332 my $guard = AnyEvent::Util::guard (sub {
1333 # "clean up"
1334 delete $LOGGER{$logger+0};
1335 });
1336
1337 sub {
1338 return 0 unless $$renabled;
1339
1340 $guard if 0; # keep guard alive, but don't cause runtime overhead
1341 require AnyEvent::Log unless $AnyEvent::Log::VERSION;
1342 package AnyEvent::Log;
1343 _log ($logger->[0], $level, @_) # logger->[0] has been converted at load time
1344 }
1345}
1346
1347if (length $ENV{PERL_ANYEVENT_LOG}) {
1348 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1287} 1349}
1288 1350
1289our @models = ( 1351our @models = (
1290 [EV:: => AnyEvent::Impl::EV:: , 1], 1352 [EV:: => AnyEvent::Impl::EV:: , 1],
1291 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1353 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1],
… …
1301 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1363 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1302 [Wx:: => AnyEvent::Impl::POE::], 1364 [Wx:: => AnyEvent::Impl::POE::],
1303 [Prima:: => AnyEvent::Impl::POE::], 1365 [Prima:: => AnyEvent::Impl::POE::],
1304 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect 1366 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1305 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::], 1367 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1306 [FLTK:: => AnyEvent::Impl::FLTK2::], 1368 [FLTK:: => AnyEvent::Impl::FLTK::],
1307); 1369);
1308 1370
1309our @isa_hook; 1371our @isa_hook;
1310 1372
1311sub _isa_set { 1373sub _isa_set {
… …
1349 1411
1350 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) { 1412 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1351 my $model = $1; 1413 my $model = $1;
1352 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//; 1414 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1353 if (eval "require $model") { 1415 if (eval "require $model") {
1416 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1354 $MODEL = $model; 1417 $MODEL = $model;
1355 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it."
1356 if $VERBOSE >= 7;
1357 } else { 1418 } else {
1358 AnyEvent::log warn => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@"; 1419 AnyEvent::log 4 => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1359 } 1420 }
1360 } 1421 }
1361 1422
1362 # check for already loaded models 1423 # check for already loaded models
1363 unless ($MODEL) { 1424 unless ($MODEL) {
1364 for (@REGISTRY, @models) { 1425 for (@REGISTRY, @models) {
1365 my ($package, $model) = @$_; 1426 my ($package, $model) = @$_;
1366 if (${"$package\::VERSION"} > 0) { 1427 if (${"$package\::VERSION"} > 0) {
1367 if (eval "require $model") { 1428 if (eval "require $model") {
1429 AnyEvent::log 7 => "autodetected model '$model', using it.";
1368 $MODEL = $model; 1430 $MODEL = $model;
1369 AnyEvent::log 7 => "autodetected model '$model', using it."
1370 if $VERBOSE >= 7;
1371 last; 1431 last;
1372 } 1432 }
1373 } 1433 }
1374 } 1434 }
1375 1435
… …
1381 $autoload 1441 $autoload
1382 and eval "require $package" 1442 and eval "require $package"
1383 and ${"$package\::VERSION"} > 0 1443 and ${"$package\::VERSION"} > 0
1384 and eval "require $model" 1444 and eval "require $model"
1385 ) { 1445 ) {
1446 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1386 $MODEL = $model; 1447 $MODEL = $model;
1387 AnyEvent::log 7 => "autoloaded model '$model', using it."
1388 if $VERBOSE >= 7;
1389 last; 1448 last;
1390 } 1449 }
1391 } 1450 }
1392 1451
1393 $MODEL 1452 $MODEL
1394 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?"; 1453 or AnyEvent::log fatal => "AnyEvent: backend autodetection failed - did you properly install AnyEvent?";
1395 } 1454 }
1396 } 1455 }
1397 1456
1398 # free memory only needed for probing 1457 # free memory only needed for probing
1399 undef @models; 1458 undef @models;
… …
1408 if defined &{"$MODEL\::$_"}; 1467 if defined &{"$MODEL\::$_"};
1409 } 1468 }
1410 1469
1411 _isa_set; 1470 _isa_set;
1412 1471
1472 # we're officially open!
1473
1413 if ($ENV{PERL_ANYEVENT_STRICT}) { 1474 if ($ENV{PERL_ANYEVENT_STRICT}) {
1414 require AnyEvent::Strict; 1475 require AnyEvent::Strict;
1415 } 1476 }
1416 1477
1417 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) { 1478 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1418 require AnyEvent::Debug; 1479 require AnyEvent::Debug;
1419 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP}); 1480 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1420 } 1481 }
1421 1482
1422 if (exists $ENV{PERL_ANYEVENT_DEBUG_SHELL}) { 1483 if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1423 require AnyEvent::Socket; 1484 require AnyEvent::Socket;
1424 require AnyEvent::Debug; 1485 require AnyEvent::Debug;
1425 1486
1426 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL}; 1487 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1427 $shell =~ s/\$\$/$$/g; 1488 $shell =~ s/\$\$/$$/g;
1428 1489
1429 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell); 1490 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1430 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service); 1491 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
1431 } 1492 }
1493
1494 # now the anyevent environment is set up as the user told us to, so
1495 # call the actual user code - post detects
1432 1496
1433 (shift @post_detect)->() while @post_detect; 1497 (shift @post_detect)->() while @post_detect;
1434 undef @post_detect; 1498 undef @post_detect;
1435 1499
1436 *post_detect = sub(&) { 1500 *post_detect = sub(&) {
… …
1538 1602
1539sub time { 1603sub time {
1540 eval q{ # poor man's autoloading {} 1604 eval q{ # poor man's autoloading {}
1541 # probe for availability of Time::HiRes 1605 # probe for availability of Time::HiRes
1542 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1606 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1543 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy."
1544 if $AnyEvent::VERBOSE >= 8;
1545 *time = sub { Time::HiRes::time () }; 1607 *time = sub { Time::HiRes::time () };
1546 *AE::time = \& Time::HiRes::time ; 1608 *AE::time = \& Time::HiRes::time ;
1609 *now = \&time;
1610 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy.";
1547 # if (eval "use POSIX (); (POSIX::times())... 1611 # if (eval "use POSIX (); (POSIX::times())...
1548 } else { 1612 } else {
1549 AnyEvent::log critical => "using built-in time(), WARNING, no sub-second resolution!";
1550 *time = sub { CORE::time }; 1613 *time = sub { CORE::time };
1551 *AE::time = sub (){ CORE::time }; 1614 *AE::time = sub (){ CORE::time };
1615 *now = \&time;
1616 AnyEvent::log 3 => "using built-in time(), WARNING, no sub-second resolution!";
1552 } 1617 }
1553
1554 *now = \&time;
1555 }; 1618 };
1556 die if $@; 1619 die if $@;
1557 1620
1558 &time 1621 &time
1559} 1622}
… …
1652 1715
1653sub signal { 1716sub signal {
1654 eval q{ # poor man's autoloading {} 1717 eval q{ # poor man's autoloading {}
1655 # probe for availability of Async::Interrupt 1718 # probe for availability of Async::Interrupt
1656 if (_have_async_interrupt) { 1719 if (_have_async_interrupt) {
1657 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling." 1720 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling.";
1658 if $AnyEvent::VERBOSE >= 8;
1659 1721
1660 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1722 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1661 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1723 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1662 1724
1663 } else { 1725 } else {
1664 AnyEvent::log 8 => "using emulated perl signal handling with latency timer." 1726 AnyEvent::log 8 => "using emulated perl signal handling with latency timer.";
1665 if $AnyEvent::VERBOSE >= 8;
1666 1727
1667 if (AnyEvent::WIN32) { 1728 if (AnyEvent::WIN32) {
1668 require AnyEvent::Util; 1729 require AnyEvent::Util;
1669 1730
1670 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1731 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
… …
1964$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 2025$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1965so on. 2026so on.
1966 2027
1967=head1 ENVIRONMENT VARIABLES 2028=head1 ENVIRONMENT VARIABLES
1968 2029
1969The following environment variables are used by this module or its 2030AnyEvent supports a number of environment variables that tune the
1970submodules. 2031runtime behaviour. They are usually evaluated when AnyEvent is
2032loaded, initialised, or a submodule that uses them is loaded. Many of
2033them also cause AnyEvent to load additional modules - for example,
2034C<PERL_ANYEVENT_DEBUG_WRAP> causes the L<AnyEvent::Debug> module to be
2035loaded.
1971 2036
1972Note that AnyEvent will remove I<all> environment variables starting with 2037All the environment variables documented here start with
1973C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 2038C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1974enabled. 2039namespace. Other modules are encouraged (but by no means required) to use
2040C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
2041namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
2042be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
2043variables starting with C<AE_>, see below).
2044
2045All variables can also be set via the C<AE_> prefix, that is, instead
2046of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
2047case there is a clash btween anyevent and another program that uses
2048C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
2049variable to the empty string, as those variables take precedence.
2050
2051When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
2052to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
2053exists. If taint mode is on, then AnyEvent will remove I<all> environment
2054variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
2055with C<undef> or the empty string, if the corresaponding C<AE_> variable
2056is set).
2057
2058The exact algorithm is currently:
2059
2060 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
2061 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
2062 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
2063
2064This ensures that child processes will not see the C<AE_> variables.
2065
2066The following environment variables are currently known to AnyEvent:
1975 2067
1976=over 4 2068=over 4
1977 2069
1978=item C<PERL_ANYEVENT_VERBOSE> 2070=item C<PERL_ANYEVENT_VERBOSE>
1979 2071
1980By default, AnyEvent will be completely silent except in fatal 2072By default, AnyEvent will only log messages with loglevel C<3>
1981conditions. You can set this environment variable to make AnyEvent more 2073(C<critical>) or higher (see L<AnyEvent::Log>). You can set this
2074environment variable to a numerical loglevel to make AnyEvent more (or
1982talkative. 2075less) talkative.
1983 2076
2077If you want to do more than just set the global logging level
2078you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
2079complex specifications.
2080
2081When set to C<0> (C<off>), then no messages whatsoever will be logged with
2082the default logging settings.
2083
1984When set to C<5> or higher, causes AnyEvent to warn about unexpected 2084When set to C<5> or higher (C<warn>), causes AnyEvent to warn about
1985conditions, such as not being able to load the event model specified by 2085unexpected conditions, such as not being able to load the event model
1986C<PERL_ANYEVENT_MODEL>. 2086specified by C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an
2087exception - this is the minimum recommended level.
1987 2088
1988When set to C<7> or higher, cause AnyEvent to report to STDERR which event 2089When set to C<7> or higher (info), cause AnyEvent to report which event model it
1989model it chooses. 2090chooses.
1990 2091
1991When set to C<8> or higher, then AnyEvent will report extra information on 2092When set to C<8> or higher (debug), then AnyEvent will report extra information on
1992which optional modules it loads and how it implements certain features. 2093which optional modules it loads and how it implements certain features.
2094
2095=item C<PERL_ANYEVENT_LOG>
2096
2097Accepts rather complex logging specifications. For example, you could log
2098all C<debug> messages of some module to stderr, warnings and above to
2099stderr, and errors and above to syslog, with:
2100
2101 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
2102
2103For the rather extensive details, see L<AnyEvent::Log>.
2104
2105This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
2106so will take effect even before AnyEvent has initialised itself.
2107
2108Note that specifying this environment variable causes the L<AnyEvent::Log>
2109module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
2110using the latter saves a few hundred kB of memory until the first message
2111is being logged.
1993 2112
1994=item C<PERL_ANYEVENT_STRICT> 2113=item C<PERL_ANYEVENT_STRICT>
1995 2114
1996AnyEvent does not do much argument checking by default, as thorough 2115AnyEvent does not do much argument checking by default, as thorough
1997argument checking is very costly. Setting this variable to a true value 2116argument checking is very costly. Setting this variable to a true value
… …
2006C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs 2125C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
2007can be very useful, however. 2126can be very useful, however.
2008 2127
2009=item C<PERL_ANYEVENT_DEBUG_SHELL> 2128=item C<PERL_ANYEVENT_DEBUG_SHELL>
2010 2129
2011If this env variable is set, then its contents will be interpreted by 2130If this env variable is nonempty, then its contents will be interpreted by
2012C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of 2131C<AnyEvent::Socket::parse_hostport> and C<AnyEvent::Debug::shell> (after
2013C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on 2132replacing every occurance of C<$$> by the process pid). The shell object
2014that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>. 2133is saved in C<$AnyEvent::Debug::SHELL>.
2015 2134
2016This takes place when the first watcher is created. 2135This happens when the first watcher is created.
2017 2136
2018For example, to bind a debug shell on a unix domain socket in 2137For example, to bind a debug shell on a unix domain socket in
2019F<< /tmp/debug<pid>.sock >>, you could use this: 2138F<< /tmp/debug<pid>.sock >>, you could use this:
2020 2139
2021 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog 2140 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
2141 # connect with e.g.: socat readline /tmp/debug123.sock
2022 2142
2143Or to bind to tcp port 4545 on localhost:
2144
2145 PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
2146 # connect with e.g.: telnet localhost 4545
2147
2023Note that creating sockets in F</tmp> is very unsafe on multiuser 2148Note that creating sockets in F</tmp> or on localhost is very unsafe on
2024systems. 2149multiuser systems.
2025 2150
2026=item C<PERL_ANYEVENT_DEBUG_WRAP> 2151=item C<PERL_ANYEVENT_DEBUG_WRAP>
2027 2152
2028Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for 2153Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for
2029debugging purposes. See C<AnyEvent::Debug::wrap> for details. 2154debugging purposes. See C<AnyEvent::Debug::wrap> for details.
… …
2067but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4> 2192but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
2068- only support IPv4, never try to resolve or contact IPv6 2193- only support IPv4, never try to resolve or contact IPv6
2069addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2194addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
2070IPv6, but prefer IPv6 over IPv4. 2195IPv6, but prefer IPv6 over IPv4.
2071 2196
2197=item C<PERL_ANYEVENT_HOSTS>
2198
2199This variable, if specified, overrides the F</etc/hosts> file used by
2200L<AnyEvent::Socket>C<::resolve_sockaddr>, i.e. hosts aliases will be read
2201from that file instead.
2202
2072=item C<PERL_ANYEVENT_EDNS0> 2203=item C<PERL_ANYEVENT_EDNS0>
2073 2204
2074Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension 2205Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension for
2075for DNS. This extension is generally useful to reduce DNS traffic, but 2206DNS. This extension is generally useful to reduce DNS traffic, especially
2076some (broken) firewalls drop such DNS packets, which is why it is off by 2207when DNSSEC is involved, but some (broken) firewalls drop such DNS
2077default. 2208packets, which is why it is off by default.
2078 2209
2079Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 2210Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
2080EDNS0 in its DNS requests. 2211EDNS0 in its DNS requests.
2081 2212
2082=item C<PERL_ANYEVENT_MAX_FORKS> 2213=item C<PERL_ANYEVENT_MAX_FORKS>
… …
2090resolver - this is the maximum number of parallel DNS requests that are 2221resolver - this is the maximum number of parallel DNS requests that are
2091sent to the DNS server. 2222sent to the DNS server.
2092 2223
2093=item C<PERL_ANYEVENT_RESOLV_CONF> 2224=item C<PERL_ANYEVENT_RESOLV_CONF>
2094 2225
2095The file to use instead of F</etc/resolv.conf> (or OS-specific 2226The absolute path to a F<resolv.conf>-style file to use instead of
2096configuration) in the default resolver. When set to the empty string, no 2227F</etc/resolv.conf> (or the OS-specific configuration) in the default
2097default config will be used. 2228resolver, or the empty string to select the default configuration.
2098 2229
2099=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2230=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
2100 2231
2101When neither C<ca_file> nor C<ca_path> was specified during 2232When neither C<ca_file> nor C<ca_path> was specified during
2102L<AnyEvent::TLS> context creation, and either of these environment 2233L<AnyEvent::TLS> context creation, and either of these environment
2103variables exist, they will be used to specify CA certificate locations 2234variables are nonempty, they will be used to specify CA certificate
2104instead of a system-dependent default. 2235locations instead of a system-dependent default.
2105 2236
2106=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT> 2237=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
2107 2238
2108When these are set to C<1>, then the respective modules are not 2239When these are set to C<1>, then the respective modules are not
2109loaded. Mostly good for testing AnyEvent itself. 2240loaded. Mostly good for testing AnyEvent itself.

Diff Legend

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