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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.373 by root, Thu Aug 25 03:08:48 2011 UTC vs.
Revision 1.377 by root, Thu Aug 25 23:20:17 2011 UTC

 =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.
+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
 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
    ()
 }
 sub log($$;@) {
-   # only load the bug bloated module when we actually are about to log something
+   # only load the big bloated module when we actually are about to log something
-   if ($_[0] <= $VERBOSE) {
+   if ($_[0] <= $VERBOSE) { # also catches non-numeric levels(!)
       require AnyEvent::Log;
       # AnyEvent::Log overwrites this function
       goto &log;
    }
+   0 # not logged
 }
 if (length $ENV{PERL_ANYEVENT_LOG}) {
    require AnyEvent::Log; # AnyEvent::Log does the thing for us
 }
       $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;
       } 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) {
 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 ();
 conditions. You can set this environment variable to make AnyEvent more
 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
 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.
 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

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.373 by root, Thu Aug 25 03:08:48 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.373 by root, Thu Aug 25 03:08:48 2011 UTC vs.
Revision 1.377 by root, Thu Aug 25 23:20:17 2011 UTC