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.364 by root, Mon Aug 15 12:56:53 2011 UTC vs.
Revision 1.382 by root, Thu Sep 1 23:46:26 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
… …
1049It should use C<postpone>: 1049It should use C<postpone>:
1050 1050
1051 AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later 1051 AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later
1052 if $some_error_condition; 1052 if $some_error_condition;
1053 1053
1054=item AnyEvent::log $level, $msg[, @args]
1055
1056Log the given C<$msg> at the given C<$level>.
1057
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
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.
1071
1054=back 1072=back
1055 1073
1056=head1 WHAT TO DO IN A MODULE 1074=head1 WHAT TO DO IN A MODULE
1057 1075
1058As a module author, you should C<use AnyEvent> and call AnyEvent methods 1076As a module author, you should C<use AnyEvent> and call AnyEvent methods
… …
1114 1132
1115 1133
1116=head1 OTHER MODULES 1134=head1 OTHER MODULES
1117 1135
1118The following is a non-exhaustive list of additional modules that use 1136The following is a non-exhaustive list of additional modules that use
1119AnyEvent as a client and can therefore be mixed easily with other AnyEvent 1137AnyEvent as a client and can therefore be mixed easily with other
1120modules 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
1121come 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 :)
1122 1143
1123=over 4 1144=over 4
1124 1145
1125=item L<AnyEvent::Util> 1146=item L<AnyEvent::Util>
1126 1147
… …
1146=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>
1147 1168
1148Implement event-based interfaces to the protocols of the same name (for 1169Implement event-based interfaces to the protocols of the same name (for
1149the 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
1150Client Protocol). 1171Client Protocol).
1151
1152=item L<AnyEvent::Handle::UDP>
1153
1154Here be danger!
1155
1156As Pauli would put it, "Not only is it not right, it's not even wrong!" -
1157there are so many things wrong with AnyEvent::Handle::UDP, most notably
1158its use of a stream-based API with a protocol that isn't streamable, that
1159the only way to improve it is to delete it.
1160
1161It features data corruption (but typically only under load) and general
1162confusion. On top, the author is not only clueless about UDP but also
1163fact-resistant - some gems of his understanding: "connect doesn't work
1164with UDP", "UDP packets are not IP packets", "UDP only has datagrams, not
1165packets", "I don't need to implement proper error checking as UDP doesn't
1166support error checking" and so on - he doesn't even understand what's
1167wrong with his module when it is explained to him.
1168
1169=item L<AnyEvent::DBI>
1170
1171Executes L<DBI> requests asynchronously in a proxy process for you,
1172notifying you in an event-based way when the operation is finished.
1173 1172
1174=item L<AnyEvent::AIO> 1173=item L<AnyEvent::AIO>
1175 1174
1176Truly 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
1177toolbox of every event programmer. AnyEvent::AIO transparently fuses 1176toolbox of every event programmer. AnyEvent::AIO transparently fuses
1178L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based 1177L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
1179file I/O, and much more. 1178file I/O, and much more.
1180 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
1181=item L<AnyEvent::HTTPD> 1198=item L<AnyEvent::HTTPD>
1182 1199
1183A simple embedded webserver. 1200A simple embedded webserver.
1184 1201
1185=item L<AnyEvent::FastPing> 1202=item L<AnyEvent::FastPing>
1186 1203
1187The fastest ping in the west. 1204The fastest ping in the west.
1188 1205
1189=item L<Coro> 1206=item L<Coro>
1190 1207
1191Has 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 };
1192 1221
1193=back 1222=back
1194 1223
1195=cut 1224=cut
1196 1225
… …
1206 1235
1207BEGIN { AnyEvent::common_sense } 1236BEGIN { AnyEvent::common_sense }
1208 1237
1209use Carp (); 1238use Carp ();
1210 1239
1211our $VERSION = '6.01'; 1240our $VERSION = '6.02';
1212our $MODEL; 1241our $MODEL;
1213
1214our @ISA; 1242our @ISA;
1215
1216our @REGISTRY; 1243our @REGISTRY;
1217
1218our $VERBOSE; 1244our $VERBOSE;
1245our $MAX_SIGNAL_LATENCY = 10;
1246our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1219 1247
1220BEGIN { 1248BEGIN {
1221 require "AnyEvent/constants.pl"; 1249 require "AnyEvent/constants.pl";
1222 1250
1223 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1251 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1224 1252
1225 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1253 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1226 if ${^TAINT}; 1254 if ${^TAINT};
1227 1255
1228 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1256 $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
1257 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1229 1258
1230} 1259 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1260 if ${^TAINT};
1231 1261
1232our $MAX_SIGNAL_LATENCY = 10; 1262 # $ENV{PERL_ANYEVENT_xxx} now valid
1233 1263
1234our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1264 $VERBOSE = length $ENV{PERL_ANYEVENT_VERBOSE} ? $ENV{PERL_ANYEVENT_VERBOSE}*1 : 3;
1235 1265
1236{
1237 my $idx; 1266 my $idx;
1238 $PROTOCOL{$_} = ++$idx 1267 $PROTOCOL{$_} = ++$idx
1239 for reverse split /\s*,\s*/, 1268 for reverse split /\s*,\s*/,
1240 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1269 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1241} 1270}
… …
1270 push @POSTPONE, shift; 1299 push @POSTPONE, shift;
1271 1300
1272 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec); 1301 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec);
1273 1302
1274 () 1303 ()
1304}
1305
1306sub log($$;@) {
1307 # only load the big bloated module when we actually are about to log something
1308 if ($_[0] <= $VERBOSE) { # also catches non-numeric levels(!)
1309 require AnyEvent::Log;
1310 # AnyEvent::Log overwrites this function
1311 goto &log;
1312 }
1313
1314 0 # not logged
1315}
1316
1317if (length $ENV{PERL_ANYEVENT_LOG}) {
1318 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1275} 1319}
1276 1320
1277our @models = ( 1321our @models = (
1278 [EV:: => AnyEvent::Impl::EV:: , 1], 1322 [EV:: => AnyEvent::Impl::EV:: , 1],
1279 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1323 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1],
… …
1289 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1333 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1290 [Wx:: => AnyEvent::Impl::POE::], 1334 [Wx:: => AnyEvent::Impl::POE::],
1291 [Prima:: => AnyEvent::Impl::POE::], 1335 [Prima:: => AnyEvent::Impl::POE::],
1292 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect 1336 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1293 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::], 1337 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1294 [FLTK:: => AnyEvent::Impl::FLTK2::], 1338 [FLTK:: => AnyEvent::Impl::FLTK::],
1295); 1339);
1296 1340
1297our @isa_hook; 1341our @isa_hook;
1298 1342
1299sub _isa_set { 1343sub _isa_set {
… …
1337 1381
1338 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) { 1382 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1339 my $model = $1; 1383 my $model = $1;
1340 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//; 1384 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1341 if (eval "require $model") { 1385 if (eval "require $model") {
1386 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1342 $MODEL = $model; 1387 $MODEL = $model;
1343 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
1344 } else { 1388 } else {
1345 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE; 1389 AnyEvent::log 5 => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1346 } 1390 }
1347 } 1391 }
1348 1392
1349 # check for already loaded models 1393 # check for already loaded models
1350 unless ($MODEL) { 1394 unless ($MODEL) {
1351 for (@REGISTRY, @models) { 1395 for (@REGISTRY, @models) {
1352 my ($package, $model) = @$_; 1396 my ($package, $model) = @$_;
1353 if (${"$package\::VERSION"} > 0) { 1397 if (${"$package\::VERSION"} > 0) {
1354 if (eval "require $model") { 1398 if (eval "require $model") {
1399 AnyEvent::log 7 => "autodetected model '$model', using it.";
1355 $MODEL = $model; 1400 $MODEL = $model;
1356 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1357 last; 1401 last;
1358 } 1402 }
1359 } 1403 }
1360 } 1404 }
1361 1405
… …
1367 $autoload 1411 $autoload
1368 and eval "require $package" 1412 and eval "require $package"
1369 and ${"$package\::VERSION"} > 0 1413 and ${"$package\::VERSION"} > 0
1370 and eval "require $model" 1414 and eval "require $model"
1371 ) { 1415 ) {
1416 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1372 $MODEL = $model; 1417 $MODEL = $model;
1373 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1374 last; 1418 last;
1375 } 1419 }
1376 } 1420 }
1377 1421
1378 $MODEL 1422 $MODEL
1379 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?\n"; 1423 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?";
1380 } 1424 }
1381 } 1425 }
1382 1426
1383 # free memory only needed for probing 1427 # free memory only needed for probing
1384 undef @models; 1428 undef @models;
… …
1393 if defined &{"$MODEL\::$_"}; 1437 if defined &{"$MODEL\::$_"};
1394 } 1438 }
1395 1439
1396 _isa_set; 1440 _isa_set;
1397 1441
1442 # we're officially open!
1443
1398 if ($ENV{PERL_ANYEVENT_STRICT}) { 1444 if ($ENV{PERL_ANYEVENT_STRICT}) {
1399 require AnyEvent::Strict; 1445 require AnyEvent::Strict;
1400 } 1446 }
1401 1447
1402 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) { 1448 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1403 require AnyEvent::Debug; 1449 require AnyEvent::Debug;
1404 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP}); 1450 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1405 } 1451 }
1406 1452
1407 if (exists $ENV{PERL_ANYEVENT_DEBUG_SHELL}) { 1453 if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1408 require AnyEvent::Socket; 1454 require AnyEvent::Socket;
1409 require AnyEvent::Debug; 1455 require AnyEvent::Debug;
1410 1456
1411 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL}; 1457 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1412 $shell =~ s/\$\$/$$/g; 1458 $shell =~ s/\$\$/$$/g;
1413 1459
1414 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell); 1460 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1415 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service); 1461 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
1416 } 1462 }
1463
1464 # now the anyevent environment is set up as the user told us to, so
1465 # call the actual user code - post detects
1417 1466
1418 (shift @post_detect)->() while @post_detect; 1467 (shift @post_detect)->() while @post_detect;
1419 undef @post_detect; 1468 undef @post_detect;
1420 1469
1421 *post_detect = sub(&) { 1470 *post_detect = sub(&) {
… …
1508 sub time() { 1557 sub time() {
1509 AnyEvent->time 1558 AnyEvent->time
1510 } 1559 }
1511 1560
1512 *postpone = \&AnyEvent::postpone; 1561 *postpone = \&AnyEvent::postpone;
1562 *log = \&AnyEvent::log;
1513 }; 1563 };
1514 die if $@; 1564 die if $@;
1515} 1565}
1516 1566
1517BEGIN { _reset } 1567BEGIN { _reset }
… …
1522 1572
1523sub time { 1573sub time {
1524 eval q{ # poor man's autoloading {} 1574 eval q{ # poor man's autoloading {}
1525 # probe for availability of Time::HiRes 1575 # probe for availability of Time::HiRes
1526 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1576 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1527 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8;
1528 *time = sub { Time::HiRes::time () }; 1577 *time = sub { Time::HiRes::time () };
1529 *AE::time = \& Time::HiRes::time ; 1578 *AE::time = \& Time::HiRes::time ;
1579 *now = \&time;
1580 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy.";
1530 # if (eval "use POSIX (); (POSIX::times())... 1581 # if (eval "use POSIX (); (POSIX::times())...
1531 } else { 1582 } else {
1532 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE;
1533 *time = sub { CORE::time }; 1583 *time = sub { CORE::time };
1534 *AE::time = sub (){ CORE::time }; 1584 *AE::time = sub (){ CORE::time };
1585 *now = \&time;
1586 AnyEvent::log 3 => "using built-in time(), WARNING, no sub-second resolution!";
1535 } 1587 }
1536
1537 *now = \&time;
1538 }; 1588 };
1539 die if $@; 1589 die if $@;
1540 1590
1541 &time 1591 &time
1542} 1592}
… …
1635 1685
1636sub signal { 1686sub signal {
1637 eval q{ # poor man's autoloading {} 1687 eval q{ # poor man's autoloading {}
1638 # probe for availability of Async::Interrupt 1688 # probe for availability of Async::Interrupt
1639 if (_have_async_interrupt) { 1689 if (_have_async_interrupt) {
1640 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8; 1690 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling.";
1641 1691
1642 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1692 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1643 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1693 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1644 1694
1645 } else { 1695 } else {
1646 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8; 1696 AnyEvent::log 8 => "using emulated perl signal handling with latency timer.";
1647 1697
1648 if (AnyEvent::WIN32) { 1698 if (AnyEvent::WIN32) {
1649 require AnyEvent::Util; 1699 require AnyEvent::Util;
1650 1700
1651 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1701 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
… …
1945$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 1995$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1946so on. 1996so on.
1947 1997
1948=head1 ENVIRONMENT VARIABLES 1998=head1 ENVIRONMENT VARIABLES
1949 1999
1950The following environment variables are used by this module or its 2000AnyEvent supports a number of environment variables that tune the
1951submodules. 2001runtime behaviour. They are usually evaluated when AnyEvent is
2002loaded, initialised, or a submodule that uses them is loaded. Many of
2003them also cause AnyEvent to load additional modules - for example,
2004C<PERL_ANYEVENT_DEBUG_WRAP> causes the L<AnyEvent::Debug> module to be
2005loaded.
1952 2006
1953Note that AnyEvent will remove I<all> environment variables starting with 2007All the environment variables documented here start with
1954C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 2008C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1955enabled. 2009namespace. Other modules are encouraged (but by no means required) to use
2010C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
2011namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
2012be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
2013variables starting with C<AE_>, see below).
2014
2015All variables can also be set via the C<AE_> prefix, that is, instead
2016of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
2017case there is a clash btween anyevent and another program that uses
2018C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
2019variable to the empty string, as those variables take precedence.
2020
2021When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
2022to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
2023exists. If taint mode is on, then AnyEvent will remove I<all> environment
2024variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
2025with C<undef> or the empty string, if the corresaponding C<AE_> variable
2026is set).
2027
2028The exact algorithm is currently:
2029
2030 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
2031 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
2032 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
2033
2034This ensures that child processes will not see the C<AE_> variables.
2035
2036The following environment variables are currently known to AnyEvent:
1956 2037
1957=over 4 2038=over 4
1958 2039
1959=item C<PERL_ANYEVENT_VERBOSE> 2040=item C<PERL_ANYEVENT_VERBOSE>
1960 2041
1961By default, AnyEvent will be completely silent except in fatal 2042By default, AnyEvent will only log messages with loglevel C<3>
1962conditions. You can set this environment variable to make AnyEvent more 2043(C<critical>) or higher (see L<AnyEvent::Log>). You can set this
2044environment variable to a numerical loglevel to make AnyEvent more (or
1963talkative. 2045less) talkative.
1964 2046
2047If you want to do more than just set the global logging level
2048you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
2049complex specifications.
2050
2051When set to C<0> (C<off>), then no messages whatsoever will be logged with
2052the default logging settings.
2053
1965When set to C<1> or higher, causes AnyEvent to warn about unexpected 2054When set to C<5> or higher (C<warn>), causes AnyEvent to warn about
1966conditions, such as not being able to load the event model specified by 2055unexpected conditions, such as not being able to load the event model
1967C<PERL_ANYEVENT_MODEL>. 2056specified by C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an
2057exception - this is the minimum recommended level.
1968 2058
1969When set to C<2> or higher, cause AnyEvent to report to STDERR which event 2059When set to C<7> or higher (info), cause AnyEvent to report which event model it
1970model it chooses. 2060chooses.
1971 2061
1972When set to C<8> or higher, then AnyEvent will report extra information on 2062When set to C<8> or higher (debug), then AnyEvent will report extra information on
1973which optional modules it loads and how it implements certain features. 2063which optional modules it loads and how it implements certain features.
2064
2065=item C<PERL_ANYEVENT_LOG>
2066
2067Accepts rather complex logging specifications. For example, you could log
2068all C<debug> messages of some module to stderr, warnings and above to
2069stderr, and errors and above to syslog, with:
2070
2071 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
2072
2073For the rather extensive details, see L<AnyEvent::Log>.
2074
2075This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
2076so will take effect even before AnyEvent has initialised itself.
2077
2078Note that specifying this environment variable causes the L<AnyEvent::Log>
2079module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
2080using the latter saves a few hundred kB of memory until the first message
2081is being logged.
1974 2082
1975=item C<PERL_ANYEVENT_STRICT> 2083=item C<PERL_ANYEVENT_STRICT>
1976 2084
1977AnyEvent does not do much argument checking by default, as thorough 2085AnyEvent does not do much argument checking by default, as thorough
1978argument checking is very costly. Setting this variable to a true value 2086argument checking is very costly. Setting this variable to a true value
… …
1992If this env variable is set, then its contents will be interpreted by 2100If this env variable is set, then its contents will be interpreted by
1993C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of 2101C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of
1994C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on 2102C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on
1995that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>. 2103that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>.
1996 2104
1997This takes place when the first watcher is created. 2105This happens when the first watcher is created.
1998 2106
1999For example, to bind a debug shell on a unix domain socket in 2107For example, to bind a debug shell on a unix domain socket in
2000F<< /tmp/debug<pid>.sock >>, you could use this: 2108F<< /tmp/debug<pid>.sock >>, you could use this:
2001 2109
2002 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog 2110 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
… …
2048but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4> 2156but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
2049- only support IPv4, never try to resolve or contact IPv6 2157- only support IPv4, never try to resolve or contact IPv6
2050addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2158addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
2051IPv6, but prefer IPv6 over IPv4. 2159IPv6, but prefer IPv6 over IPv4.
2052 2160
2161=item C<PERL_ANYEVENT_HOSTS>
2162
2163This variable, if specified, overrides the F</etc/hosts> file used by
2164L<AnyEvent::Socket>C<::resolve_sockaddr>, i.e. hosts aliases will be read
2165from that file instead.
2166
2053=item C<PERL_ANYEVENT_EDNS0> 2167=item C<PERL_ANYEVENT_EDNS0>
2054 2168
2055Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension 2169Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension for
2056for DNS. This extension is generally useful to reduce DNS traffic, but 2170DNS. This extension is generally useful to reduce DNS traffic, especially
2057some (broken) firewalls drop such DNS packets, which is why it is off by 2171when DNSSEC is involved, but some (broken) firewalls drop such DNS
2058default. 2172packets, which is why it is off by default.
2059 2173
2060Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 2174Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
2061EDNS0 in its DNS requests. 2175EDNS0 in its DNS requests.
2062 2176
2063=item C<PERL_ANYEVENT_MAX_FORKS> 2177=item C<PERL_ANYEVENT_MAX_FORKS>
… …
2071resolver - this is the maximum number of parallel DNS requests that are 2185resolver - this is the maximum number of parallel DNS requests that are
2072sent to the DNS server. 2186sent to the DNS server.
2073 2187
2074=item C<PERL_ANYEVENT_RESOLV_CONF> 2188=item C<PERL_ANYEVENT_RESOLV_CONF>
2075 2189
2076The file to use instead of F</etc/resolv.conf> (or OS-specific 2190The absolute path to a F<resolv.conf>-style file to use instead of
2077configuration) in the default resolver. When set to the empty string, no 2191F</etc/resolv.conf> (or the OS-specific configuration) in the default
2078default config will be used. 2192resolver, or the empty string to select the default configuration.
2079 2193
2080=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2194=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
2081 2195
2082When neither C<ca_file> nor C<ca_path> was specified during 2196When neither C<ca_file> nor C<ca_path> was specified during
2083L<AnyEvent::TLS> context creation, and either of these environment 2197L<AnyEvent::TLS> context creation, and either of these environment
2084variables exist, they will be used to specify CA certificate locations 2198variables are nonempty, they will be used to specify CA certificate
2085instead of a system-dependent default. 2199locations instead of a system-dependent default.
2086 2200
2087=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT> 2201=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
2088 2202
2089When these are set to C<1>, then the respective modules are not 2203When these are set to C<1>, then the respective modules are not
2090loaded. Mostly good for testing AnyEvent itself. 2204loaded. Mostly good for testing AnyEvent itself.
… …
2807 2921
2808Tutorial/Introduction: L<AnyEvent::Intro>. 2922Tutorial/Introduction: L<AnyEvent::Intro>.
2809 2923
2810FAQ: L<AnyEvent::FAQ>. 2924FAQ: L<AnyEvent::FAQ>.
2811 2925
2812Utility functions: L<AnyEvent::Util>. 2926Utility functions: L<AnyEvent::Util> (misc. grab-bag), L<AnyEvent::Log>
2927(simply logging).
2813 2928
2929Development/Debugging: L<AnyEvent::Strict> (stricter checking),
2930L<AnyEvent::Debug> (interactive shell, watcher tracing).
2931
2814Event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>, L<Glib::EV>, 2932Supported event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>,
2815L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2933L<Glib::EV>, L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>,
2934L<Qt>, L<POE>, L<FLTK>.
2816 2935
2817Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2936Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2818L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2937L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2819L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2938L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2820L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>. 2939L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>,
2940L<AnyEvent::Impl::FLTK>.
2821 2941
2822Non-blocking file handles, sockets, TCP clients and 2942Non-blocking handles, pipes, stream sockets, TCP clients and
2823servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2943servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2824 2944
2825Asynchronous DNS: L<AnyEvent::DNS>. 2945Asynchronous DNS: L<AnyEvent::DNS>.
2826 2946
2827Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>. 2947Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.

Diff Legend

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