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

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.49 by root, Thu Mar 22 01:03:57 2012 UTC vs.
Revision 1.55 by root, Fri Mar 30 21:31:52 2012 UTC

 Simple uses:
    use AnyEvent;
+   AE::log fatal => "No config found, cannot continue!"; # never returns
+   AE::log alert => "The battery died!";
+   AE::log crit  => "The battery temperature is too hot!";
+   AE::log error => "Division by zero attempted.";
+   AE::log warn  => "Couldn't delete the file.";
+   AE::log note  => "Wanted to create config, but config already exists.";
+   AE::log info  => "File soandso successfully deleted.";
+   AE::log debug => "the function returned 3";
    AE::log trace => "going to call function abc";
-   AE::log debug => "the function returned 3";
-   AE::log info  => "file soandso successfully deleted";
-   AE::log note  => "wanted to create config, but config was already created";
-   AE::log warn  => "couldn't delete the file";
-   AE::log error => "failed to retrieve data";
-   AE::log crit  => "the battery temperature is too hot";
-   AE::log alert => "the battery died";
-   AE::log fatal => "no config found, cannot continue"; # never returns
 Log level overview:
    LVL NAME      SYSLOG   PERL  NOTE
     1  fatal     emerg    exit  system unusable, aborts program!
 attempt to be "the" logging solution or even "a" logging solution for
 AnyEvent - AnyEvent simply creates logging messages internally, and this
 module more or less exposes the mechanism, with some extra spiff to allow
 using it from other modules as well.
-Remember that the default verbosity level is C<3> (C<critical>), so little
+Remember that the default verbosity level is C<4> (C<error>), so only
-will be logged, unless you set C<PERL_ANYEVENT_VERBOSE> to a higher number
+errors and more important messages will be logged, unless you set
-before starting your program, or change the logging level at runtime with
+C<PERL_ANYEVENT_VERBOSE> to a higher number before starting your program
-something like:
+(C<AE_VERBOSE=5> is recommended during development), or change the logging
+level at runtime with something like:
    use AnyEvent::Log;
    $AnyEvent::Log::FILTER->level ("info");
 The design goal behind this module was to keep it simple (and small),
 levels 7..9 are usually meant for developers.
 You can normally only log a message once at highest priority level (C<1>,
 C<fatal>), because logging a fatal message will also quit the program - so
 use it sparingly :)
+For example, a program that finds an unknown switch on the commandline
+might well use a fatal logging level to tell users about it - the "system"
+in this case would be the program, or module.
 Some methods also offer some extra levels, such as C<0>, C<off>, C<none>
 or C<all> - these are only valid for the methods that documented them.
 =head1 LOGGING FUNCTIONS
 the logging (which consists of formatting the message and printing it or
 whatever it wants to do with it).
 =over 4
-=item $ctx->log_cb ($cb->($str)
+=item $ctx->log_cb ($cb->($str))
 Replaces the logging callback on the context (C<undef> disables the
 logging callback).
 The logging callback is responsible for handling formatted log messages
 Replaces the formatting callback on the context (C<undef> restores the
 default formatter).
 The callback is passed the (possibly fractional) timestamp, the original
-logging context, the (numeric) logging level and the raw message string
+logging context (object, not title), the (numeric) logging level and
-and needs to return a formatted log message. In most cases this will be a
+the raw message string and needs to return a formatted log message. In
-string, but it could just as well be an array reference that just stores
+most cases this will be a string, but it could just as well be an array
-the values.
+reference that just stores the values.
 If, for some reason, you want to use C<caller> to find out more about the
 logger then you should walk up the call stack until you are no longer
 inside the C<AnyEvent::Log> package.
       "<$lvl>$msg\n"
    });
 Example: return an array reference with just the log values, and use
-C<PApp::SQL::sql_exec> to store the emssage in a database.
+C<PApp::SQL::sql_exec> to store the message in a database.
    $ctx->fmt_cb (sub { \@_ });
    $ctx->log_cb (sub {
       my ($msg) = @_;
 Sets the C<log_cb> to simply use C<CORE::warn> to report any messages
 (usually this logs to STDERR).
 =item $ctx->log_to_file ($path)
-Sets the C<log_cb> to log to a file (by appending), unbuffered.
+Sets the C<log_cb> to log to a file (by appending), unbuffered. The
+function might return before the log file has been opened or created.
 =item $ctx->log_to_path ($path)
 Same as C<< ->log_to_file >>, but opens the file for each message. This
 is much slower, but allows you to change/move/rename/delete the file at
       warn shift;
       0
    });
 }
+# this function is a good example of why threads are a must,
+# simply for priority inversion.
+sub _log_to_disk {
+   # eval'uating this at runtime saves 220kb rss - perl has become
+   # an insane memory waster.
+   eval q{ # poor man's autoloading {}
+      sub _log_to_disk {
+         my ($ctx, $path, $keepopen) = @_;
+         my $fh;
+         my @queue;
+         my $delay;
+         my $disable;
+         use AnyEvent::IO ();
+         my $kick = sub {
+            undef $delay;
+            return unless @queue;
+            $delay = 1;
+            # we pass $kick to $kick, so $kick itself doesn't keep a reference to $kick.
+            my $kick = shift;
+            # write one or more messages
+            my $write = sub {
+               # we write as many messages as have been queued
+               my $data = join "", @queue;
+               @queue = ();
+               AnyEvent::IO::ae_write $fh, $data, sub {
+                  $disable = 1;
+                  @_
+                     ? ($_[0] == length $data or AE::log 4 => "unable to write to logfile '$path': short write")
+                     :                           AE::log 4 => "unable to write to logfile '$path': $!";
+                  undef $disable;
+                  if ($keepopen) {
+                     $kick->($kick);
+                  } else {
+                     AnyEvent::IO::ae_close ($fh, sub {
+                        undef $fh;
+                        $kick->($kick);
+                     });
+                  }
+               };
+            };
+            if ($fh) {
+               $write->();
+            } else {
+               AnyEvent::IO::ae_open
+                  $path,
+                  AnyEvent::IO::O_CREAT | AnyEvent::IO::O_WRONLY | AnyEvent::IO::O_APPEND,
+                  0666,
+                  sub {
+                     $fh = shift
+                        or do {
+                           $disable = 1;
+                           AE::log 4 => "unable to open logfile '$path': $!";
+                           undef $disable;
+                           return;
+                        };
+                     $write->();
+                  }
+               ;
+            }
+         };
+         $ctx->log_cb (sub {
+            return if $disable;
+            push @queue, shift;
+            $kick->($kick) unless $delay;
+            0
+         });
+         $kick->($kick) if $keepopen; # initial open
+      };
+   };
+   die if $@;
+   &_log_to_disk
+}
 sub log_to_file {
    my ($ctx, $path) = @_;
-   open my $fh, ">>", $path
+   _log_to_disk $ctx, $path, 1;
-      or die "$path: $!";
-   $ctx->log_cb (sub {
-      syswrite $fh, shift;
-      0
-   });
 }
 sub log_to_path {
    my ($ctx, $path) = @_;
-   $ctx->log_cb (sub {
+   _log_to_disk $ctx, $path, 0;
-      open my $fh, ">>", $path
-         or die "$path: $!";
-      syswrite $fh, shift;
-      0
-   });
 }
 sub log_to_syslog {
    my ($ctx, $facility) = @_;
 =over 4
 =item $ctx->log ($level, $msg[, @params])
 Same as C<AnyEvent::Log::log>, but uses the given context as log context.
+Example: log a message in the context of another package.
+   (AnyEvent::Log::ctx "Other::Package")->log (warn => "heely bo");
 =item $logger = $ctx->logger ($level[, \$enabled])
 Same as C<AnyEvent::Log::logger>, but uses the given context as log
 context.
    if (/\G(.+)/g) {
       die "PERL_ANYEVENT_LOG ($spec): parse error at '$1'\n";
    }
 }
-1;
 =head1 EXAMPLES
 This section shows some common configurations, both as code, and as
 C<PERL_ANYEVENT_LOG> string.
  Marc Lehmann <schmorp@schmorp.de>
  http://home.schmorp.de/
 =cut
+1

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents): Revision 1.49 by root, Thu Mar 22 01:03:57 2012 UTC vs. Revision 1.55 by root, Fri Mar 30 21:31:52 2012 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.49 by root, Thu Mar 22 01:03:57 2012 UTC vs.
Revision 1.55 by root, Fri Mar 30 21:31:52 2012 UTC