[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent.pm

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.365 by root, Tue Aug 16 14:47:26 2011 UTC vs.
Revision 1.377 by root, Thu Aug 25 23:20:17 2011 UTC

 =head1 NAME
 AnyEvent - the DBI of event loop programming
-EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt
+EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, Qt,
-and POE are various supported event loops/environments.
+FLTK and POE are various supported event loops/environments.
 =head1 SYNOPSIS
    use AnyEvent;
 =item AnyEvent::log $level, $msg[, @args]
 Log the given C<$msg> at the given C<$level>.
-Loads AnyEvent::Log on first use and calls C<AnyEvent::Log::log> -
+If L<AnyEvent::Log> is not loaded then this function makes a simple test
+to see whether the message will be logged. If the test succeeds it will
+load AnyEvent::Log and call C<AnyEvent::Log::log> - consequently, look at
-consequently, look at the L<AnyEvent::Log> documentation for details.
+the L<AnyEvent::Log> documentation for details.
+If the test fails it will simply return.
+If you want to sprinkle loads of logging calls around your code, consider
+creating a logger callback with the C<AnyEvent::Log::logger> function,
+which can reduce typing, codesize and can reduce the logging overhead
+enourmously.
 =back
 =head1 WHAT TO DO IN A MODULE
 =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
+AnyEvent as a client and can therefore be mixed easily with other
-modules and other event loops in the same program. Some of the modules
+AnyEvent modules and other event loops in the same program. Some of the
-come as part of AnyEvent, the others are available via CPAN.
+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
 =item L<AnyEvent::Util>
 =item L<AnyEvent::HTTP>, L<AnyEvent::IRC>, L<AnyEvent::XMPP>, L<AnyEvent::GPSD>, L<AnyEvent::IGS>, L<AnyEvent::FCP>
 Implement event-based interfaces to the protocols of the same name (for
 the curious, IGS is the International Go Server and FCP is the Freenet
 Client Protocol).
-=item L<AnyEvent::Handle::UDP>
-Here be danger!
-As Pauli would put it, "Not only is it not right, it's not even wrong!" -
-there are so many things wrong with AnyEvent::Handle::UDP, most notably
-its use of a stream-based API with a protocol that isn't streamable, that
-the only way to improve it is to delete it.
-It features data corruption (but typically only under load) and general
-confusion. On top, the author is not only clueless about UDP but also
-fact-resistant - some gems of his understanding: "connect doesn't work
-with UDP", "UDP packets are not IP packets", "UDP only has datagrams, not
-packets", "I don't need to implement proper error checking as UDP doesn't
-support error checking" and so on - he doesn't even understand what's
-wrong with his module when it is explained to him.
-=item L<AnyEvent::DBI>
-Executes L<DBI> requests asynchronously in a proxy process for you,
-notifying you in an event-based way when the operation is finished.
 =item L<AnyEvent::AIO>
 Truly asynchronous (as opposed to non-blocking) I/O, should be in the
 toolbox of every event programmer. AnyEvent::AIO transparently fuses
 L<IO::AIO> and AnyEvent together, giving AnyEvent access to event-based
 file I/O, and much more.
+=item L<AnyEvent::Filesys::Notify>
+AnyEvent is good for non-blocking stuff, but it can't detect file or
+path changes (e.g. "watch this directory for new files", "watch this
+file for changes"). The L<AnyEvent::Filesys::Notify> module promises to
+do just that in a portbale fashion, supporting inotify on GNU/Linux and
+some weird, without doubt broken, stuff on OS X to monitor files. It can
+fall back to blocking scans at regular intervals transparently on other
+platforms, so it's about as portable as it gets.
+(I haven't used it myself, but I haven't heard anybody complaining about
+it yet).
+=item L<AnyEvent::DBI>
+Executes L<DBI> requests asynchronously in a proxy process for you,
+notifying you in an event-based way when the operation is finished.
 =item L<AnyEvent::HTTPD>
 A simple embedded webserver.
 =item L<AnyEvent::FastPing>
 The fastest ping in the west.
 =item L<Coro>
-Has special support for AnyEvent via L<Coro::AnyEvent>.
+Has special support for AnyEvent via L<Coro::AnyEvent>, which allows you
+to simply invert the flow control - don't call us, we will call you:
+   async {
+      Coro::AnyEvent::sleep 5; # creates a 5s timer and waits for it
+      print "5 seconds later!\n";
+      Coro::AnyEvent::readable *STDIN; # uses an I/O watcher
+      my $line = <STDIN>; # works for ttys
+      AnyEvent::HTTP::http_get "url", Coro::rouse_cb;
+      my ($body, $hdr) = Coro::rouse_wait;
+   };
 =back
 =cut
    eval "sub TAINT (){" . (${^TAINT}*1) . "}";
    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;
 }
 our $MAX_SIGNAL_LATENCY = 10;
    ()
 }
 sub log($$;@) {
+   # only load the big bloated module when we actually are about to log something
+   if ($_[0] <= $VERBOSE) { # also catches non-numeric levels(!)
-   require AnyEvent::Log;
+      require AnyEvent::Log;
-   # AnyEvent::Log overwrites this function
+      # AnyEvent::Log overwrites this function
-   goto &log;
+      goto &log;
+   }
+   0 # not logged
+}
+if (length $ENV{PERL_ANYEVENT_LOG}) {
+   require AnyEvent::Log; # AnyEvent::Log does the thing for us
 }
 our @models = (
    [EV::                   => AnyEvent::Impl::EV::   , 1],
    [AnyEvent::Loop::       => AnyEvent::Impl::Perl:: , 1],
    if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
       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$@";
+         AnyEvent::log 5 => "unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@";
       }
    }
    # check for already loaded models
    unless ($MODEL) {
       for (@REGISTRY, @models) {
          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;
             }
          }
       }
                $autoload
                and eval "require $package"
                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;
             }
          }
          $MODEL
          if defined &{"$MODEL\::$_"};
    }
    _isa_set;
+   # we're officially open!
    if ($ENV{PERL_ANYEVENT_STRICT}) {
       require AnyEvent::Strict;
    }
    if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
       require AnyEvent::Debug;
       AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
    }
-   if (exists $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
+   if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
       require AnyEvent::Socket;
       require AnyEvent::Debug;
       my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
       $shell =~ s/\$\$/$$/g;
       my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
       $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
    }
+   # now the anyevent environment is set up as the user told us to, so
+   # call the actual user code - post detects
    (shift @post_detect)->() while @post_detect;
    undef @post_detect;
    *post_detect = sub(&) {
 sub time {
    eval q{ # poor man's autoloading {}
       # probe for availability of Time::HiRes
       if (eval "use Time::HiRes (); Time::HiRes::time (); 1") {
-         AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy."
-            if $AnyEvent::VERBOSE >= 8;
          *time     = sub { Time::HiRes::time () };
          *AE::time = \&    Time::HiRes::time     ;
+         *now      = \&time;
+         AnyEvent::log 8 => "AnyEvent: using Time::HiRes for sub-second timing accuracy.";
          # if (eval "use POSIX (); (POSIX::times())...
       } else {
-         AnyEvent::log critical => "using built-in time(), WARNING, no sub-second resolution!";
          *time     = sub   { CORE::time };
          *AE::time = sub (){ CORE::time };
+         *now      = \&time;
+         AnyEvent::log 3 => "using built-in time(), WARNING, no sub-second resolution!";
       }
-      *now = \&time;
    };
    die if $@;
    &time
 }
 sub signal {
    eval q{ # poor man's autoloading {}
       # probe for availability of Async::Interrupt
       if (_have_async_interrupt) {
-         AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling."
+         AnyEvent::log 8 => "using Async::Interrupt for race-free signal handling.";
-            if $AnyEvent::VERBOSE >= 8;
          $SIGPIPE_R = new Async::Interrupt::EventPipe;
          $SIG_IO = AE::io $SIGPIPE_R->fileno, 0, \&_signal_exec;
       } else {
-         AnyEvent::log 8 => "using emulated perl signal handling with latency timer."
+         AnyEvent::log 8 => "using emulated perl signal handling with latency timer.";
-            if $AnyEvent::VERBOSE >= 8;
          if (AnyEvent::WIN32) {
             require AnyEvent::Util;
             ($SIGPIPE_R, $SIGPIPE_W) = AnyEvent::Util::portable_pipe ();
 $Event/EV::DIED->() >>, L<Glib> uses C<< install_exception_handler >> and
 so on.
 =head1 ENVIRONMENT VARIABLES
-The following environment variables are used by this module or its
+AnyEvent supports a number of environment variables that tune the
-submodules.
+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.
-Note that AnyEvent will remove I<all> environment variables starting with
+All the environment variables documented here start with
-C<PERL_ANYEVENT_> from C<%ENV> when it is loaded while taint mode is
+C<PERL_ANYEVENT_>, which is what AnyEvent considers its own
-enabled.
+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.
+The following environment variables are currently known to AnyEvent:
 =over 4
 =item C<PERL_ANYEVENT_VERBOSE>
 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
+When set to C<5> or higher (warn), causes AnyEvent to warn about unexpected
 conditions, such as not being able to load the event model specified by
-C<PERL_ANYEVENT_MODEL>.
+C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an exception - this
+is the minimum recommended level.
-When set to C<7> or higher, cause AnyEvent to report to STDERR which event
+When set to C<7> or higher (info), cause AnyEvent to report which event model it
-model it chooses.
+chooses.
-When set to C<8> or higher, then AnyEvent will report extra information on
+When set to C<8> or higher (debug), 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>.
+This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
+so will take effect even before AnyEvent has initialised itself.
+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
 argument checking is very costly. Setting this variable to a true value
 If this env variable is set, then its contents will be interpreted by
 C<AnyEvent::Socket::parse_hostport> (after replacing every occurance of
 C<$$> by the process pid) and an C<AnyEvent::Debug::shell> is bound on
 that port. The shell object is saved in C<$AnyEvent::Debug::SHELL>.
-This takes place when the first watcher is created.
+This happens when the first watcher is created.
 For example, to bind a debug shell on a unix domain socket in
 F<< /tmp/debug<pid>.sock >>, you could use this:
    PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
 but support both and try to use both.  C<PERL_ANYEVENT_PROTOCOLS=ipv4>
 - only support IPv4, never try to resolve or contact IPv6
 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
+Used by L<AnyEvent::DNS> to decide whether to use the EDNS0 extension for
-for DNS. This extension is generally useful to reduce DNS traffic, but
+DNS. This extension is generally useful to reduce DNS traffic, especially
-some (broken) firewalls drop such DNS packets, which is why it is off by
+when DNSSEC is involved, but some (broken) firewalls drop such DNS
-default.
+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.
 =item C<PERL_ANYEVENT_MAX_FORKS>
 resolver - this is the maximum number of parallel DNS requests that are
 sent to the DNS server.
 =item C<PERL_ANYEVENT_RESOLV_CONF>
-The file to use instead of F</etc/resolv.conf> (or OS-specific
+The absolute path to a F<resolv.conf>-style file to use instead of
-configuration) in the default resolver. When set to the empty string, no
+F</etc/resolv.conf> (or the OS-specific configuration) in the default
-default config will be used.
+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
+variables are nonempty, they will be used to specify CA certificate
-instead of a system-dependent default.
+locations instead of a system-dependent default.
 =item C<PERL_ANYEVENT_AVOID_GUARD> and C<PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT>
 When these are set to C<1>, then the respective modules are not
 loaded. Mostly good for testing AnyEvent itself.

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.365 by root, Tue Aug 16 14:47:26 2011 UTC vs. Revision 1.377 by root, Thu Aug 25 23:20:17 2011 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.365 by root, Tue Aug 16 14:47:26 2011 UTC vs.
Revision 1.377 by root, Thu Aug 25 23:20:17 2011 UTC