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.373 by root, Thu Aug 25 03:08:48 2011 UTC vs.
Revision 1.387 by root, Sat Oct 1 22:39:29 2011 UTC

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

Diff Legend

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