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.371 by root, Wed Aug 24 23:59:10 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
… …
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> - 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
1062creating a logger callback with the C<AnyEvent::Log::logger> function.
1063
1061=back 1064=back
1062 1065
1063=head1 WHAT TO DO IN A MODULE 1066=head1 WHAT TO DO IN A MODULE
1064 1067
1065As a module author, you should C<use AnyEvent> and call AnyEvent methods 1068As a module author, you should C<use AnyEvent> and call AnyEvent methods
… …
1121 1124
1122 1125
1123=head1 OTHER MODULES 1126=head1 OTHER MODULES
1124 1127
1125The following is a non-exhaustive list of additional modules that use 1128The following is a non-exhaustive list of additional modules that use
1126AnyEvent as a client and can therefore be mixed easily with other AnyEvent 1129AnyEvent as a client and can therefore be mixed easily with other
1127modules 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
1128come 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 :)
1129 1135
1130=over 4 1136=over 4
1131 1137
1132=item L<AnyEvent::Util> 1138=item L<AnyEvent::Util>
1133 1139
… …
1228 require "AnyEvent/constants.pl"; 1234 require "AnyEvent/constants.pl";
1229 1235
1230 eval "sub TAINT (){" . (${^TAINT}*1) . "}"; 1236 eval "sub TAINT (){" . (${^TAINT}*1) . "}";
1231 1237
1232 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} 1238 delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
1239 if ${^TAINT};
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} = ()
1233 if ${^TAINT}; 1245 if ${^TAINT};
1234 1246
1235 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1; 1247 $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
1236} 1248}
1237 1249
… …
1408 if defined &{"$MODEL\::$_"}; 1420 if defined &{"$MODEL\::$_"};
1409 } 1421 }
1410 1422
1411 _isa_set; 1423 _isa_set;
1412 1424
1425 # we're officially open!
1426
1427 if (length $ENV{PERL_ANYEVENT_LOG}) {
1428 require AnyEvent::Log; # AnyEvent::Log does the thing for us
1429 }
1430
1413 if ($ENV{PERL_ANYEVENT_STRICT}) { 1431 if ($ENV{PERL_ANYEVENT_STRICT}) {
1414 require AnyEvent::Strict; 1432 require AnyEvent::Strict;
1415 } 1433 }
1416 1434
1417 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) { 1435 if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
1418 require AnyEvent::Debug; 1436 require AnyEvent::Debug;
1419 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP}); 1437 AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
1420 } 1438 }
1421 1439
1422 if (exists $ENV{PERL_ANYEVENT_DEBUG_SHELL}) { 1440 if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
1423 require AnyEvent::Socket; 1441 require AnyEvent::Socket;
1424 require AnyEvent::Debug; 1442 require AnyEvent::Debug;
1425 1443
1426 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL}; 1444 my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
1427 $shell =~ s/\$\$/$$/g; 1445 $shell =~ s/\$\$/$$/g;
1428 1446
1429 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell); 1447 my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
1430 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service); 1448 $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
1431 } 1449 }
1450
1451 # now the anyevent environment is set up as the user told us to, so
1452 # call the actual user code - post detects
1432 1453
1433 (shift @post_detect)->() while @post_detect; 1454 (shift @post_detect)->() while @post_detect;
1434 undef @post_detect; 1455 undef @post_detect;
1435 1456
1436 *post_detect = sub(&) { 1457 *post_detect = sub(&) {
… …
1964$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and 1985$Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
1965so on. 1986so on.
1966 1987
1967=head1 ENVIRONMENT VARIABLES 1988=head1 ENVIRONMENT VARIABLES
1968 1989
1969The following environment variables are used by this module or its 1990AnyEvent supports a number of environment variables that tune the
1970submodules. 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.
1971 1996
1972Note that AnyEvent will remove I<all> environment variables starting with 1997All the environment variables documented here start with
1973C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is 1998C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
1974enabled. 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:
1975 2027
1976=over 4 2028=over 4
1977 2029
1978=item C<PERL_ANYEVENT_VERBOSE> 2030=item C<PERL_ANYEVENT_VERBOSE>
1979 2031
1980By default, AnyEvent will be completely silent except in fatal 2032By default, AnyEvent will be completely silent except in fatal
1981conditions. You can set this environment variable to make AnyEvent more 2033conditions. You can set this environment variable to make AnyEvent more
1982talkative. 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.
1983 2037
1984When 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
1985conditions, 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
1986C<PERL_ANYEVENT_MODEL>. 2040C<PERL_ANYEVENT_MODEL>.
1987 2041
1988When 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
1989model it chooses. 2043model it chooses.
1990 2044
1991When 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
1992which 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.
1993 2062
1994=item C<PERL_ANYEVENT_STRICT> 2063=item C<PERL_ANYEVENT_STRICT>
1995 2064
1996AnyEvent does not do much argument checking by default, as thorough 2065AnyEvent does not do much argument checking by default, as thorough
1997argument checking is very costly. Setting this variable to a true value 2066argument checking is very costly. Setting this variable to a true value
… …
2069addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or 2138addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
2070IPv6, but prefer IPv6 over IPv4. 2139IPv6, but prefer IPv6 over IPv4.
2071 2140
2072=item C<PERL_ANYEVENT_EDNS0> 2141=item C<PERL_ANYEVENT_EDNS0>
2073 2142
2074Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension 2143Used 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 2144DNS. This extension is generally useful to reduce DNS traffic, especially
2076some (broken) firewalls drop such DNS packets, which is why it is off by 2145when DNSSEC is involved, but some (broken) firewalls drop such DNS
2077default. 2146packets, which is why it is off by default.
2078 2147
2079Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce 2148Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
2080EDNS0 in its DNS requests. 2149EDNS0 in its DNS requests.
2081 2150
2082=item C<PERL_ANYEVENT_MAX_FORKS> 2151=item C<PERL_ANYEVENT_MAX_FORKS>
… …
2090resolver - this is the maximum number of parallel DNS requests that are 2159resolver - this is the maximum number of parallel DNS requests that are
2091sent to the DNS server. 2160sent to the DNS server.
2092 2161
2093=item C<PERL_ANYEVENT_RESOLV_CONF> 2162=item C<PERL_ANYEVENT_RESOLV_CONF>
2094 2163
2095The file to use instead of F</etc/resolv.conf> (or OS-specific 2164The 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 2165F</etc/resolv.conf> (or the OS-specific configuration) in the default
2097default config will be used. 2166resolver, or the empty string to select the default configuration.
2098 2167
2099=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>. 2168=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
2100 2169
2101When neither C<ca_file> nor C<ca_path> was specified during 2170When neither C<ca_file> nor C<ca_path> was specified during
2102L<AnyEvent::TLS> context creation, and either of these environment 2171L<AnyEvent::TLS> context creation, and either of these environment
2103variables exist, they will be used to specify CA certificate locations 2172variables are nonempty, they will be used to specify CA certificate
2104instead of a system-dependent default. 2173locations instead of a system-dependent default.
2105 2174
2106=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT> 2175=item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
2107 2176
2108When these are set to C<1>, then the respective modules are not 2177When these are set to C<1>, then the respective modules are not
2109loaded. Mostly good for testing AnyEvent itself. 2178loaded. Mostly good for testing AnyEvent itself.

Diff Legend

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