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.360 by root, Sat Aug 13 22:44:05 2011 UTC vs.
Revision 1.379 by root, Fri Aug 26 18:09:04 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.
1064
1065If you want to sprinkle loads of logging calls around your code, consider
1066creating a logger callback with the C<AnyEvent::Log::logger> function,
1067which can reduce typing, codesize and can reduce the logging overhead
1068enourmously.
1069
1054=back 1070=back
1055 1071
1056=head1 WHAT TO DO IN A MODULE 1072=head1 WHAT TO DO IN A MODULE
1057 1073
1058As a module author, you should C<use AnyEvent> and call AnyEvent methods 1074As a module author, you should C<use AnyEvent> and call AnyEvent methods
… …
1114 1130
1115 1131
1116=head1 OTHER MODULES 1132=head1 OTHER MODULES
1117 1133
1118The following is a non-exhaustive list of additional modules that use 1134The following is a non-exhaustive list of additional modules that use
1119AnyEvent as a client and can therefore be mixed easily with other AnyEvent 1135AnyEvent as a client and can therefore be mixed easily with other
1120modules and other event loops in the same program. Some of the modules 1136AnyEvent modules and other event loops in the same program. Some of the
1121come as part of AnyEvent, the others are available via CPAN. 1137modules come as part of AnyEvent, the others are available via CPAN (see
1138L<http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for
1139a longer non-exhaustive list), and the list is heavily biased towards
1140modules of the AnyEvent author himself :)
1122 1141
1123=over 4 1142=over 4
1124 1143
1125=item L<AnyEvent::Util> 1144=item L<AnyEvent::Util>
1126 1145
… …
1146=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP> 1165=item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP>
1147 1166
1148Implement event-based interfaces to the protocols of the same name (for 1167Implement event-based interfaces to the protocols of the same name (for
1149the 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
1150Client Protocol). 1169Client 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 1170
1174=item L<AnyEvent::AIO> 1171=item L<AnyEvent::AIO>
1175 1172
1176Truly 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
1177toolbox of every event programmer. AnyEvent::AIO transparently fuses 1174toolbox of every event programmer. AnyEvent::AIO transparently fuses
1178L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based 1175L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
1179file I/O, and much more. 1176file I/O, and much more.
1180 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
1181=item L<AnyEvent::HTTPD> 1196=item L<AnyEvent::HTTPD>
1182 1197
1183A simple embedded webserver. 1198A simple embedded webserver.
1184 1199
1185=item L<AnyEvent::FastPing> 1200=item L<AnyEvent::FastPing>
1186 1201
1187The fastest ping in the west. 1202The fastest ping in the west.
1188 1203
1189=item L<Coro> 1204=item L<Coro>
1190 1205
1191Has 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 };
1192 1219
1193=back 1220=back
1194 1221
1195=cut 1222=cut
1196 1223
… …
1206 1233
1207BEGIN { AnyEvent::common_sense } 1234BEGIN { AnyEvent::common_sense }
1208 1235
1209use Carp (); 1236use Carp ();
1210 1237
1211our $VERSION = '6.0'; 1238our $VERSION = '6.02';
1212our $MODEL; 1239our $MODEL;
1213 1240
1214our @ISA; 1241our @ISA;
1215 1242
1216our @REGISTRY; 1243our @REGISTRY;
… …
1223 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1250 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1224 1251
1225 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1252 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1226 if ${^TAINT}; 1253 if ${^TAINT};
1227 1254
1255 $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
1256 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1257
1258 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1259 if ${^TAINT};
1260
1228 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1261 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
1229
1230} 1262}
1231 1263
1232our $MAX_SIGNAL_LATENCY = 10; 1264our $MAX_SIGNAL_LATENCY = 10;
1233 1265
1234our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1266our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
… …
1270 push @POSTPONE, shift; 1302 push @POSTPONE, shift;
1271 1303
1272 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec); 1304 $POSTPONE_W ||= AE::timer (0, 0, \&_postpone_exec);
1273 1305
1274 () 1306 ()
1307}
1308
1309sub log($$;@) {
1310 # only load the big bloated module when we actually are about to log something
1311 if ($_[0] <= $VERBOSE) { # also catches non-numeric levels(!)
1312 require AnyEvent::Log;
1313 # AnyEvent::Log overwrites this function
1314 goto &log;
1315 }
1316
1317 0 # not logged
1318}
1319
1320if (length $ENV{PERL_ANYEVENT_LOG}) {
1321 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1275} 1322}
1276 1323
1277our @models = ( 1324our @models = (
1278 [EV:: => AnyEvent::Impl::EV:: , 1], 1325 [EV:: => AnyEvent::Impl::EV:: , 1],
1279 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1326 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1],
… …
1289 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1336 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1290 [Wx:: => AnyEvent::Impl::POE::], 1337 [Wx:: => AnyEvent::Impl::POE::],
1291 [Prima:: => AnyEvent::Impl::POE::], 1338 [Prima:: => AnyEvent::Impl::POE::],
1292 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect 1339 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1293 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::], 1340 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1294 [FLTK:: => AnyEvent::Impl::FLTK2::], 1341 [FLTK:: => AnyEvent::Impl::FLTK::],
1295); 1342);
1343
1344our @isa_hook;
1345
1346sub _isa_set {
1347 my @pkg = ("AnyEvent", (map $_->[0], grep defined, @isa_hook), $MODEL);
1348
1349 @{"$pkg[$_-1]::ISA"} = $pkg[$_]
1350 for 1 .. $#pkg;
1351
1352 grep $_ && $_->[1], @isa_hook
1353 and AE::_reset ();
1354}
1355
1356# used for hooking AnyEvent::Strict and AnyEvent::Debug::Wrap into the class hierarchy
1357sub _isa_hook($$;$) {
1358 my ($i, $pkg, $reset_ae) = @_;
1359
1360 $isa_hook[$i] = $pkg ? [$pkg, $reset_ae] : undef;
1361
1362 _isa_set;
1363}
1296 1364
1297# all autoloaded methods reserve the complete glob, not just the method slot. 1365# all autoloaded methods reserve the complete glob, not just the method slot.
1298# due to bugs in perls method cache implementation. 1366# due to bugs in perls method cache implementation.
1299our @methods = qw(io timer time now now_update signal child idle condvar); 1367our @methods = qw(io timer time now now_update signal child idle condvar);
1300 1368
1301sub detect() { 1369sub detect() {
1370 return $MODEL if $MODEL; # some programs keep references to detect
1371
1302 local $!; # for good measure 1372 local $!; # for good measure
1303 local $SIG{__DIE__}; # we use eval 1373 local $SIG{__DIE__}; # we use eval
1304 1374
1305 # free some memory 1375 # free some memory
1306 *detect = sub () { $MODEL }; 1376 *detect = sub () { $MODEL };
… …
1314 1384
1315 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) { 1385 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1316 my $model = $1; 1386 my $model = $1;
1317 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//; 1387 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1318 if (eval "require $model") { 1388 if (eval "require $model") {
1389 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1319 $MODEL = $model; 1390 $MODEL = $model;
1320 warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $VERBOSE >= 2;
1321 } else { 1391 } else {
1322 warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $VERBOSE; 1392 AnyEvent::log 5 => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1323 } 1393 }
1324 } 1394 }
1325 1395
1326 # check for already loaded models 1396 # check for already loaded models
1327 unless ($MODEL) { 1397 unless ($MODEL) {
1328 for (@REGISTRY, @models) { 1398 for (@REGISTRY, @models) {
1329 my ($package, $model) = @$_; 1399 my ($package, $model) = @$_;
1330 if (${"$package\::VERSION"} > 0) { 1400 if (${"$package\::VERSION"} > 0) {
1331 if (eval "require $model") { 1401 if (eval "require $model") {
1402 AnyEvent::log 7 => "autodetected model '$model', using it.";
1332 $MODEL = $model; 1403 $MODEL = $model;
1333 warn "AnyEvent: autodetected model '$model', using it.\n" if $VERBOSE >= 2;
1334 last; 1404 last;
1335 } 1405 }
1336 } 1406 }
1337 } 1407 }
1338 1408
… …
1344 $autoload 1414 $autoload
1345 and eval "require $package" 1415 and eval "require $package"
1346 and ${"$package\::VERSION"} > 0 1416 and ${"$package\::VERSION"} > 0
1347 and eval "require $model" 1417 and eval "require $model"
1348 ) { 1418 ) {
1419 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1349 $MODEL = $model; 1420 $MODEL = $model;
1350 warn "AnyEvent: autoloaded model '$model', using it.\n" if $VERBOSE >= 2;
1351 last; 1421 last;
1352 } 1422 }
1353 } 1423 }
1354 1424
1355 $MODEL 1425 $MODEL
1356 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?\n"; 1426 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?";
1357 } 1427 }
1358 } 1428 }
1359 1429
1360 # free memory only needed for probing 1430 # free memory only needed for probing
1361 undef @models; 1431 undef @models;
1362 undef @REGISTRY; 1432 undef @REGISTRY;
1363 1433
1364 push @{"$MODEL\::ISA"}, "AnyEvent::Base"; 1434 push @{"$MODEL\::ISA"}, "AnyEvent::Base";
1365 unshift @ISA, $MODEL;
1366 1435
1367 # now nuke some methods that are overridden by the backend. 1436 # now nuke some methods that are overridden by the backend.
1368 # SUPER usage is not allowed in these. 1437 # SUPER usage is not allowed in these.
1369 for (qw(time signal child idle)) { 1438 for (qw(time signal child idle)) {
1370 undef &{"AnyEvent::Base::$_"} 1439 undef &{"AnyEvent::Base::$_"}
1371 if defined &{"$MODEL\::$_"}; 1440 if defined &{"$MODEL\::$_"};
1372 } 1441 }
1373 1442
1443 _isa_set;
1444
1445 # we're officially open!
1446
1374 if ($ENV{PERL_ANYEVENT_STRICT}) { 1447 if ($ENV{PERL_ANYEVENT_STRICT}) {
1375 require AnyEvent::Strict; 1448 require AnyEvent::Strict;
1376 } 1449 }
1377 1450
1378 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) { 1451 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1379 require AnyEvent::Debug; 1452 require AnyEvent::Debug;
1380 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP}); 1453 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1381 } 1454 }
1382 1455
1383 if (exists $ENV{PERL_ANYEVENT_DEBUG_SHELL}) { 1456 if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1384 require AnyEvent::Socket; 1457 require AnyEvent::Socket;
1385 require AnyEvent::Debug; 1458 require AnyEvent::Debug;
1386 1459
1387 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL}; 1460 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1388 $shell =~ s/\$\$/$$/g; 1461 $shell =~ s/\$\$/$$/g;
1389 1462
1390 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell); 1463 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1391 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service); 1464 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
1392 } 1465 }
1466
1467 # now the anyevent environment is set up as the user told us to, so
1468 # call the actual user code - post detects
1393 1469
1394 (shift @post_detect)->() while @post_detect; 1470 (shift @post_detect)->() while @post_detect;
1395 undef @post_detect; 1471 undef @post_detect;
1396 1472
1397 *post_detect = sub(&) { 1473 *post_detect = sub(&) {
… …
1484 sub time() { 1560 sub time() {
1485 AnyEvent->time 1561 AnyEvent->time
1486 } 1562 }
1487 1563
1488 *postpone = \&AnyEvent::postpone; 1564 *postpone = \&AnyEvent::postpone;
1565 *log = \&AnyEvent::log;
1489 }; 1566 };
1490 die if $@; 1567 die if $@;
1491} 1568}
1492 1569
1493BEGIN { _reset } 1570BEGIN { _reset }
… …
1498 1575
1499sub time { 1576sub time {
1500 eval q{ # poor man's autoloading {} 1577 eval q{ # poor man's autoloading {}
1501 # probe for availability of Time::HiRes 1578 # probe for availability of Time::HiRes
1502 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1579 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
1503 warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8; 1580 *time = sub { Time::HiRes::time () };
1504 *AE::time = \&Time::HiRes::time; 1581 *AE::time = \& Time::HiRes::time ;
1582 *now = \&time;
1583 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy.";
1505 # if (eval "use POSIX (); (POSIX::times())... 1584 # if (eval "use POSIX (); (POSIX::times())...
1506 } else { 1585 } else {
1586 *time = sub { CORE::time };
1587 *AE::time = sub (){ CORE::time };
1588 *now = \&time;
1507 warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE; 1589 AnyEvent::log 3 => "using built-in time(), WARNING, no sub-second resolution!";
1508 *AE::time = sub (){ time }; # epic fail
1509 } 1590 }
1510
1511 *time = sub { AE::time }; # different prototypes
1512 }; 1591 };
1513 die if $@; 1592 die if $@;
1514 1593
1515 &time 1594 &time
1516} 1595}
1517 1596
1518*now = \&time; 1597*now = \&time;
1519
1520sub now_update { } 1598sub now_update { }
1521 1599
1522sub _poll { 1600sub _poll {
1523 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught"; 1601 Carp::croak "$AnyEvent::MODEL does not support blocking waits. Caught";
1524} 1602}
… …
1610 1688
1611sub signal { 1689sub signal {
1612 eval q{ # poor man's autoloading {} 1690 eval q{ # poor man's autoloading {}
1613 # probe for availability of Async::Interrupt 1691 # probe for availability of Async::Interrupt
1614 if (_have_async_interrupt) { 1692 if (_have_async_interrupt) {
1615 warn "AnyEvent: using Async::Interrupt for race-free signal handling.\n" if $VERBOSE >= 8; 1693 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling.";
1616 1694
1617 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1695 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1618 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1696 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1619 1697
1620 } else { 1698 } else {
1621 warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8; 1699 AnyEvent::log 8 => "using emulated perl signal handling with latency timer.";
1622 1700
1623 if (AnyEvent::WIN32) { 1701 if (AnyEvent::WIN32) {
1624 require AnyEvent::Util; 1702 require AnyEvent::Util;
1625 1703
1626 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1704 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
… …
1920$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 1998$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1921so on. 1999so on.
1922 2000
1923=head1 ENVIRONMENT VARIABLES 2001=head1 ENVIRONMENT VARIABLES
1924 2002
1925The following environment variables are used by this module or its 2003AnyEvent supports a number of environment variables that tune the
1926submodules. 2004runtime behaviour. They are usually evaluated when AnyEvent is
2005loaded, initialised, or a submodule that uses them is loaded. Many of
2006them also cause AnyEvent to load additional modules - for example,
2007C<PERL_ANYEVENT_DEBUG_WRAP> causes the L<AnyEvent::Debug> module to be
2008loaded.
1927 2009
1928Note that AnyEvent will remove I<all> environment variables starting with 2010All the environment variables documented here start with
1929C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 2011C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1930enabled. 2012namespace. Other modules are encouraged (but by no means required) to use
2013C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
2014namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
2015be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
2016variables starting with C<AE_>, see below).
2017
2018All variables can also be set via the C<AE_> prefix, that is, instead
2019of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
2020case there is a clash btween anyevent and another program that uses
2021C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
2022variable to the empty string, as those variables take precedence.
2023
2024When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
2025to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
2026exists. If taint mode is on, then AnyEvent will remove I<all> environment
2027variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
2028with C<undef> or the empty string, if the corresaponding C<AE_> variable
2029is set).
2030
2031The exact algorithm is currently:
2032
2033 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
2034 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
2035 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
2036
2037This ensures that child processes will not see the C<AE_> variables.
2038
2039The following environment variables are currently known to AnyEvent:
1931 2040
1932=over 4 2041=over 4
1933 2042
1934=item C<PERL_ANYEVENT_VERBOSE> 2043=item C<PERL_ANYEVENT_VERBOSE>
1935 2044
1936By default, AnyEvent will be completely silent except in fatal 2045By default, AnyEvent will be completely silent except in fatal
1937conditions. You can set this environment variable to make AnyEvent more 2046conditions. You can set this environment variable to make AnyEvent more
1938talkative. 2047talkative. If 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.
1939 2050
1940When set to C<1> or higher, causes AnyEvent to warn about unexpected 2051When set to C<5> or higher (warn), causes AnyEvent to warn about unexpected
1941conditions, such as not being able to load the event model specified by 2052conditions, such as not being able to load the event model specified by
1942C<PERL_ANYEVENT_MODEL>. 2053C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an exception - this
2054is the minimum recommended level.
1943 2055
1944When set to C<2> or higher, cause AnyEvent to report to STDERR which event 2056When set to C<7> or higher (info), cause AnyEvent to report which event model it
1945model it chooses. 2057chooses.
1946 2058
1947When set to C<8> or higher, then AnyEvent will report extra information on 2059When set to C<8> or higher (debug), then AnyEvent will report extra information on
1948which optional modules it loads and how it implements certain features. 2060which optional modules it loads and how it implements certain features.
2061
2062=item C<PERL_ANYEVENT_LOG>
2063
2064Accepts rather complex logging specifications. For example, you could log
2065all C<debug> messages of some module to stderr, warnings and above to
2066stderr, and errors and above to syslog, with:
2067
2068 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
2069
2070For the rather extensive details, see L<AnyEvent::Log>.
2071
2072This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
2073so will take effect even before AnyEvent has initialised itself.
2074
2075Note that specifying this environment variable causes the L<AnyEvent::Log>
2076module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
2077using the latter saves a few hundred kB of memory until the first message
2078is being logged.
1949 2079
1950=item C<PERL_ANYEVENT_STRICT> 2080=item C<PERL_ANYEVENT_STRICT>
1951 2081
1952AnyEvent does not do much argument checking by default, as thorough 2082AnyEvent does not do much argument checking by default, as thorough
1953argument checking is very costly. Setting this variable to a true value 2083argument checking is very costly. Setting this variable to a true value
… …
1967If this env variable is set, then its contents will be interpreted by 2097If this env variable is set, then its contents will be interpreted by
1968C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of 2098C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of
1969C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on 2099C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on
1970that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>. 2100that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>.
1971 2101
1972This takes place when the first watcher is created. 2102This happens when the first watcher is created.
1973 2103
1974For example, to bind a debug shell on a unix domain socket in 2104For example, to bind a debug shell on a unix domain socket in
1975F<< /tmp/debug<pid>.sock >>, you could use this: 2105F<< /tmp/debug<pid>.sock >>, you could use this:
1976 2106
1977 PERL_ANYEVENT_DEBUG_SHELL=unix/:/tmp/debug\$\$.sock perlprog 2107 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
1978 2108
1979Note that creating sockets in F</tmp> is very unsafe on multiuser 2109Note that creating sockets in F</tmp> is very unsafe on multiuser
1980systems. 2110systems.
1981 2111
1982=item C<PERL_ANYEVENT_DEBUG_WRAP> 2112=item C<PERL_ANYEVENT_DEBUG_WRAP>
… …
2023but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4> 2153but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
2024- only support IPv4, never try to resolve or contact IPv6 2154- only support IPv4, never try to resolve or contact IPv6
2025addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2155addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
2026IPv6, but prefer IPv6 over IPv4. 2156IPv6, but prefer IPv6 over IPv4.
2027 2157
2158=item C<PERL_ANYEVENT_HOSTS>
2159
2160This variable, if specified, overrides the F</etc/hosts> file used by
2161L<AnyEvent::Socket>C<::resolve_sockaddr>, i.e. hosts aliases will be read
2162from that file instead.
2163
2028=item C<PERL_ANYEVENT_EDNS0> 2164=item C<PERL_ANYEVENT_EDNS0>
2029 2165
2030Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension 2166Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension for
2031for DNS. This extension is generally useful to reduce DNS traffic, but 2167DNS. This extension is generally useful to reduce DNS traffic, especially
2032some (broken) firewalls drop such DNS packets, which is why it is off by 2168when DNSSEC is involved, but some (broken) firewalls drop such DNS
2033default. 2169packets, which is why it is off by default.
2034 2170
2035Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 2171Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
2036EDNS0 in its DNS requests. 2172EDNS0 in its DNS requests.
2037 2173
2038=item C<PERL_ANYEVENT_MAX_FORKS> 2174=item C<PERL_ANYEVENT_MAX_FORKS>
… …
2046resolver - this is the maximum number of parallel DNS requests that are 2182resolver - this is the maximum number of parallel DNS requests that are
2047sent to the DNS server. 2183sent to the DNS server.
2048 2184
2049=item C<PERL_ANYEVENT_RESOLV_CONF> 2185=item C<PERL_ANYEVENT_RESOLV_CONF>
2050 2186
2051The file to use instead of F</etc/resolv.conf> (or OS-specific 2187The absolute path to a F<resolv.conf>-style file to use instead of
2052configuration) in the default resolver. When set to the empty string, no 2188F</etc/resolv.conf> (or the OS-specific configuration) in the default
2053default config will be used. 2189resolver, or the empty string to select the default configuration.
2054 2190
2055=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2191=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
2056 2192
2057When neither C<ca_file> nor C<ca_path> was specified during 2193When neither C<ca_file> nor C<ca_path> was specified during
2058L<AnyEvent::TLS> context creation, and either of these environment 2194L<AnyEvent::TLS> context creation, and either of these environment
2059variables exist, they will be used to specify CA certificate locations 2195variables are nonempty, they will be used to specify CA certificate
2060instead of a system-dependent default. 2196locations instead of a system-dependent default.
2061 2197
2062=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT> 2198=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
2063 2199
2064When these are set to C<1>, then the respective modules are not 2200When these are set to C<1>, then the respective modules are not
2065loaded. Mostly good for testing AnyEvent itself. 2201loaded. Mostly good for testing AnyEvent itself.
… …
2397(even when used without AnyEvent), but most event loops have acceptable 2533(even when used without AnyEvent), but most event loops have acceptable
2398performance with or without AnyEvent. 2534performance with or without AnyEvent.
2399 2535
2400=item * The overhead AnyEvent adds is usually much smaller than the overhead of 2536=item * The overhead AnyEvent adds is usually much smaller than the overhead of
2401the actual event loop, only with extremely fast event loops such as EV 2537the actual event loop, only with extremely fast event loops such as EV
2402adds AnyEvent significant overhead. 2538does AnyEvent add significant overhead.
2403 2539
2404=item * You should avoid POE like the plague if you want performance or 2540=item * You should avoid POE like the plague if you want performance or
2405reasonable memory usage. 2541reasonable memory usage.
2406 2542
2407=back 2543=back
… …
2782 2918
2783Tutorial/Introduction: L<AnyEvent::Intro>. 2919Tutorial/Introduction: L<AnyEvent::Intro>.
2784 2920
2785FAQ: L<AnyEvent::FAQ>. 2921FAQ: L<AnyEvent::FAQ>.
2786 2922
2787Utility functions: L<AnyEvent::Util>. 2923Utility functions: L<AnyEvent::Util> (misc. grab-bag), L<AnyEvent::Log>
2924(simply logging).
2788 2925
2926Development/Debugging: L<AnyEvent::Strict> (stricter checking),
2927L<AnyEvent::Debug> (interactive shell, watcher tracing).
2928
2789Event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>, L<Glib::EV>, 2929Supported event modules: L<AnyEvent::Loop>, L<EV>, L<EV::Glib>,
2790L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2930L<Glib::EV>, L<Event>, L<Glib::Event>, L<Glib>, L<Tk>, L<Event::Lib>,
2931L<Qt>, L<POE>, L<FLTK>.
2791 2932
2792Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2933Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2793L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2934L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2794L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2935L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2795L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>. 2936L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>, L<Anyevent::Impl::Irssi>,
2937L<AnyEvent::Impl::FLTK>.
2796 2938
2797Non-blocking file handles, sockets, TCP clients and 2939Non-blocking handles, pipes, stream sockets, TCP clients and
2798servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>. 2940servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2799 2941
2800Asynchronous DNS: L<AnyEvent::DNS>. 2942Asynchronous DNS: L<AnyEvent::DNS>.
2801 2943
2802Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>. 2944Thread support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.

Diff Legend

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