--- AnyEvent/lib/AnyEvent.pm	2011/08/17 02:14:17	1.367
+++ AnyEvent/lib/AnyEvent.pm	2011/08/25 03:08:48	1.373
@@ -2,8 +2,8 @@
 
 AnyEvent - the DBI of event loop programming
 
-EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt
-and POE are various supported event loops/environments.
+EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt,
+FLTK and POE are various supported event loops/environments.
 
 =head1 SYNOPSIS
 
@@ -1059,7 +1059,7 @@
 consequently, look at the L<AnyEvent::Log> documentation for details.
 
 If you want to sprinkle loads of logging calls around your code, consider
-creating a logger callback with the C<AnyEvent::Log::logger< function.
+creating a logger callback with the C<AnyEvent::Log::logger> function.
 
 =back
 
@@ -1126,9 +1126,12 @@
 =head1 OTHER MODULES
 
 The following is a non-exhaustive list of additional modules that use
-AnyEvent as a client and can therefore be mixed easily with other AnyEvent
-modules and other event loops in the same program. Some of the modules
-come as part of AnyEvent, the others are available via CPAN.
+AnyEvent as a client and can therefore be mixed easily with other
+AnyEvent modules and other event loops in the same program. Some of the
+modules come as part of AnyEvent, the others are available via CPAN (see
+L<http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for
+a longer non-exhaustive list), and the list is heavily biased towards
+modules of the AnyEvent author himself :)
 
 =over 4
 
@@ -1235,6 +1238,12 @@
    delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV}
       if ${^TAINT};
 
+   $ENV{"PERL_ANYEVENT_$_"} = $ENV{"AE_$_"}
+      for grep s/^AE_// && !exists $ENV{"PERL_ANYEVENT_$_"}, keys %ENV;
+
+   @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} = ()
+      if ${^TAINT};
+
    $VERBOSE = $ENV{PERL_ANYEVENT_VERBOSE}*1;
 }
 
@@ -1284,9 +1293,16 @@
 }
 
 sub log($$;@) {
-   require AnyEvent::Log;
-   # AnyEvent::Log overwrites this function
-   goto &log;
+   # only load the bug bloated module when we actually are about to log something
+   if ($_[0] <= $VERBOSE) {
+      require AnyEvent::Log;
+      # AnyEvent::Log overwrites this function
+      goto &log;
+   }
+}
+
+if (length $ENV{PERL_ANYEVENT_LOG}) {
+   require AnyEvent::Log; # AnyEvent::Log does the thing for us
 }
 
 our @models = (
@@ -1354,9 +1370,8 @@
       my $model = $1;
       $model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
       if (eval "require $model") {
+         AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
          $MODEL = $model;
-         AnyEvent::log 7 => "loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it."
-            if $VERBOSE >= 7;
       } else {
          AnyEvent::log warn => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
       }
@@ -1368,9 +1383,8 @@
          my ($package, $model) = @$_;
          if (${"$package\::VERSION"} > 0) {
             if (eval "require $model") {
+               AnyEvent::log 7 => "autodetected model '$model', using it.";
                $MODEL = $model;
-               AnyEvent::log 7 => "autodetected model '$model', using it."
-                  if $VERBOSE >= 7;
                last;
             }
          }
@@ -1386,9 +1400,8 @@
                and ${"$package\::VERSION"} > 0
                and eval "require $model"
             ) {
+               AnyEvent::log 7 => "autoloaded model '$model', using it.";
                $MODEL = $model;
-               AnyEvent::log 7 => "autoloaded model '$model', using it."
-                  if $VERBOSE >= 7;
                last;
             }
          }
@@ -1974,12 +1987,43 @@
 
 =head1 ENVIRONMENT VARIABLES
 
-The following environment variables are used by this module or its
-submodules.
+AnyEvent supports a number of environment variables that tune the
+runtime behaviour. They are usually evaluated when AnyEvent is
+loaded, initialised, or a submodule that uses them is loaded. Many of
+them also cause AnyEvent to load additional modules - for example,
+C<PERL_ANYEVENT_DEBUG_WRAP> causes the L<AnyEvent::Debug> module to be
+loaded.
+
+All the environment variables documented here start with
+C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
+namespace. Other modules are encouraged (but by no means required) to use
+C<PERL_ANYEVENT_SUBMODULE> if they have registered the AnyEvent::Submodule
+namespace on CPAN, for any submodule. For example, L<AnyEvent::HTTP> could
+be expected to use C<PERL_ANYEVENT_HTTP_PROXY> (it should not access env
+variables starting with C<AE_>, see below).
+
+All variables can also be set via the C<AE_> prefix, that is, instead
+of setting C<PERL_ANYEVENT_VERBOSE> you can also set C<AE_VERBOSE>. In
+case there is a clash btween anyevent and another program that uses
+C<AE_something> you can set the corresponding C<PERL_ANYEVENT_something>
+variable to the empty string, as those variables take precedence.
+
+When AnyEvent is first loaded, it copies all C<AE_xxx> env variables
+to their C<PERL_ANYEVENT_xxx> counterpart unless that variable already
+exists. If taint mode is on, then AnyEvent will remove I<all> environment
+variables starting with C<PERL_ANYEVENT_> from C<%ENV> (or replace them
+with C<undef> or the empty string, if the corresaponding C<AE_> variable
+is set).
+
+The exact algorithm is currently:
+
+   1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
+   2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
+   3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
+
+This ensures that child processes will not see the C<AE_> variables.
 
-Note that AnyEvent will remove I<all> environment variables starting with
-C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is
-enabled.
+The following environment variables are currently known to AnyEvent:
 
 =over 4
 
@@ -1987,7 +2031,9 @@
 
 By default, AnyEvent will be completely silent except in fatal
 conditions. You can set this environment variable to make AnyEvent more
-talkative.
+talkative. If you want to do more than just set the global logging level
+you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
+complex specifications.
 
 When set to C<5> or higher, causes AnyEvent to warn about unexpected
 conditions, such as not being able to load the event model specified by
@@ -1999,6 +2045,21 @@
 When set to C<8> or higher, then AnyEvent will report extra information on
 which optional modules it loads and how it implements certain features.
 
+=item C<PERL_ANYEVENT_LOG>
+
+Accepts rather complex logging specifications. For example, you could log
+all C<debug> messages of some module to stderr, warnings and above to
+stderr, and errors and above to syslog, with:
+
+   PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
+
+For the rather extensive details, see L<AnyEvent::Log>.
+
+Note that specifying this environment variable causes the L<AnyEvent::Log>
+module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
+using the latter saves a few hundred kB of memory until the first message
+is being logged.
+
 =item C<PERL_ANYEVENT_STRICT>
 
 AnyEvent does not do much argument checking by default, as thorough
@@ -2077,12 +2138,18 @@
 addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
 IPv6, but prefer IPv6 over IPv4.
 
+=item C<PERL_ANYEVENT_HOSTS>
+
+This variable, if specified, overrides the F</etc/hosts> file used by
+L<AnyEvent::Socket>C<::resolve_sockaddr>, i.e. hosts aliases will be read
+from that file instead.
+
 =item C<PERL_ANYEVENT_EDNS0>
 
-Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension
-for DNS. This extension is generally useful to reduce DNS traffic, but
-some (broken) firewalls drop such DNS packets, which is why it is off by
-default.
+Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension for
+DNS. This extension is generally useful to reduce DNS traffic, especially
+when DNSSEC is involved, but some (broken) firewalls drop such DNS
+packets, which is why it is off by default.
 
 Setting this variable to C<1> will cause L<AnyEvent::DNS> to announce
 EDNS0 in its DNS requests.
@@ -2100,16 +2167,16 @@
 
 =item C<PERL_ANYEVENT_RESOLV_CONF>
 
-The file to use instead of F</etc/resolv.conf> (or OS-specific
-configuration) in the default resolver. When set to the empty string, no
-default config will be used.
+The absolute path to a F<resolv.conf>-style file to use instead of
+F</etc/resolv.conf> (or the OS-specific configuration) in the default
+resolver, or the empty string to select the default configuration.
 
 =item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
 
 When neither C<ca_file> nor C<ca_path> was specified during
 L<AnyEvent::TLS> context creation, and either of these environment
-variables exist, they will be used to specify CA certificate locations
-instead of a system-dependent default.
+variables are nonempty, they will be used to specify CA certificate
+locations instead of a system-dependent default.
 
 =item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>