ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent/Log.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent/Log.pm (file contents):
Revision 1.11 by root, Sat Aug 20 01:03:09 2011 UTC vs.
Revision 1.12 by root, Sat Aug 20 01:33:10 2011 UTC

… …
377They have exactly one parent - the context of the "parent" package. The 377They have exactly one parent - the context of the "parent" package. The
378parent package is simply defined to be the package name without the last 378parent package is simply defined to be the package name without the last
379component, i.e. C<AnyEvent::Debug::Wrapped> becomes C<AnyEvent::Debug>, 379component, i.e. C<AnyEvent::Debug::Wrapped> becomes C<AnyEvent::Debug>,
380and C<AnyEvent> becomes ... C<AnyEvent::Log::Top> which is the 380and C<AnyEvent> becomes ... C<AnyEvent::Log::Top> which is the
381exception of the rule - just like the parent of any package name in 381exception of the rule - just like the parent of any package name in
382Perl is C<main>, the default parent of any toplevel package context is 382Perl is C<main>, the default parent of any top-level package context is
383C<AnyEvent::Log::Top>. 383C<AnyEvent::Log::Top>.
384 384
385Since perl packages form only an approximate hierarchy, this parent 385Since perl packages form only an approximate hierarchy, this parent
386context can of course be removed. 386context can of course be removed.
387 387
388All other (anonymous) contexts have no parents and an empty title by 388All other (anonymous) contexts have no parents and an empty title by
389default. 389default.
390 390
391When the module is loaded it creates the default context called 391When the module is loaded it creates the default context called
392C<AnyEvent::Log::Default>, which simply logs everything to STDERR and 392C<AnyEvent::Log::Default> (also stored in C<$AnyEvent::Log::Default>),
393doesn't propagate anything anywhere by default. The purpose of the default 393which simply logs everything to STDERR and doesn't propagate anything
394context is to provide a convenient place to override the global logging 394anywhere by default. The purpose of the default context is to provide
395a convenient place to override the global logging target or to attach
395target or to attach additional log targets. It's not meant for filtering. 396additional log targets. It's not meant for filtering.
396 397
397It then creates the root context called C<AnyEvent::Log::Root> and 398It then creates the root context called C<AnyEvent::Log::Root> (also
398sets its log level set to all levels up to the one specified by 399stored in C<$AnyEvent::Log::Root>) and sets its log level set to all
399C<$ENV{PERL_ANYEVENT_VERBOSE}>. It then attached the default logging 400levels up to the one specified by C<$ENV{PERL_ANYEVENT_VERBOSE}>. It
400context to it. The purpose of the root context is to simply provide 401then attached the default logging context to it. The purpose of the root
401filtering according to some global log level. 402context is to simply provide filtering according to some global log level.
402 403
403Finally it creates the toplevel package context called 404Finally it creates the top-level package context called
405C<AnyEvent::Log::Top> (also stored in, you might have guessed,
404C<AnyEvent::Log::Top> and attached the root context but otherwise leaves 406C<$AnyEvent::Log::Top>) and attached the root context but otherwise leaves
405it at default config. It's purpose is simply to collect all log messages 407it at default config. It's purpose is simply to collect all log messages
406system-wide. 408system-wide.
407 409
408These three special contexts can also be referred to by the names 410These three special contexts can also be referred to by the
409C<AE::Log::Default>, C<AE::Log::Root> and C<AE::Log::Top>. 411package/context names C<AE::Log::Default>, C<AE::Log::Root> and
412C<AE::Log::Top>.
410 413
411The effect of all this is that log messages, by default, wander up 414The effect of all this is that log messages, by default, wander up
412to the root context where log messages with lower priority then 415to the root context where log messages with lower priority then
413C<$ENV{PERL_ANYEVENT_VERBOSE}> will be filtered away and then to the 416C<$ENV{PERL_ANYEVENT_VERBOSE}> will be filtered away and then to the
414AnyEvent::Log::Default context to be logged to STDERR. 417AnyEvent::Log::Default context to be logged to STDERR.
… …
468 $default->title ("AnyEvent::Log::Default"); 471 $default->title ("AnyEvent::Log::Default");
469 $default->log_cb (sub { 472 $default->log_cb (sub {
470 print STDERR shift; 473 print STDERR shift;
471 0 474 0
472 }); 475 });
473 $CTX{"AnyEvent::Log::Default"} = $CTX{"AE::Log::Default"} = $default; 476 $AnyEvent::Log::Default = $CTX{"AnyEvent::Log::Default"} = $CTX{"AE::Log::Default"} = $default;
474 477
475 my $root = ctx undef; 478 my $root = ctx undef;
476 $root->title ("AnyEvent::Log::Root"); 479 $root->title ("AnyEvent::Log::Root");
477 $root->level ($AnyEvent::VERBOSE); 480 $root->level ($AnyEvent::VERBOSE);
478 $root->attach ($default); 481 $root->attach ($default);
479 $CTX{"AnyEvent::Log::Root"} = $CTX{"AE::Log::Root"} = $root; 482 $AnyEvent::Log::Root = $CTX{"AnyEvent::Log::Root"} = $CTX{"AE::Log::Root"} = $root;
480 483
481 my $top = ctx undef; 484 my $top = ctx undef;
482 $top->title ("AnyEvent::Log::Top"); 485 $top->title ("AnyEvent::Log::Top");
483 $top->attach ($root); 486 $top->attach ($root);
484 $CTX{"AnyEvent::Log::Top"} = $CTX{"AE::Log::Top"} = $top; 487 $AnyEvent::Log::Top = $CTX{"AnyEvent::Log::Top"} = $CTX{"AE::Log::Top"} = $top;
485} 488}
486 489
487AnyEvent::Log::reset; 490AnyEvent::Log::reset;
488 491
492# hello, CPAN, please catch me
489package AnyEvent::Log::Default; 493package AnyEvent::Log::Default;
490package AE::Log::Default; 494package AE::Log::Default;
491package AnyEvent::Log::Root; 495package AnyEvent::Log::Root;
492package AE::Log::Root; 496package AE::Log::Root;
493package AnyEvent::Log::Top; 497package AnyEvent::Log::Top;
494package AE::Log::Top; 498package AE::Log::Top;
495 499
496=back
497
498=cut
499
500package AnyEvent::Log::Ctx; 500package AnyEvent::Log::Ctx;
501 501
502# 0 1 2 3 4 502# 0 1 2 3 4
503# [$title, $level, %$parents, &$logcb, &$fmtcb] 503# [$title, $level, %$parents, &$logcb, &$fmtcb]
504
505=item $ctx = new AnyEvent::Log::Ctx methodname => param...
506
507This is a convenience constructor that makes it simpler to construct
508anonymous logging contexts.
509
510Each key-value pair results in an invocation of the method of the same
511name as the key with the value as parameter, unless the value is an
512arrayref, in which case it calls the method with the contents of the
513array. The methods are called in the same order as specified.
514
515Example: create a new logging context and set both the default logging
516level, some parent contexts and a logging callback.
517
518 $ctx = new AnyEvent::Log::Ctx
519 title => "dubious messages",
520 level => "error",
521 log_cb => sub { print STDOUT shift; 0 },
522 parents => [$ctx1, $ctx, $ctx2],
523 ;
524
525=back
526
527=cut
528
529sub new {
530 my $class = shift;
531
532 my $ctx = AnyEvent::Log::ctx undef;
533
534 while (@_) {
535 my ($k, $v) = splice @_, 0, 2;
536 $ctx->$k (ref $v eq "ARRAY" ? @$v : $v);
537 }
538
539 bless $ctx, $class # do we really support subclassing, hmm?
540}
541
504 542
505=head2 CONFIGURING A LOG CONTEXT 543=head2 CONFIGURING A LOG CONTEXT
506 544
507The following methods can be used to configure the logging context. 545The following methods can be used to configure the logging context.
508 546
… …
758 796
7591; 7971;
760 798
761=back 799=back
762 800
801=head1 EXAMPLES
802
803This section shows some common configurations.
804
805=over 4
806
807=item Setting the global logging level.
808
809Either put PERL_ANYEVENT_VERBOSE=<number> into your environment before
810running your program, or modify the log level of the root context:
811
812 PERL_ANYEVENT_VERBOSE=5 ./myprog
813
814 $AnyEvent::Log::Root->level ("warn");
815
816=item Append all messages to a file instead of sending them to STDERR.
817
818This is affected by the global logging level.
819
820 open my $fh, ">>", $path
821 or die "$path: $!";
822
823 $AnyEvent::Log::Default->log_cb (sub {
824 syswrite $fh, shift;
825 0
826 });
827
828=item Write all messages with priority C<error> and higher to a file.
829
830This writes them only when the global logging level allows it, because
831it is attached to the default context which is invoked I<after> global
832filtering.
833
834 open my $fh, ">>", $path
835 or die "$path: $!";
836
837 $AnyEvent::Log::Default->attach (new AnyEvent::Log::Ctx
838 log_cb => sub { syswrite $fh, shift; 0 });
839
840This writes them regardless of the global logging level, because it is
841attached to the toplevel context, which receives all messages I<before>
842the global filtering.
843
844 $AnyEvent::Log::Top->attach (new AnyEvent::Log::Ctx
845 log_cb => sub { syswrite $fh, shift; 0 });
846
847In both cases, messages are still written to STDOUT.
848
849=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).
850
851Attach the CyAnyEvent::Log::Default> context to the C<AnyEvent::Debug>
852context and increase the C<AnyEvent::Debug> logging level - this simply
853circumvents the global filtering for trace messages.
854
855 my $debug = AnyEvent::Debug->AnyEvent::Log::ctx;
856 $debug->attach ($AnyEvent::Log::Default);
857 $debug->levels ("trace"); # not "level"!
858
859=back
860
763=head1 AUTHOR 861=head1 AUTHOR
764 862
765 Marc Lehmann <schmorp@schmorp.de> 863 Marc Lehmann <schmorp@schmorp.de>
766 http://home.schmorp.de/ 864 http://home.schmorp.de/
767 865

Diff Legend

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