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.388 by root, Sun Oct 2 01:22:01 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
… …
415not restart syscalls (that includes L<Async::Interrupt> and AnyEvent's 415not restart syscalls (that includes L<Async::Interrupt> and AnyEvent's
416pure perl implementation). 416pure perl implementation).
417 417
418=head3 Safe/Unsafe Signals 418=head3 Safe/Unsafe Signals
419 419
420Perl signals can be either "safe" (synchronous to opcode handling) or 420Perl signals can be either "safe" (synchronous to opcode handling)
421"unsafe" (asynchronous) - the former might get delayed indefinitely, the 421or "unsafe" (asynchronous) - the former might delay signal delivery
422latter might corrupt your memory. 422indefinitely, the latter might corrupt your memory.
423 423
424AnyEvent signal handlers are, in addition, synchronous to the event loop, 424AnyEvent signal handlers are, in addition, synchronous to the event loop,
425i.e. they will not interrupt your running perl program but will only be 425i.e. they will not interrupt your running perl program but will only be
426called as part of the normal event handling (just like timer, I/O etc. 426called as part of the normal event handling (just like timer, I/O etc.
427callbacks, too). 427callbacks, too).
428 428
429=head3 Signal Races, Delays and Workarounds 429=head3 Signal Races, Delays and Workarounds
430 430
431Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching 431Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support
432callbacks to signals in a generic way, which is a pity, as you cannot 432attaching callbacks to signals in a generic way, which is a pity,
433do race-free signal handling in perl, requiring C libraries for 433as you cannot do race-free signal handling in perl, requiring
434this. AnyEvent will try to do its best, which means in some cases, 434C libraries for this. AnyEvent will try to do its best, which
435signals will be delayed. The maximum time a signal might be delayed is 435means in some cases, signals will be delayed. The maximum time
436specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 seconds). This 436a signal might be delayed is 10 seconds by default, but can
437variable can be changed only before the first signal watcher is created, 437be overriden via C<$ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY}> or
438and should be left alone otherwise. This variable determines how often 438C<$AnyEvent::MAX_SIGNAL_LATENCY> - see the Ö<ENVIRONMENT VARIABLES>
439AnyEvent polls for signals (in case a wake-up was missed). Higher values 439section for details.
440will cause fewer spurious wake-ups, which is better for power and CPU
441saving.
442 440
443All these problems can be avoided by installing the optional 441All these problems can be avoided by installing the optional
444L<Async::Interrupt> module, which works with most event loops. It will not 442L<Async::Interrupt> module, which works with most event loops. It will not
445work with inherently broken event loops such as L<Event> or L<Event::Lib> 443work with inherently broken event loops such as L<Event> or L<Event::Lib>
446(and not with L<POE> currently, as POE does its own workaround with 444(and not with L<POE> currently). For those, you just have to suffer the
447one-second latency). For those, you just have to suffer the delays. 445delays.
448 446
449=head2 CHILD PROCESS WATCHERS 447=head2 CHILD PROCESS WATCHERS
450 448
451 $w = AnyEvent->child (pid => <process id>, cb => <callback>); 449 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
452 450
… …
878 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 876 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
879 AnyEvent::Impl::POE based on POE, very slow, some limitations. 877 AnyEvent::Impl::POE based on POE, very slow, some limitations.
880 AnyEvent::Impl::Irssi used when running within irssi. 878 AnyEvent::Impl::Irssi used when running within irssi.
881 AnyEvent::Impl::IOAsync based on IO::Async. 879 AnyEvent::Impl::IOAsync based on IO::Async.
882 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop. 880 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop.
883 AnyEvent::Impl::FLTK2 based on FLTK (fltk 2 binding). 881 AnyEvent::Impl::FLTK based on FLTK (fltk 2 binding).
884 882
885=item Backends with special needs. 883=item Backends with special needs.
886 884
887Qt requires the Qt::Application to be instantiated first, but will 885Qt requires the Qt::Application to be instantiated first, but will
888otherwise be picked up automatically. As long as the main program 886otherwise be picked up automatically. As long as the main program
… …
1053 1051
1054=item AnyEvent::log $level, $msg[, @args] 1052=item AnyEvent::log $level, $msg[, @args]
1055 1053
1056Log the given C<$msg> at the given C<$level>. 1054Log the given C<$msg> at the given C<$level>.
1057 1055
1058Loads AnyEvent::Log on first use and calls C<AnyEvent::Log::log> - 1056If L<AnyEvent::Log> is not loaded then this function makes a simple test
1057to see whether the message will be logged. If the test succeeds it will
1058load AnyEvent::Log and call C<AnyEvent::Log::log> - consequently, look at
1059consequently, look at the L<AnyEvent::Log> documentation for details. 1059the L<AnyEvent::Log> documentation for details.
1060
1061If the test fails it will simply return. Right now this happens when a
1062numerical loglevel is used and it is larger than the level specified via
1063C<$ENV{PERL_ANYEVENT_VERBOSE}>.
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.
1060 1069
1061=back 1070=back
1062 1071
1063=head1 WHAT TO DO IN A MODULE 1072=head1 WHAT TO DO IN A MODULE
1064 1073
… …
1121 1130
1122 1131
1123=head1 OTHER MODULES 1132=head1 OTHER MODULES
1124 1133
1125The following is a non-exhaustive list of additional modules that use 1134The following is a non-exhaustive list of additional modules that use
1126AnyEvent as a client and can therefore be mixed easily with other AnyEvent 1135AnyEvent as a client and can therefore be mixed easily with other
1127modules 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
1128come 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 :)
1129 1141
1130=over 4 1142=over 4
1131 1143
1132=item L<AnyEvent::Util> 1144=item L<AnyEvent::Util>
1133 1145
… …
1153=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>
1154 1166
1155Implement event-based interfaces to the protocols of the same name (for 1167Implement event-based interfaces to the protocols of the same name (for
1156the 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
1157Client Protocol). 1169Client 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 1170
1181=item L<AnyEvent::AIO> 1171=item L<AnyEvent::AIO>
1182 1172
1183Truly 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
1184toolbox of every event programmer. AnyEvent::AIO transparently fuses 1174toolbox of every event programmer. AnyEvent::AIO transparently fuses
1185L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based 1175L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
1186file I/O, and much more. 1176file I/O, and much more.
1187 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
1188=item L<AnyEvent::HTTPD> 1196=item L<AnyEvent::HTTPD>
1189 1197
1190A simple embedded webserver. 1198A simple embedded webserver.
1191 1199
1192=item L<AnyEvent::FastPing> 1200=item L<AnyEvent::FastPing>
1193 1201
1194The fastest ping in the west. 1202The fastest ping in the west.
1195 1203
1196=item L<Coro> 1204=item L<Coro>
1197 1205
1198Has 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 };
1199 1219
1200=back 1220=back
1201 1221
1202=cut 1222=cut
1203 1223
… …
1213 1233
1214BEGIN { AnyEvent::common_sense } 1234BEGIN { AnyEvent::common_sense }
1215 1235
1216use Carp (); 1236use Carp ();
1217 1237
1218our $VERSION = '6.01'; 1238our $VERSION = '6.02';
1219our $MODEL; 1239our $MODEL;
1220
1221our @ISA; 1240our @ISA;
1222
1223our @REGISTRY; 1241our @REGISTRY;
1224
1225our $VERBOSE; 1242our $VERBOSE;
1243our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1244our $MAX_SIGNAL_LATENCY = $ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY} || 10; # executes after the BEGIN block below (tainting!)
1226 1245
1227BEGIN { 1246BEGIN {
1228 require "AnyEvent/constants.pl"; 1247 require "AnyEvent/constants.pl";
1229 1248
1230 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1249 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1231 1250
1232 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1251 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1233 if ${^TAINT}; 1252 if ${^TAINT};
1234 1253
1235 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1254 $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
1236} 1255 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1237 1256
1238our $MAX_SIGNAL_LATENCY = 10; 1257 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1258 if ${^TAINT};
1239 1259
1240our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred 1260 # $ENV{PERL_ANYEVENT_xxx} now valid
1241 1261
1242{ 1262 $VERBOSE = length $ENV{PERL_ANYEVENT_VERBOSE} ? $ENV{PERL_ANYEVENT_VERBOSE}*1 : 4;
1263
1243 my $idx; 1264 my $idx;
1244 $PROTOCOL{$_} = ++$idx 1265 $PROTOCOL{$_} = ++$idx
1245 for reverse split /\s*,\s*/, 1266 for reverse split /\s*,\s*/,
1246 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1267 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1247} 1268}
… …
1279 1300
1280 () 1301 ()
1281} 1302}
1282 1303
1283sub log($$;@) { 1304sub log($$;@) {
1284 require AnyEvent::Log; 1305 # only load the big bloated module when we actually are about to log something
1306 if ($_[0] <= ($VERBOSE || 1)) { # also catches non-numeric levels(!) and fatal
1307 local ($!, $@);
1308 require AnyEvent::Log; # among other things, sets $VERBOSE to 9
1285 # AnyEvent::Log overwrites this function 1309 # AnyEvent::Log overwrites this function
1286 goto &log; 1310 goto &log;
1311 }
1312
1313 0 # not logged
1314}
1315
1316sub logger($;$) {
1317 package AnyEvent::Log;
1318
1319 my ($level, $renabled) = @_;
1320
1321 $$renabled = $level <= $VERBOSE;
1322
1323 my $pkg = (caller)[0];
1324
1325 my $logger = [$pkg, $level, $renabled];
1326
1327 our %LOGGER;
1328 $LOGGER{$logger+0} = $logger;
1329
1330 return unless defined wantarray;
1331
1332 require AnyEvent::Util;
1333 my $guard = AnyEvent::Util::guard (sub {
1334 # "clean up"
1335 delete $LOGGER{$logger+0};
1336 });
1337
1338 sub {
1339 return 0 unless $$renabled;
1340
1341 $guard if 0; # keep guard alive, but don't cause runtime overhead
1342 require AnyEvent::Log unless $AnyEvent::Log::VERSION;
1343 package AnyEvent::Log;
1344 _log ($logger->[0], $level, @_) # logger->[0] has been converted at load time
1345 }
1346}
1347
1348if (length $ENV{PERL_ANYEVENT_LOG}) {
1349 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1287} 1350}
1288 1351
1289our @models = ( 1352our @models = (
1290 [EV:: => AnyEvent::Impl::EV:: , 1], 1353 [EV:: => AnyEvent::Impl::EV::],
1291 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1354 [AnyEvent::Loop:: => AnyEvent::Impl::Perl::],
1292 # everything below here will not (normally) be autoprobed 1355 # everything below here will not (normally) be autoprobed
1293 # as the pure perl backend should work everywhere 1356 # as the pure perl backend should work everywhere
1294 # and is usually faster 1357 # and is usually faster
1358 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package, so msut be near the top
1295 [Event:: => AnyEvent::Impl::Event::, 1], 1359 [Event:: => AnyEvent::Impl::Event::], # slow, stable
1296 [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers 1360 [Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
1361 # everything below here should not be autoloaded
1297 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1362 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1298 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1299 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1363 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1300 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1364 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1301 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1365 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1302 [Wx:: => AnyEvent::Impl::POE::], 1366 [Wx:: => AnyEvent::Impl::POE::],
1303 [Prima:: => AnyEvent::Impl::POE::], 1367 [Prima:: => AnyEvent::Impl::POE::],
1304 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect 1368 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1305 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::], 1369 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1306 [FLTK:: => AnyEvent::Impl::FLTK2::], 1370 [FLTK:: => AnyEvent::Impl::FLTK::],
1307); 1371);
1308 1372
1309our @isa_hook; 1373our @isa_hook;
1310 1374
1311sub _isa_set { 1375sub _isa_set {
… …
1331# due to bugs in perls method cache implementation. 1395# due to bugs in perls method cache implementation.
1332our @methods = qw(io timer time now now_update signal child idle condvar); 1396our @methods = qw(io timer time now now_update signal child idle condvar);
1333 1397
1334sub detect() { 1398sub detect() {
1335 return $MODEL if $MODEL; # some programs keep references to detect 1399 return $MODEL if $MODEL; # some programs keep references to detect
1400
1401 # IO::Async::Loop::AnyEvent is extremely evil, refuse to work with it
1402 # the author knows about the problems and what it does to AnyEvent as a whole
1403 # (and the ability of others to use AnyEvent), but simply wants to abuse AnyEvent
1404 # anyway.
1405 AnyEvent::log fatal => "AnyEvent: IO::Async::Loop::AnyEvent detected - this module is broken by design,\n"
1406 . "abuses internals and breaks AnyEvent, will not continue."
1407 if exists $INC{"IO/Async/Loop/AnyEvent.pm"};
1336 1408
1337 local $!; # for good measure 1409 local $!; # for good measure
1338 local $SIG{__DIE__}; # we use eval 1410 local $SIG{__DIE__}; # we use eval
1339 1411
1340 # free some memory 1412 # free some memory
… …
1349 1421
1350 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) { 1422 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1351 my $model = $1; 1423 my $model = $1;
1352 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//; 1424 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1353 if (eval "require $model") { 1425 if (eval "require $model") {
1426 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1354 $MODEL = $model; 1427 $MODEL = $model;
1355 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it."
1356 if $VERBOSE >= 7;
1357 } else { 1428 } else {
1358 AnyEvent::log warn => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@"; 1429 AnyEvent::log 4 => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1359 } 1430 }
1360 } 1431 }
1361 1432
1362 # check for already loaded models 1433 # check for already loaded models
1363 unless ($MODEL) { 1434 unless ($MODEL) {
1364 for (@REGISTRY, @models) { 1435 for (@REGISTRY, @models) {
1365 my ($package, $model) = @$_; 1436 my ($package, $model) = @$_;
1366 if (${"$package\::VERSION"} > 0) { 1437 if (${"$package\::VERSION"} > 0) {
1367 if (eval "require $model") { 1438 if (eval "require $model") {
1439 AnyEvent::log 7 => "autodetected model '$model', using it.";
1368 $MODEL = $model; 1440 $MODEL = $model;
1369 AnyEvent::log 7 => "autodetected model '$model', using it."
1370 if $VERBOSE >= 7;
1371 last; 1441 last;
1372 } 1442 }
1373 } 1443 }
1374 } 1444 }
1375 1445
1376 unless ($MODEL) { 1446 unless ($MODEL) {
1377 # try to autoload a model 1447 # try to autoload a model
1378 for (@REGISTRY, @models) { 1448 for (@REGISTRY, @models) {
1379 my ($package, $model, $autoload) = @$_; 1449 my ($package, $model) = @$_;
1380 if ( 1450 if (
1381 $autoload
1382 and eval "require $package" 1451 eval "require $package"
1383 and ${"$package\::VERSION"} > 0 1452 and ${"$package\::VERSION"} > 0
1384 and eval "require $model" 1453 and eval "require $model"
1385 ) { 1454 ) {
1455 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1386 $MODEL = $model; 1456 $MODEL = $model;
1387 AnyEvent::log 7 => "autoloaded model '$model', using it."
1388 if $VERBOSE >= 7;
1389 last; 1457 last;
1390 } 1458 }
1391 } 1459 }
1392 1460
1393 $MODEL 1461 $MODEL
1394 or die "AnyEvent: backend autodetection failed - did you properly install AnyEvent?"; 1462 or AnyEvent::log fatal => "AnyEvent: backend autodetection failed - did you properly install AnyEvent?";
1395 } 1463 }
1396 } 1464 }
1397 1465
1398 # free memory only needed for probing 1466 # free memory only needed for probing
1399 undef @models; 1467 undef @models;
… …
1408 if defined &{"$MODEL\::$_"}; 1476 if defined &{"$MODEL\::$_"};
1409 } 1477 }
1410 1478
1411 _isa_set; 1479 _isa_set;
1412 1480
1481 # we're officially open!
1482
1413 if ($ENV{PERL_ANYEVENT_STRICT}) { 1483 if ($ENV{PERL_ANYEVENT_STRICT}) {
1414 require AnyEvent::Strict; 1484 require AnyEvent::Strict;
1415 } 1485 }
1416 1486
1417 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) { 1487 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1418 require AnyEvent::Debug; 1488 require AnyEvent::Debug;
1419 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP}); 1489 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1420 } 1490 }
1421 1491
1422 if (exists $ENV{PERL_ANYEVENT_DEBUG_SHELL}) { 1492 if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1423 require AnyEvent::Socket; 1493 require AnyEvent::Socket;
1424 require AnyEvent::Debug; 1494 require AnyEvent::Debug;
1425 1495
1426 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL}; 1496 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1427 $shell =~ s/\$\$/$$/g; 1497 $shell =~ s/\$\$/$$/g;
1428 1498
1429 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell); 1499 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1430 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service); 1500 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
1431 } 1501 }
1502
1503 # now the anyevent environment is set up as the user told us to, so
1504 # call the actual user code - post detects
1432 1505
1433 (shift @post_detect)->() while @post_detect; 1506 (shift @post_detect)->() while @post_detect;
1434 undef @post_detect; 1507 undef @post_detect;
1435 1508
1436 *post_detect = sub(&) { 1509 *post_detect = sub(&) {
… …
1538 1611
1539sub time { 1612sub time {
1540 eval q{ # poor man's autoloading {} 1613 eval q{ # poor man's autoloading {}
1541 # probe for availability of Time::HiRes 1614 # probe for availability of Time::HiRes
1542 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1615 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 () }; 1616 *time = sub { Time::HiRes::time () };
1546 *AE::time = \& Time::HiRes::time ; 1617 *AE::time = \& Time::HiRes::time ;
1618 *now = \&time;
1619 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy.";
1547 # if (eval "use POSIX (); (POSIX::times())... 1620 # if (eval "use POSIX (); (POSIX::times())...
1548 } else { 1621 } else {
1549 AnyEvent::log critical => "using built-in time(), WARNING, no sub-second resolution!";
1550 *time = sub { CORE::time }; 1622 *time = sub { CORE::time };
1551 *AE::time = sub (){ CORE::time }; 1623 *AE::time = sub (){ CORE::time };
1624 *now = \&time;
1625 AnyEvent::log 3 => "using built-in time(), WARNING, no sub-second resolution!";
1552 } 1626 }
1553
1554 *now = \&time;
1555 }; 1627 };
1556 die if $@; 1628 die if $@;
1557 1629
1558 &time 1630 &time
1559} 1631}
… …
1652 1724
1653sub signal { 1725sub signal {
1654 eval q{ # poor man's autoloading {} 1726 eval q{ # poor man's autoloading {}
1655 # probe for availability of Async::Interrupt 1727 # probe for availability of Async::Interrupt
1656 if (_have_async_interrupt) { 1728 if (_have_async_interrupt) {
1657 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling." 1729 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling.";
1658 if $AnyEvent::VERBOSE >= 8;
1659 1730
1660 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1731 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1661 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1732 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1662 1733
1663 } else { 1734 } else {
1664 AnyEvent::log 8 => "using emulated perl signal handling with latency timer." 1735 AnyEvent::log 8 => "using emulated perl signal handling with latency timer.";
1665 if $AnyEvent::VERBOSE >= 8;
1666 1736
1667 if (AnyEvent::WIN32) { 1737 if (AnyEvent::WIN32) {
1668 require AnyEvent::Util; 1738 require AnyEvent::Util;
1669 1739
1670 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1740 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
… …
1964$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 2034$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1965so on. 2035so on.
1966 2036
1967=head1 ENVIRONMENT VARIABLES 2037=head1 ENVIRONMENT VARIABLES
1968 2038
1969The following environment variables are used by this module or its 2039AnyEvent supports a number of environment variables that tune the
1970submodules. 2040runtime behaviour. They are usually evaluated when AnyEvent is
2041loaded, initialised, or a submodule that uses them is loaded. Many of
2042them also cause AnyEvent to load additional modules - for example,
2043C<PERL_ANYEVENT_DEBUG_WRAP> causes the L<AnyEvent::Debug> module to be
2044loaded.
1971 2045
1972Note that AnyEvent will remove I<all> environment variables starting with 2046All the environment variables documented here start with
1973C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 2047C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1974enabled. 2048namespace. Other modules are encouraged (but by no means required) to use
2049C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
2050namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
2051be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
2052variables starting with C<AE_>, see below).
2053
2054All variables can also be set via the C<AE_> prefix, that is, instead
2055of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
2056case there is a clash btween anyevent and another program that uses
2057C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
2058variable to the empty string, as those variables take precedence.
2059
2060When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
2061to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
2062exists. If taint mode is on, then AnyEvent will remove I<all> environment
2063variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
2064with C<undef> or the empty string, if the corresaponding C<AE_> variable
2065is set).
2066
2067The exact algorithm is currently:
2068
2069 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
2070 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
2071 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
2072
2073This ensures that child processes will not see the C<AE_> variables.
2074
2075The following environment variables are currently known to AnyEvent:
1975 2076
1976=over 4 2077=over 4
1977 2078
1978=item C<PERL_ANYEVENT_VERBOSE> 2079=item C<PERL_ANYEVENT_VERBOSE>
1979 2080
1980By default, AnyEvent will be completely silent except in fatal 2081By default, AnyEvent will only log messages with loglevel C<3>
1981conditions. You can set this environment variable to make AnyEvent more 2082(C<critical>) or higher (see L<AnyEvent::Log>). You can set this
2083environment variable to a numerical loglevel to make AnyEvent more (or
1982talkative. 2084less) talkative.
1983 2085
2086If you want to do more than just set the global logging level
2087you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
2088complex specifications.
2089
2090When set to C<0> (C<off>), then no messages whatsoever will be logged with
2091the default logging settings.
2092
1984When set to C<5> or higher, causes AnyEvent to warn about unexpected 2093When 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 2094unexpected conditions, such as not being able to load the event model
1986C<PERL_ANYEVENT_MODEL>. 2095specified by C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an
2096exception - this is the minimum recommended level.
1987 2097
1988When set to C<7> or higher, cause AnyEvent to report to STDERR which event 2098When set to C<7> or higher (info), cause AnyEvent to report which event model it
1989model it chooses. 2099chooses.
1990 2100
1991When set to C<8> or higher, then AnyEvent will report extra information on 2101When 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. 2102which optional modules it loads and how it implements certain features.
2103
2104=item C<PERL_ANYEVENT_LOG>
2105
2106Accepts rather complex logging specifications. For example, you could log
2107all C<debug> messages of some module to stderr, warnings and above to
2108stderr, and errors and above to syslog, with:
2109
2110 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
2111
2112For the rather extensive details, see L<AnyEvent::Log>.
2113
2114This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
2115so will take effect even before AnyEvent has initialised itself.
2116
2117Note that specifying this environment variable causes the L<AnyEvent::Log>
2118module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
2119using the latter saves a few hundred kB of memory until the first message
2120is being logged.
1993 2121
1994=item C<PERL_ANYEVENT_STRICT> 2122=item C<PERL_ANYEVENT_STRICT>
1995 2123
1996AnyEvent does not do much argument checking by default, as thorough 2124AnyEvent does not do much argument checking by default, as thorough
1997argument checking is very costly. Setting this variable to a true value 2125argument checking is very costly. Setting this variable to a true value
… …
2006C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs 2134C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
2007can be very useful, however. 2135can be very useful, however.
2008 2136
2009=item C<PERL_ANYEVENT_DEBUG_SHELL> 2137=item C<PERL_ANYEVENT_DEBUG_SHELL>
2010 2138
2011If this env variable is set, then its contents will be interpreted by 2139If this env variable is nonempty, then its contents will be interpreted by
2012C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of 2140C<AnyEvent::Socket::parse_hostport> and C<AnyEvent::Debug::shell> (after
2013C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on 2141replacing every occurance of C<$$> by the process pid). The shell object
2014that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>. 2142is saved in C<$AnyEvent::Debug::SHELL>.
2015 2143
2016This takes place when the first watcher is created. 2144This happens when the first watcher is created.
2017 2145
2018For example, to bind a debug shell on a unix domain socket in 2146For example, to bind a debug shell on a unix domain socket in
2019F<< /tmp/debug<pid>.sock >>, you could use this: 2147F<< /tmp/debug<pid>.sock >>, you could use this:
2020 2148
2021 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog 2149 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
2150 # connect with e.g.: socat readline /tmp/debug123.sock
2022 2151
2152Or to bind to tcp port 4545 on localhost:
2153
2154 PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
2155 # connect with e.g.: telnet localhost 4545
2156
2023Note that creating sockets in F</tmp> is very unsafe on multiuser 2157Note that creating sockets in F</tmp> or on localhost is very unsafe on
2024systems. 2158multiuser systems.
2025 2159
2026=item C<PERL_ANYEVENT_DEBUG_WRAP> 2160=item C<PERL_ANYEVENT_DEBUG_WRAP>
2027 2161
2028Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for 2162Can 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. 2163debugging purposes. See C<AnyEvent::Debug::wrap> for details.
… …
2067but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4> 2201but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
2068- only support IPv4, never try to resolve or contact IPv6 2202- only support IPv4, never try to resolve or contact IPv6
2069addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2203addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
2070IPv6, but prefer IPv6 over IPv4. 2204IPv6, but prefer IPv6 over IPv4.
2071 2205
2206=item C<PERL_ANYEVENT_HOSTS>
2207
2208This variable, if specified, overrides the F</etc/hosts> file used by
2209L<AnyEvent::Socket>C<::resolve_sockaddr>, i.e. hosts aliases will be read
2210from that file instead.
2211
2072=item C<PERL_ANYEVENT_EDNS0> 2212=item C<PERL_ANYEVENT_EDNS0>
2073 2213
2074Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension 2214Used 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 2215DNS. This extension is generally useful to reduce DNS traffic, especially
2076some (broken) firewalls drop such DNS packets, which is why it is off by 2216when DNSSEC is involved, but some (broken) firewalls drop such DNS
2077default. 2217packets, which is why it is off by default.
2078 2218
2079Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 2219Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
2080EDNS0 in its DNS requests. 2220EDNS0 in its DNS requests.
2081 2221
2082=item C<PERL_ANYEVENT_MAX_FORKS> 2222=item C<PERL_ANYEVENT_MAX_FORKS>
… …
2088 2228
2089The default value for the C<max_outstanding> parameter for the default DNS 2229The default value for the C<max_outstanding> parameter for the default DNS
2090resolver - this is the maximum number of parallel DNS requests that are 2230resolver - this is the maximum number of parallel DNS requests that are
2091sent to the DNS server. 2231sent to the DNS server.
2092 2232
2233=item C<PERL_ANYEVENT_MAX_SIGNAL_LATENCY>
2234
2235Perl has inherently racy signal handling (you can basically choose between
2236losing signals and memory corruption) - pure perl event loops (including
2237C<AnyEvent::Loop>, when C<Async::Interrupt> isn't available) therefore
2238have to poll regularly to avoid losing signals.
2239
2240Some event loops are racy, but don't poll regularly, and some event loops
2241are written in C but are still racy. For those event loops, AnyEvent
2242installs a timer that regularly wakes up the event loop.
2243
2244By default, the interval for this timer is C<10> seconds, but you can
2245override this delay with this environment variable (or by setting
2246the C<$AnyEvent::MAX_SIGNAL_LATENCY> variable before creating signal
2247watchers).
2248
2249Lower values increase CPU (and energy) usage, higher values can introduce
2250long delays when reaping children or waiting for signals.
2251
2252The L<AnyEvent::Async> module, if available, will be used to avoid this
2253polling (with most event loops).
2254
2093=item C<PERL_ANYEVENT_RESOLV_CONF> 2255=item C<PERL_ANYEVENT_RESOLV_CONF>
2094 2256
2095The file to use instead of F</etc/resolv.conf> (or OS-specific 2257The 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 2258F</etc/resolv.conf> (or the OS-specific configuration) in the default
2097default config will be used. 2259resolver, or the empty string to select the default configuration.
2098 2260
2099=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2261=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
2100 2262
2101When neither C<ca_file> nor C<ca_path> was specified during 2263When neither C<ca_file> nor C<ca_path> was specified during
2102L<AnyEvent::TLS> context creation, and either of these environment 2264L<AnyEvent::TLS> context creation, and either of these environment
2103variables exist, they will be used to specify CA certificate locations 2265variables are nonempty, they will be used to specify CA certificate
2104instead of a system-dependent default. 2266locations instead of a system-dependent default.
2105 2267
2106=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT> 2268=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
2107 2269
2108When these are set to C<1>, then the respective modules are not 2270When these are set to C<1>, then the respective modules are not
2109loaded. Mostly good for testing AnyEvent itself. 2271loaded. Mostly good for testing AnyEvent itself.

Diff Legend

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