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.380 by root, Thu Sep 1 04:07:18 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
… …
1237 1235
1238use Carp (); 1236use Carp ();
1239 1237
1240our $VERSION = '6.02'; 1238our $VERSION = '6.02';
1241our $MODEL; 1239our $MODEL;
1242
1243our @ISA; 1240our @ISA;
1244
1245our @REGISTRY; 1241our @REGISTRY;
1246
1247our $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!)
1248 1245
1249BEGIN { 1246BEGIN {
1250 require "AnyEvent/constants.pl"; 1247 require "AnyEvent/constants.pl";
1251 1248
1252 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1249 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
… …
1258 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV; 1255 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1259 1256
1260 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = () 1257 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1261 if ${^TAINT}; 1258 if ${^TAINT};
1262 1259
1260 # $ENV{PERL_ANYEVENT_xxx} now valid
1261
1263 $VERBOSE = length $ENV{PERL_ANYEVENT_VERBOSE} ? $ENV{PERL_ANYEVENT_VERBOSE}*1 : 3; 1262 $VERBOSE = length $ENV{PERL_ANYEVENT_VERBOSE} ? $ENV{PERL_ANYEVENT_VERBOSE}*1 : 4;
1264}
1265 1263
1266our $MAX_SIGNAL_LATENCY = 10;
1267
1268our %PROTOCOL; # (ipv4|ipv6) => (1|2), higher numbers are preferred
1269
1270{
1271 my $idx; 1264 my $idx;
1272 $PROTOCOL{$_} = ++$idx 1265 $PROTOCOL{$_} = ++$idx
1273 for reverse split /\s*,\s*/, 1266 for reverse split /\s*,\s*/,
1274 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6"; 1267 $ENV{PERL_ANYEVENT_PROTOCOLS} || "ipv4,ipv6";
1275} 1268}
… …
1308 () 1301 ()
1309} 1302}
1310 1303
1311sub log($$;@) { 1304sub log($$;@) {
1312 # 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
1313 if ($_[0] <= $VERBOSE) { # also catches non-numeric levels(!) 1306 if ($_[0] <= ($VERBOSE || 1)) { # also catches non-numeric levels(!) and fatal
1314 require AnyEvent::Log; 1307 require AnyEvent::Log; # among other things, sets $VERBOSE to 9
1315 # AnyEvent::Log overwrites this function 1308 # AnyEvent::Log overwrites this function
1316 goto &log; 1309 goto &log;
1317 } 1310 }
1318 1311
1319 0 # not logged 1312 0 # not logged
1320} 1313}
1321 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 }
1343}
1344
1322if (length $ENV{PERL_ANYEVENT_LOG}) { 1345if (length $ENV{PERL_ANYEVENT_LOG}) {
1323 require AnyEvent::Log; # AnyEvent::Log does the thing for us 1346 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1324} 1347}
1325 1348
1326our @models = ( 1349our @models = (
1327 [EV:: => AnyEvent::Impl::EV:: , 1], 1350 [EV:: => AnyEvent::Impl::EV::],
1328 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1351 [AnyEvent::Loop:: => AnyEvent::Impl::Perl::],
1329 # everything below here will not (normally) be autoprobed 1352 # everything below here will not (normally) be autoprobed
1330 # as the pure perl backend should work everywhere 1353 # as the pure perl backend should work everywhere
1331 # 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
1332 [Event:: => AnyEvent::Impl::Event::, 1], 1356 [Event:: => AnyEvent::Impl::Event::], # slow, stable
1333 [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
1334 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy 1359 [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
1335 [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package
1336 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles 1360 [Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1337 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program 1361 [Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1338 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza 1362 [POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1339 [Wx:: => AnyEvent::Impl::POE::], 1363 [Wx:: => AnyEvent::Impl::POE::],
1340 [Prima:: => AnyEvent::Impl::POE::], 1364 [Prima:: => AnyEvent::Impl::POE::],
… …
1369our @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);
1370 1394
1371sub detect() { 1395sub detect() {
1372 return $MODEL if $MODEL; # some programs keep references to detect 1396 return $MODEL if $MODEL; # some programs keep references to detect
1373 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"};
1405
1374 local $!; # for good measure 1406 local $!; # for good measure
1375 local $SIG{__DIE__}; # we use eval 1407 local $SIG{__DIE__}; # we use eval
1376 1408
1377 # free some memory 1409 # free some memory
1378 *detect = sub () { $MODEL }; 1410 *detect = sub () { $MODEL };
… …
1389 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//; 1421 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1390 if (eval "require $model") { 1422 if (eval "require $model") {
1391 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.";
1392 $MODEL = $model; 1424 $MODEL = $model;
1393 } else { 1425 } else {
1394 AnyEvent::log 5 => "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$@";
1395 } 1427 }
1396 } 1428 }
1397 1429
1398 # check for already loaded models 1430 # check for already loaded models
1399 unless ($MODEL) { 1431 unless ($MODEL) {
… …
1409 } 1441 }
1410 1442
1411 unless ($MODEL) { 1443 unless ($MODEL) {
1412 # try to autoload a model 1444 # try to autoload a model
1413 for (@REGISTRY, @models) { 1445 for (@REGISTRY, @models) {
1414 my ($package, $model, $autoload) = @$_; 1446 my ($package, $model) = @$_;
1415 if ( 1447 if (
1416 $autoload
1417 and eval "require $package" 1448 eval "require $package"
1418 and ${"$package\::VERSION"} > 0 1449 and ${"$package\::VERSION"} > 0
1419 and eval "require $model" 1450 and eval "require $model"
1420 ) { 1451 ) {
1421 AnyEvent::log 7 => "autoloaded model '$model', using it."; 1452 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1422 $MODEL = $model; 1453 $MODEL = $model;
1423 last; 1454 last;
1424 } 1455 }
1425 } 1456 }
1426 1457
1427 $MODEL 1458 $MODEL
1428 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?";
1429 } 1460 }
1430 } 1461 }
1431 1462
1432 # free memory only needed for probing 1463 # free memory only needed for probing
1433 undef @models; 1464 undef @models;
… …
2100C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs 2131C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
2101can be very useful, however. 2132can be very useful, however.
2102 2133
2103=item C<PERL_ANYEVENT_DEBUG_SHELL> 2134=item C<PERL_ANYEVENT_DEBUG_SHELL>
2104 2135
2105If 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
2106C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of 2137C<AnyEvent::Socket::parse_hostport> and C<AnyEvent::Debug::shell> (after
2107C<$$> 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
2108that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>. 2139is saved in C<$AnyEvent::Debug::SHELL>.
2109 2140
2110This happens when the first watcher is created. 2141This happens when the first watcher is created.
2111 2142
2112For 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
2113F<< /tmp/debug<pid>.sock >>, you could use this: 2144F<< /tmp/debug<pid>.sock >>, you could use this:
2114 2145
2115 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
2116 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
2117Note 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
2118systems. 2155multiuser systems.
2119 2156
2120=item C<PERL_ANYEVENT_DEBUG_WRAP> 2157=item C<PERL_ANYEVENT_DEBUG_WRAP>
2121 2158
2122Can 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
2123debugging purposes. See C<AnyEvent::Debug::wrap> for details. 2160debugging purposes. See C<AnyEvent::Debug::wrap> for details.
… …
2187=item C<PERL_ANYEVENT_MAX_OUTSTANDING_DNS> 2224=item C<PERL_ANYEVENT_MAX_OUTSTANDING_DNS>
2188 2225
2189The 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
2190resolver - this is the maximum number of parallel DNS requests that are 2227resolver - this is the maximum number of parallel DNS requests that are
2191sent 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).
2192 2251
2193=item C<PERL_ANYEVENT_RESOLV_CONF> 2252=item C<PERL_ANYEVENT_RESOLV_CONF>
2194 2253
2195The 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
2196F</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