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.367 by root, Wed Aug 17 02:14:17 2011 UTC vs.
Revision 1.373 by root, Thu Aug 25 03:08:48 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
… …
1057 1057
1058Loads AnyEvent::Log on first use and calls C<AnyEvent::Log::log> - 1058Loads AnyEvent::Log on first use and calls C<AnyEvent::Log::log> -
1059consequently, look at the L<AnyEvent::Log> documentation for details. 1059consequently, look at the L<AnyEvent::Log> documentation for details.
1060 1060
1061If you want to sprinkle loads of logging calls around your code, consider 1061If you want to sprinkle loads of logging calls around your code, consider
1062creating a logger callback with the C<AnyEvent::Log::logger< function. 1062creating a logger callback with the C<AnyEvent::Log::logger> function.
1063 1063
1064=back 1064=back
1065 1065
1066=head1 WHAT TO DO IN A MODULE 1066=head1 WHAT TO DO IN A MODULE
1067 1067
… …
1124 1124
1125 1125
1126=head1 OTHER MODULES 1126=head1 OTHER MODULES
1127 1127
1128The following is a non-exhaustive list of additional modules that use 1128The following is a non-exhaustive list of additional modules that use
1129AnyEvent as a client and can therefore be mixed easily with other AnyEvent 1129AnyEvent as a client and can therefore be mixed easily with other
1130modules and other event loops in the same program. Some of the modules 1130AnyEvent modules and other event loops in the same program. Some of the
1131come as part of AnyEvent, the others are available via CPAN. 1131modules come as part of AnyEvent, the others are available via CPAN (see
1132L<http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for
1133a longer non-exhaustive list), and the list is heavily biased towards
1134modules of the AnyEvent author himself :)
1132 1135
1133=over 4 1136=over 4
1134 1137
1135=item L<AnyEvent::Util> 1138=item L<AnyEvent::Util>
1136 1139
… …
1233 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1236 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1234 1237
1235 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1238 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1236 if ${^TAINT}; 1239 if ${^TAINT};
1237 1240
1241 $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
1242 for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
1243
1244 @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
1245 if ${^TAINT};
1246
1238 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1247 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
1239} 1248}
1240 1249
1241our $MAX_SIGNAL_LATENCY = 10; 1250our $MAX_SIGNAL_LATENCY = 10;
1242 1251
… …
1282 1291
1283 () 1292 ()
1284} 1293}
1285 1294
1286sub log($$;@) { 1295sub log($$;@) {
1296 # only load the bug bloated module when we actually are about to log something
1297 if ($_[0] <= $VERBOSE) {
1287 require AnyEvent::Log; 1298 require AnyEvent::Log;
1288 # AnyEvent::Log overwrites this function 1299 # AnyEvent::Log overwrites this function
1289 goto &log; 1300 goto &log;
1301 }
1302}
1303
1304if (length $ENV{PERL_ANYEVENT_LOG}) {
1305 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1290} 1306}
1291 1307
1292our @models = ( 1308our @models = (
1293 [EV:: => AnyEvent::Impl::EV:: , 1], 1309 [EV:: => AnyEvent::Impl::EV:: , 1],
1294 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1], 1310 [AnyEvent::Loop:: => AnyEvent::Impl::Perl:: , 1],
… …
1352 1368
1353 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) { 1369 if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
1354 my $model = $1; 1370 my $model = $1;
1355 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//; 1371 $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
1356 if (eval "require $model") { 1372 if (eval "require $model") {
1373 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
1357 $MODEL = $model; 1374 $MODEL = $model;
1358 AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it."
1359 if $VERBOSE >= 7;
1360 } else { 1375 } else {
1361 AnyEvent::log warn => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@"; 1376 AnyEvent::log warn => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
1362 } 1377 }
1363 } 1378 }
1364 1379
… …
1366 unless ($MODEL) { 1381 unless ($MODEL) {
1367 for (@REGISTRY, @models) { 1382 for (@REGISTRY, @models) {
1368 my ($package, $model) = @$_; 1383 my ($package, $model) = @$_;
1369 if (${"$package\::VERSION"} > 0) { 1384 if (${"$package\::VERSION"} > 0) {
1370 if (eval "require $model") { 1385 if (eval "require $model") {
1386 AnyEvent::log 7 => "autodetected model '$model', using it.";
1371 $MODEL = $model; 1387 $MODEL = $model;
1372 AnyEvent::log 7 => "autodetected model '$model', using it."
1373 if $VERBOSE >= 7;
1374 last; 1388 last;
1375 } 1389 }
1376 } 1390 }
1377 } 1391 }
1378 1392
… …
1384 $autoload 1398 $autoload
1385 and eval "require $package" 1399 and eval "require $package"
1386 and ${"$package\::VERSION"} > 0 1400 and ${"$package\::VERSION"} > 0
1387 and eval "require $model" 1401 and eval "require $model"
1388 ) { 1402 ) {
1403 AnyEvent::log 7 => "autoloaded model '$model', using it.";
1389 $MODEL = $model; 1404 $MODEL = $model;
1390 AnyEvent::log 7 => "autoloaded model '$model', using it."
1391 if $VERBOSE >= 7;
1392 last; 1405 last;
1393 } 1406 }
1394 } 1407 }
1395 1408
1396 $MODEL 1409 $MODEL
… …
1972$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 1985$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1973so on. 1986so on.
1974 1987
1975=head1 ENVIRONMENT VARIABLES 1988=head1 ENVIRONMENT VARIABLES
1976 1989
1977The following environment variables are used by this module or its 1990AnyEvent supports a number of environment variables that tune the
1978submodules. 1991runtime behaviour. They are usually evaluated when AnyEvent is
1992loaded, initialised, or a submodule that uses them is loaded. Many of
1993them also cause AnyEvent to load additional modules - for example,
1994C<PERL_ANYEVENT_DEBUG_WRAP> causes the L<AnyEvent::Debug> module to be
1995loaded.
1979 1996
1980Note that AnyEvent will remove I<all> environment variables starting with 1997All the environment variables documented here start with
1981C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 1998C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1982enabled. 1999namespace. Other modules are encouraged (but by no means required) to use
2000C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
2001namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
2002be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
2003variables starting with C<AE_>, see below).
2004
2005All variables can also be set via the C<AE_> prefix, that is, instead
2006of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
2007case there is a clash btween anyevent and another program that uses
2008C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
2009variable to the empty string, as those variables take precedence.
2010
2011When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
2012to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
2013exists. If taint mode is on, then AnyEvent will remove I<all> environment
2014variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
2015with C<undef> or the empty string, if the corresaponding C<AE_> variable
2016is set).
2017
2018The exact algorithm is currently:
2019
2020 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
2021 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
2022 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
2023
2024This ensures that child processes will not see the C<AE_> variables.
2025
2026The following environment variables are currently known to AnyEvent:
1983 2027
1984=over 4 2028=over 4
1985 2029
1986=item C<PERL_ANYEVENT_VERBOSE> 2030=item C<PERL_ANYEVENT_VERBOSE>
1987 2031
1988By default, AnyEvent will be completely silent except in fatal 2032By default, AnyEvent will be completely silent except in fatal
1989conditions. You can set this environment variable to make AnyEvent more 2033conditions. You can set this environment variable to make AnyEvent more
1990talkative. 2034talkative. If 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
2036complex specifications.
1991 2037
1992When set to C<5> or higher, causes AnyEvent to warn about unexpected 2038When set to C<5> or higher, causes AnyEvent to warn about unexpected
1993conditions, such as not being able to load the event model specified by 2039conditions, such as not being able to load the event model specified by
1994C<PERL_ANYEVENT_MODEL>. 2040C<PERL_ANYEVENT_MODEL>.
1995 2041
1996When set to C<7> or higher, cause AnyEvent to report to STDERR which event 2042When set to C<7> or higher, cause AnyEvent to report to STDERR which event
1997model it chooses. 2043model it chooses.
1998 2044
1999When set to C<8> or higher, then AnyEvent will report extra information on 2045When set to C<8> or higher, then AnyEvent will report extra information on
2000which optional modules it loads and how it implements certain features. 2046which optional modules it loads and how it implements certain features.
2047
2048=item C<PERL_ANYEVENT_LOG>
2049
2050Accepts rather complex logging specifications. For example, you could log
2051all C<debug> messages of some module to stderr, warnings and above to
2052stderr, and errors and above to syslog, with:
2053
2054 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
2055
2056For the rather extensive details, see L<AnyEvent::Log>.
2057
2058Note that specifying this environment variable causes the L<AnyEvent::Log>
2059module 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
2061is being logged.
2001 2062
2002=item C<PERL_ANYEVENT_STRICT> 2063=item C<PERL_ANYEVENT_STRICT>
2003 2064
2004AnyEvent does not do much argument checking by default, as thorough 2065AnyEvent does not do much argument checking by default, as thorough
2005argument checking is very costly. Setting this variable to a true value 2066argument checking is very costly. Setting this variable to a true value
… …
2075but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4> 2136but support both and try to use both. C<PERL_ANYEVENT_PROTOCOLS=ipv4>
2076- only support IPv4, never try to resolve or contact IPv6 2137- only support IPv4, never try to resolve or contact IPv6
2077addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2138addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
2078IPv6, but prefer IPv6 over IPv4. 2139IPv6, but prefer IPv6 over IPv4.
2079 2140
2141=item C<PERL_ANYEVENT_HOSTS>
2142
2143This variable, if specified, overrides the F</etc/hosts> file used by
2144L<AnyEvent::Socket>C<::resolve_sockaddr>, i.e. hosts aliases will be read
2145from that file instead.
2146
2080=item C<PERL_ANYEVENT_EDNS0> 2147=item C<PERL_ANYEVENT_EDNS0>
2081 2148
2082Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension 2149Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension for
2083for DNS. This extension is generally useful to reduce DNS traffic, but 2150DNS. This extension is generally useful to reduce DNS traffic, especially
2084some (broken) firewalls drop such DNS packets, which is why it is off by 2151when DNSSEC is involved, but some (broken) firewalls drop such DNS
2085default. 2152packets, which is why it is off by default.
2086 2153
2087Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 2154Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
2088EDNS0 in its DNS requests. 2155EDNS0 in its DNS requests.
2089 2156
2090=item C<PERL_ANYEVENT_MAX_FORKS> 2157=item C<PERL_ANYEVENT_MAX_FORKS>
… …
2098resolver - this is the maximum number of parallel DNS requests that are 2165resolver - this is the maximum number of parallel DNS requests that are
2099sent to the DNS server. 2166sent to the DNS server.
2100 2167
2101=item C<PERL_ANYEVENT_RESOLV_CONF> 2168=item C<PERL_ANYEVENT_RESOLV_CONF>
2102 2169
2103The file to use instead of F</etc/resolv.conf> (or OS-specific 2170The absolute path to a F<resolv.conf>-style file to use instead of
2104configuration) in the default resolver. When set to the empty string, no 2171F</etc/resolv.conf> (or the OS-specific configuration) in the default
2105default config will be used. 2172resolver, or the empty string to select the default configuration.
2106 2173
2107=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2174=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
2108 2175
2109When neither C<ca_file> nor C<ca_path> was specified during 2176When neither C<ca_file> nor C<ca_path> was specified during
2110L<AnyEvent::TLS> context creation, and either of these environment 2177L<AnyEvent::TLS> context creation, and either of these environment
2111variables exist, they will be used to specify CA certificate locations 2178variables are nonempty, they will be used to specify CA certificate
2112instead of a system-dependent default. 2179locations instead of a system-dependent default.
2113 2180
2114=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT> 2181=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
2115 2182
2116When these are set to C<1>, then the respective modules are not 2183When these are set to C<1>, then the respective modules are not
2117loaded. Mostly good for testing AnyEvent itself. 2184loaded. Mostly good for testing AnyEvent itself.

Diff Legend

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