NAME¶
Log::Dispatchouli::Global - a system for sharing a global, dynamically-scoped
logger
VERSION¶
version 2.005
DESCRIPTION¶
Warning: This interface is still experimental.
Log::Dispatchouli::Global is a framework for a global logger object. In your
top-level programs that are actually executed, you'd add something like this:
use Log::Dispatchouli::Global '$Logger' => {
init => {
ident => 'My::Daemon',
facility => 'local2',
to_stdout => 1,
},
};
This will import a $Logger into your program, and more importantly will
initialize it with a new Log::Dispatchouli object created by passing the value
for the "init" parameter to Log::Dispatchouli's "new"
method.
Much of the rest of your program, across various libraries, can then just use
this:
use Log::Dispatchouli::Global '$Logger';
sub whatever {
...
$Logger->log("about to do something");
local $Logger = $Logger->proxy({ proxy_prefix => "whatever: " });
for (@things) {
$Logger->log([ "doing thing %s", $_ ]);
...
}
}
This eliminates the need to pass around what is effectively a global, while
still allowing it to be specialized withing certain contexts of your program.
Warning! Although you
could just use Log::Dispatchouli::Global as
your shared logging library, you almost
certainly want to write a
subclass that will only be shared amongst your application's classes.
Log::Dispatchouli::Global is meant to be subclassed and shared only within
controlled systems. Remember,
sharing your state with code you don't
control is dangerous.
USING¶
In general, you will either be using a Log::Dispatchouli::Global class to get a
$Logger or to initialize it (and then get $Logger). These are both
demonstrated above. Also, when importing $Logger you may request it be
imported under a different name:
use Log::Dispatchouli::Global '$Logger' => { -as => 'L' };
$L->log( ... );
There is only one class method that you are likely to use:
"current_logger". This provides the value of the shared logger from
the caller's context, initializing it to a default if needed. Even this method
is unlikely to be required frequently, but it
does allow users to
see $Logger without importing it.
SUBCLASSING¶
Before using Log::Dispatchouli::Global in your application, you should subclass
it. When you subclass it, you should provide the following methods:
logger_globref¶
This method should return a globref in which the shared logger will be stored.
Subclasses will be in their own package, so barring any need for cleverness,
every implementation of this method can look like the following:
sub logger_globref { no warnings 'once'; return \*Logger }
default_logger¶
If no logger has been initialized, but something tries to log, it gets the
default logger, created by calling this method.
The default implementation calls "new" on the
"default_logger_class" with the result of
"default_logger_args" as the arguments.
default_logger_class¶
This returns the class on which "new" will be called when initializing
a logger, either from the "init" argument when importing or the
default logger.
Its default value is Log::Dispatchouli.
default_logger_args¶
If no logger has been initialized, but something tries to log, it gets the
default logger, created by calling "new" on the
"default_logger_class" and passing the results of calling this
method.
Its default return value creates a sink, so that anything logged without an
initialized logger is lost.
default_logger_ref¶
This method returns a scalar reference in which the cached default value is
stored for comparison. This is used when someone tries to "init" the
global. When someone tries to initialize the global logger, and it's already
set, then:
- •
- if the current value is the same as the default, the new
value is set
- •
- if the current value is not the same as the default,
we die
Since you want the default to be isolated to your application's logger, the
default behavior is default loggers are associated with the glob reference to
which the default might be assigned. It is recommended that you replace this
method to return a shared, private variable for your subclasses, by putting
the following code in the base class for your Log::Dispatchouli::Global
classes:
my $default_logger;
sub default_logger_ref { \$default_logger };
COOKBOOK¶
Common Logger Recipes¶
Say you often use the same configuration for one kind of program, like automated
tests. You've already written your own subclass to get your own storage and
defaults, maybe "MyApp::Logger".
You can't just write a subclass with a different default, because if another
class using the same global has set the global with
its default, yours
won't be honored. You don't just want this new value to be the default, you
want it to be
the logger. What you want to do in this case is to
initialize your logger normally, then reexport it, like this:
package MyApp::Logger::Test;
use parent 'MyApp::Logger';
use MyApp::Logger '$Logger' => {
init => {
ident => "Tester($0)",
to_self => 1,
facility => undef,
},
};
This will set up the logger and re-export it, and will properly die if anything
else attempts to initialize the logger to something else.
AUTHOR¶
Ricardo SIGNES <rjbs@cpan.org>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2011 by Ricardo SIGNES.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.