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.376 by root, Thu Aug 25 06:34:11 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
… …
1053 1053
1054=item AnyEvent::log $level, $msg[, @args] 1054=item AnyEvent::log $level, $msg[, @args]
1055 1055
1056Log the given C<$msg> at the given C<$level>. 1056Log the given C<$msg> at the given C<$level>.
1057 1057
1058Loads AnyEvent::Log on first use and calls C<AnyEvent::Log::log> - 1058If L<AnyEvent::Log> is not loaded then this function makes a simple test
1059to see whether the message will be logged. If the test succeeds it will
1060load AnyEvent::Log and call C<AnyEvent::Log::log> - consequently, look at
1059consequently, look at the L<AnyEvent::Log> documentation for details. 1061the L<AnyEvent::Log> documentation for details.
1062
1063If the test fails it will simply return.
1064
1065If you want to sprinkle loads of logging calls around your code, consider
1066creating a logger callback with the C<AnyEvent::Log::logger> function,
1067which can reduce typing, codesize and can reduce the logging overhead
1068enourmously.
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
… …
1230 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1242 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1231 1243
1232 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1244 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1233 if ${^TAINT}; 1245 if ${^TAINT};
1234 1246
1247 $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
1248 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1249
1250 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1251 if ${^TAINT};
1252
1235 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1253 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
1236} 1254}
1237 1255
1238our $MAX_SIGNAL_LATENCY = 10; 1256our $MAX_SIGNAL_LATENCY = 10;
1239 1257
… …
1279 1297
1280 () 1298 ()
1281} 1299}
1282 1300
1283sub log($$;@) { 1301sub log($$;@) {
1302 # only load the big bloated module when we actually are about to log something
1303 if ($_[0] <= $VERBOSE) { # also catches non-numeric levels(!)
1284 require AnyEvent::Log; 1304 require AnyEvent::Log;
1285 # AnyEvent::Log overwrites this function 1305 # AnyEvent::Log overwrites this function
1286 goto &log; 1306 goto &log;
1307 }
1308
1309 0 # not logged
1310}
1311
1312if (length $ENV{PERL_ANYEVENT_LOG}) {
1313 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1287} 1314}
1288 1315
1289our @models = ( 1316our @models = (
1290 [EV:: => AnyEvent::Impl::EV:: , 1], 1317 [EV:: => AnyEvent::Impl::EV:: , 1],
1291 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1318 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1],
… …
1349 1376
1350 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) { 1377 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1351 my $model = $1; 1378 my $model = $1;
1352 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//; 1379 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1353 if (eval "require $model") { 1380 if (eval "require $model") {
1381 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1354 $MODEL = $model; 1382 $MODEL = $model;
1355 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it."
1356 if $VERBOSE >= 7;
1357 } else { 1383 } else {
1358 AnyEvent::log warn => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@"; 1384 AnyEvent::log 5 => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1359 } 1385 }
1360 } 1386 }
1361 1387
1362 # check for already loaded models 1388 # check for already loaded models
1363 unless ($MODEL) { 1389 unless ($MODEL) {
1364 for (@REGISTRY, @models) { 1390 for (@REGISTRY, @models) {
1365 my ($package, $model) = @$_; 1391 my ($package, $model) = @$_;
1366 if (${"$package\::VERSION"} > 0) { 1392 if (${"$package\::VERSION"} > 0) {
1367 if (eval "require $model") { 1393 if (eval "require $model") {
1394 AnyEvent::log 7 => "autodetected model '$model', using it.";
1368 $MODEL = $model; 1395 $MODEL = $model;
1369 AnyEvent::log 7 => "autodetected model '$model', using it."
1370 if $VERBOSE >= 7;
1371 last; 1396 last;
1372 } 1397 }
1373 } 1398 }
1374 } 1399 }
1375 1400
… …
1381 $autoload 1406 $autoload
1382 and eval "require $package" 1407 and eval "require $package"
1383 and ${"$package\::VERSION"} > 0 1408 and ${"$package\::VERSION"} > 0
1384 and eval "require $model" 1409 and eval "require $model"
1385 ) { 1410 ) {
1411 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1386 $MODEL = $model; 1412 $MODEL = $model;
1387 AnyEvent::log 7 => "autoloaded model '$model', using it."
1388 if $VERBOSE >= 7;
1389 last; 1413 last;
1390 } 1414 }
1391 } 1415 }
1392 1416
1393 $MODEL 1417 $MODEL
… …
1408 if defined &{"$MODEL\::$_"}; 1432 if defined &{"$MODEL\::$_"};
1409 } 1433 }
1410 1434
1411 _isa_set; 1435 _isa_set;
1412 1436
1437 # we're officially open!
1438
1413 if ($ENV{PERL_ANYEVENT_STRICT}) { 1439 if ($ENV{PERL_ANYEVENT_STRICT}) {
1414 require AnyEvent::Strict; 1440 require AnyEvent::Strict;
1415 } 1441 }
1416 1442
1417 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) { 1443 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1418 require AnyEvent::Debug; 1444 require AnyEvent::Debug;
1419 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP}); 1445 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1420 } 1446 }
1421 1447
1422 if (exists $ENV{PERL_ANYEVENT_DEBUG_SHELL}) { 1448 if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1423 require AnyEvent::Socket; 1449 require AnyEvent::Socket;
1424 require AnyEvent::Debug; 1450 require AnyEvent::Debug;
1425 1451
1426 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL}; 1452 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1427 $shell =~ s/\$\$/$$/g; 1453 $shell =~ s/\$\$/$$/g;
1428 1454
1429 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell); 1455 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1430 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service); 1456 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
1431 } 1457 }
1458
1459 # now the anyevent environment is set up as the user told us to, so
1460 # call the actual user code - post detects
1432 1461
1433 (shift @post_detect)->() while @post_detect; 1462 (shift @post_detect)->() while @post_detect;
1434 undef @post_detect; 1463 undef @post_detect;
1435 1464
1436 *post_detect = sub(&) { 1465 *post_detect = sub(&) {
… …
1538 1567
1539sub time { 1568sub time {
1540 eval q{ # poor man's autoloading {} 1569 eval q{ # poor man's autoloading {}
1541 # probe for availability of Time::HiRes 1570 # probe for availability of Time::HiRes
1542 if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { 1571 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 () }; 1572 *time = sub { Time::HiRes::time () };
1546 *AE::time = \& Time::HiRes::time ; 1573 *AE::time = \& Time::HiRes::time ;
1574 *now = \&time;
1575 AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy.";
1547 # if (eval "use POSIX (); (POSIX::times())... 1576 # if (eval "use POSIX (); (POSIX::times())...
1548 } else { 1577 } else {
1549 AnyEvent::log critical => "using built-in time(), WARNING, no sub-second resolution!";
1550 *time = sub { CORE::time }; 1578 *time = sub { CORE::time };
1551 *AE::time = sub (){ CORE::time }; 1579 *AE::time = sub (){ CORE::time };
1580 *now = \&time;
1581 AnyEvent::log 3 => "using built-in time(), WARNING, no sub-second resolution!";
1552 } 1582 }
1553
1554 *now = \&time;
1555 }; 1583 };
1556 die if $@; 1584 die if $@;
1557 1585
1558 &time 1586 &time
1559} 1587}
… …
1652 1680
1653sub signal { 1681sub signal {
1654 eval q{ # poor man's autoloading {} 1682 eval q{ # poor man's autoloading {}
1655 # probe for availability of Async::Interrupt 1683 # probe for availability of Async::Interrupt
1656 if (_have_async_interrupt) { 1684 if (_have_async_interrupt) {
1657 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling." 1685 AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling.";
1658 if $AnyEvent::VERBOSE >= 8;
1659 1686
1660 $SIGPIPE_R = new Async::Interrupt::EventPipe; 1687 $SIGPIPE_R = new Async::Interrupt::EventPipe;
1661 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec; 1688 $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
1662 1689
1663 } else { 1690 } else {
1664 AnyEvent::log 8 => "using emulated perl signal handling with latency timer." 1691 AnyEvent::log 8 => "using emulated perl signal handling with latency timer.";
1665 if $AnyEvent::VERBOSE >= 8;
1666 1692
1667 if (AnyEvent::WIN32) { 1693 if (AnyEvent::WIN32) {
1668 require AnyEvent::Util; 1694 require AnyEvent::Util;
1669 1695
1670 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe (); 1696 ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
… …
1964$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 1990$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1965so on. 1991so on.
1966 1992
1967=head1 ENVIRONMENT VARIABLES 1993=head1 ENVIRONMENT VARIABLES
1968 1994
1969The following environment variables are used by this module or its 1995AnyEvent supports a number of environment variables that tune the
1970submodules. 1996runtime behaviour. They are usually evaluated when AnyEvent is
1997loaded, initialised, or a submodule that uses them is loaded. Many of
1998them also cause AnyEvent to load additional modules - for example,
1999C<PERL_ANYEVENT_DEBUG_WRAP> causes the L<AnyEvent::Debug> module to be
2000loaded.
1971 2001
1972Note that AnyEvent will remove I<all> environment variables starting with 2002All the environment variables documented here start with
1973C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 2003C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1974enabled. 2004namespace. Other modules are encouraged (but by no means required) to use
2005C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
2006namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
2007be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
2008variables starting with C<AE_>, see below).
2009
2010All variables can also be set via the C<AE_> prefix, that is, instead
2011of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
2012case there is a clash btween anyevent and another program that uses
2013C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
2014variable to the empty string, as those variables take precedence.
2015
2016When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
2017to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
2018exists. If taint mode is on, then AnyEvent will remove I<all> environment
2019variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
2020with C<undef> or the empty string, if the corresaponding C<AE_> variable
2021is set).
2022
2023The exact algorithm is currently:
2024
2025 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
2026 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
2027 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
2028
2029This ensures that child processes will not see the C<AE_> variables.
2030
2031The following environment variables are currently known to AnyEvent:
1975 2032
1976=over 4 2033=over 4
1977 2034
1978=item C<PERL_ANYEVENT_VERBOSE> 2035=item C<PERL_ANYEVENT_VERBOSE>
1979 2036
1980By default, AnyEvent will be completely silent except in fatal 2037By default, AnyEvent will be completely silent except in fatal
1981conditions. You can set this environment variable to make AnyEvent more 2038conditions. You can set this environment variable to make AnyEvent more
1982talkative. 2039talkative. If you want to do more than just set the global logging level
2040you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
2041complex specifications.
1983 2042
1984When set to C<5> or higher, causes AnyEvent to warn about unexpected 2043When set to C<5> or higher (warn), causes AnyEvent to warn about unexpected
1985conditions, such as not being able to load the event model specified by 2044conditions, such as not being able to load the event model specified by
1986C<PERL_ANYEVENT_MODEL>. 2045C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an exception - this
2046is the minimum recommended level.
1987 2047
1988When set to C<7> or higher, cause AnyEvent to report to STDERR which event 2048When set to C<7> or higher (info), cause AnyEvent to report which event model it
1989model it chooses. 2049chooses.
1990 2050
1991When set to C<8> or higher, then AnyEvent will report extra information on 2051When 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. 2052which optional modules it loads and how it implements certain features.
2053
2054=item C<PERL_ANYEVENT_LOG>
2055
2056Accepts rather complex logging specifications. For example, you could log
2057all C<debug> messages of some module to stderr, warnings and above to
2058stderr, and errors and above to syslog, with:
2059
2060 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
2061
2062For the rather extensive details, see L<AnyEvent::Log>.
2063
2064This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
2065so will take effect even before AnyEvent has initialised itself.
2066
2067Note that specifying this environment variable causes the L<AnyEvent::Log>
2068module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
2069using the latter saves a few hundred kB of memory until the first message
2070is being logged.
1993 2071
1994=item C<PERL_ANYEVENT_STRICT> 2072=item C<PERL_ANYEVENT_STRICT>
1995 2073
1996AnyEvent does not do much argument checking by default, as thorough 2074AnyEvent does not do much argument checking by default, as thorough
1997argument checking is very costly. Setting this variable to a true value 2075argument checking is very costly. Setting this variable to a true value
… …
2011If this env variable is set, then its contents will be interpreted by 2089If this env variable is set, then its contents will be interpreted by
2012C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of 2090C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of
2013C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on 2091C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on
2014that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>. 2092that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>.
2015 2093
2016This takes place when the first watcher is created. 2094This happens when the first watcher is created.
2017 2095
2018For example, to bind a debug shell on a unix domain socket in 2096For example, to bind a debug shell on a unix domain socket in
2019F<< /tmp/debug<pid>.sock >>, you could use this: 2097F<< /tmp/debug<pid>.sock >>, you could use this:
2020 2098
2021 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog 2099 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
… …
2067but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4> 2145but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
2068- only support IPv4, never try to resolve or contact IPv6 2146- only support IPv4, never try to resolve or contact IPv6
2069addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2147addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
2070IPv6, but prefer IPv6 over IPv4. 2148IPv6, but prefer IPv6 over IPv4.
2071 2149
2150=item C<PERL_ANYEVENT_HOSTS>
2151
2152This variable, if specified, overrides the F</etc/hosts> file used by
2153L<AnyEvent::Socket>C<::resolve_sockaddr>, i.e. hosts aliases will be read
2154from that file instead.
2155
2072=item C<PERL_ANYEVENT_EDNS0> 2156=item C<PERL_ANYEVENT_EDNS0>
2073 2157
2074Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension 2158Used 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 2159DNS. This extension is generally useful to reduce DNS traffic, especially
2076some (broken) firewalls drop such DNS packets, which is why it is off by 2160when DNSSEC is involved, but some (broken) firewalls drop such DNS
2077default. 2161packets, which is why it is off by default.
2078 2162
2079Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 2163Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
2080EDNS0 in its DNS requests. 2164EDNS0 in its DNS requests.
2081 2165
2082=item C<PERL_ANYEVENT_MAX_FORKS> 2166=item C<PERL_ANYEVENT_MAX_FORKS>
… …
2090resolver - this is the maximum number of parallel DNS requests that are 2174resolver - this is the maximum number of parallel DNS requests that are
2091sent to the DNS server. 2175sent to the DNS server.
2092 2176
2093=item C<PERL_ANYEVENT_RESOLV_CONF> 2177=item C<PERL_ANYEVENT_RESOLV_CONF>
2094 2178
2095The file to use instead of F</etc/resolv.conf> (or OS-specific 2179The 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 2180F</etc/resolv.conf> (or the OS-specific configuration) in the default
2097default config will be used. 2181resolver, or the empty string to select the default configuration.
2098 2182
2099=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2183=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
2100 2184
2101When neither C<ca_file> nor C<ca_path> was specified during 2185When neither C<ca_file> nor C<ca_path> was specified during
2102L<AnyEvent::TLS> context creation, and either of these environment 2186L<AnyEvent::TLS> context creation, and either of these environment
2103variables exist, they will be used to specify CA certificate locations 2187variables are nonempty, they will be used to specify CA certificate
2104instead of a system-dependent default. 2188locations instead of a system-dependent default.
2105 2189
2106=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT> 2190=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
2107 2191
2108When these are set to C<1>, then the respective modules are not 2192When these are set to C<1>, then the respective modules are not
2109loaded. Mostly good for testing AnyEvent itself. 2193loaded. Mostly good for testing AnyEvent itself.

Diff Legend

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