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.377 by root, Thu Aug 25 23:20:17 2011 UTC vs.
Revision 1.388 by root, Sun Oct 2 01:22:01 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
… …
1058If L<AnyEvent::Log> is not loaded then this function makes a simple test 1056If 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 1057to 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 1058load AnyEvent::Log and call C<AnyEvent::Log::log> - consequently, look at
1061the L<AnyEvent::Log> documentation for details. 1059the L<AnyEvent::Log> documentation for details.
1062 1060
1063If the test fails it will simply return. 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 1064
1065If 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
1066creating 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 1067which can reduce typing, codesize and can reduce the logging overhead
1068enourmously. 1068enourmously.
… …
1233 1233
1234BEGIN { AnyEvent::common_sense } 1234BEGIN { AnyEvent::common_sense }
1235 1235
1236use Carp (); 1236use Carp ();
1237 1237
1238our $VERSION = '6.01'; 1238our $VERSION = '6.02';
1239our $MODEL; 1239our $MODEL;
1240
1241our @ISA; 1240our @ISA;
1242
1243our @REGISTRY; 1241our @REGISTRY;
1244
1245our $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!)
1246 1245
1247BEGIN { 1246BEGIN {
1248 require "AnyEvent/constants.pl"; 1247 require "AnyEvent/constants.pl";
1249 1248
1250 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1249 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
… …
1256 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV; 1255 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1257 1256
1258 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = () 1257 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1259 if ${^TAINT}; 1258 if ${^TAINT};
1260 1259
1261 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1260 # $ENV{PERL_ANYEVENT_xxx} now valid
1262}
1263 1261
1264our $MAX_SIGNAL_LATENCY = 10; 1262 $VERBOSE = length $ENV{PERL_ANYEVENT_VERBOSE} ? $ENV{PERL_ANYEVENT_VERBOSE}*1 : 4;
1265 1263
1266our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1267
1268{
1269 my $idx; 1264 my $idx;
1270 $PROTOCOL{$_} = ++$idx 1265 $PROTOCOL{$_} = ++$idx
1271 for reverse split /\s*,\s*/, 1266 for reverse split /\s*,\s*/,
1272 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1267 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1273} 1268}
… …
1306 () 1301 ()
1307} 1302}
1308 1303
1309sub log($$;@) { 1304sub log($$;@) {
1310 # only load the big 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
1311 if ($_[0] <= $VERBOSE) { # also catches non-numeric levels(!) 1306 if ($_[0] <= ($VERBOSE || 1)) { # also catches non-numeric levels(!) and fatal
1312 require AnyEvent::Log; 1307 local ($!, $@);
1308 require AnyEvent::Log; # among other things, sets $VERBOSE to 9
1313 # AnyEvent::Log overwrites this function 1309 # AnyEvent::Log overwrites this function
1314 goto &log; 1310 goto &log;
1315 } 1311 }
1316 1312
1317 0 # not logged 1313 0 # not logged
1318} 1314}
1319 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
1320if (length $ENV{PERL_ANYEVENT_LOG}) { 1348if (length $ENV{PERL_ANYEVENT_LOG}) {
1321 require AnyEvent::Log; # AnyEvent::Log does the thing for us 1349 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1322} 1350}
1323 1351
1324our @models = ( 1352our @models = (
1325 [EV:: => AnyEvent::Impl::EV:: , 1], 1353 [EV:: => AnyEvent::Impl::EV::],
1326 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1354 [AnyEvent::Loop:: => AnyEvent::Impl::Perl::],
1327 # everything below here will not (normally) be autoprobed 1355 # everything below here will not (normally) be autoprobed
1328 # as the pure perl backend should work everywhere 1356 # as the pure perl backend should work everywhere
1329 # 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
1330 [Event:: => AnyEvent::Impl::Event::, 1], 1359 [Event:: => AnyEvent::Impl::Event::], # slow, stable
1331 [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
1332 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1362 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1333 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1334 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1363 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1335 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1364 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1336 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1365 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1337 [Wx:: => AnyEvent::Impl::POE::], 1366 [Wx:: => AnyEvent::Impl::POE::],
1338 [Prima:: => AnyEvent::Impl::POE::], 1367 [Prima:: => AnyEvent::Impl::POE::],
1339 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect 1368 [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # a bitch to autodetect
1340 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::], 1369 [Cocoa::EventLoop:: => AnyEvent::Impl::Cocoa::],
1341 [FLTK:: => AnyEvent::Impl::FLTK2::], 1370 [FLTK:: => AnyEvent::Impl::FLTK::],
1342); 1371);
1343 1372
1344our @isa_hook; 1373our @isa_hook;
1345 1374
1346sub _isa_set { 1375sub _isa_set {
… …
1366# due to bugs in perls method cache implementation. 1395# due to bugs in perls method cache implementation.
1367our @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);
1368 1397
1369sub detect() { 1398sub detect() {
1370 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"};
1371 1408
1372 local $!; # for good measure 1409 local $!; # for good measure
1373 local $SIG{__DIE__}; # we use eval 1410 local $SIG{__DIE__}; # we use eval
1374 1411
1375 # free some memory 1412 # free some memory
… …
1387 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//; 1424 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1388 if (eval "require $model") { 1425 if (eval "require $model") {
1389 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it."; 1426 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1390 $MODEL = $model; 1427 $MODEL = $model;
1391 } else { 1428 } else {
1392 AnyEvent::log 5 => "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$@";
1393 } 1430 }
1394 } 1431 }
1395 1432
1396 # check for already loaded models 1433 # check for already loaded models
1397 unless ($MODEL) { 1434 unless ($MODEL) {
… …
1407 } 1444 }
1408 1445
1409 unless ($MODEL) { 1446 unless ($MODEL) {
1410 # try to autoload a model 1447 # try to autoload a model
1411 for (@REGISTRY, @models) { 1448 for (@REGISTRY, @models) {
1412 my ($package, $model, $autoload) = @$_; 1449 my ($package, $model) = @$_;
1413 if ( 1450 if (
1414 $autoload
1415 and eval "require $package" 1451 eval "require $package"
1416 and ${"$package\::VERSION"} > 0 1452 and ${"$package\::VERSION"} > 0
1417 and eval "require $model" 1453 and eval "require $model"
1418 ) { 1454 ) {
1419 AnyEvent::log 7 => "autoloaded model '$model', using it."; 1455 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1420 $MODEL = $model; 1456 $MODEL = $model;
1421 last; 1457 last;
1422 } 1458 }
1423 } 1459 }
1424 1460
1425 $MODEL 1461 $MODEL
1426 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?";
1427 } 1463 }
1428 } 1464 }
1429 1465
1430 # free memory only needed for probing 1466 # free memory only needed for probing
1431 undef @models; 1467 undef @models;
… …
2040 2076
2041=over 4 2077=over 4
2042 2078
2043=item C<PERL_ANYEVENT_VERBOSE> 2079=item C<PERL_ANYEVENT_VERBOSE>
2044 2080
2045By default, AnyEvent will be completely silent except in fatal 2081By default, AnyEvent will only log messages with loglevel C<3>
2046conditions. 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
2084less) talkative.
2085
2047talkative. If you want to do more than just set the global logging level 2086If 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 2087you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
2049complex specifications. 2088complex specifications.
2050 2089
2090When set to C<0> (C<off>), then no messages whatsoever will be logged with
2091the default logging settings.
2092
2051When set to C<5> or higher (warn), causes AnyEvent to warn about unexpected 2093When set to C<5> or higher (C<warn>), causes AnyEvent to warn about
2052conditions, such as not being able to load the event model specified by 2094unexpected conditions, such as not being able to load the event model
2053C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an exception - this 2095specified by C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an
2054is the minimum recommended level. 2096exception - this is the minimum recommended level.
2055 2097
2056When set to C<7> or higher (info), cause AnyEvent to report which event model it 2098When set to C<7> or higher (info), cause AnyEvent to report which event model it
2057chooses. 2099chooses.
2058 2100
2059When set to C<8> or higher (debug), then AnyEvent will report extra information on 2101When set to C<8> or higher (debug), then AnyEvent will report extra information on
… …
2092C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs 2134C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
2093can be very useful, however. 2135can be very useful, however.
2094 2136
2095=item C<PERL_ANYEVENT_DEBUG_SHELL> 2137=item C<PERL_ANYEVENT_DEBUG_SHELL>
2096 2138
2097If 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
2098C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of 2140C<AnyEvent::Socket::parse_hostport> and C<AnyEvent::Debug::shell> (after
2099C<$$> 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
2100that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>. 2142is saved in C<$AnyEvent::Debug::SHELL>.
2101 2143
2102This happens when the first watcher is created. 2144This happens when the first watcher is created.
2103 2145
2104For 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
2105F<< /tmp/debug<pid>.sock >>, you could use this: 2147F<< /tmp/debug<pid>.sock >>, you could use this:
2106 2148
2107 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
2108 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
2109Note 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
2110systems. 2158multiuser systems.
2111 2159
2112=item C<PERL_ANYEVENT_DEBUG_WRAP> 2160=item C<PERL_ANYEVENT_DEBUG_WRAP>
2113 2161
2114Can 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
2115debugging purposes. See C<AnyEvent::Debug::wrap> for details. 2163debugging purposes. See C<AnyEvent::Debug::wrap> for details.
… …
2179=item C<PERL_ANYEVENT_MAX_OUTSTANDING_DNS> 2227=item C<PERL_ANYEVENT_MAX_OUTSTANDING_DNS>
2180 2228
2181The 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
2182resolver - this is the maximum number of parallel DNS requests that are 2230resolver - this is the maximum number of parallel DNS requests that are
2183sent to the DNS server. 2231sent to the DNS server.
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).
2184 2254
2185=item C<PERL_ANYEVENT_RESOLV_CONF> 2255=item C<PERL_ANYEVENT_RESOLV_CONF>
2186 2256
2187The absolute path to a F<resolv.conf>-style file to use instead of 2257The absolute path to a F<resolv.conf>-style file to use instead of
2188F</etc/resolv.conf> (or the OS-specific configuration) in the default 2258F</etc/resolv.conf> (or the OS-specific configuration) in the default

Diff Legend

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