Log::Dispatchouli::GloUser3Contributed Perl DocumeLog::Dispatchouli::Global(3)NAMELog::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.
perl v5.14.1 2011-04-08 Log::Dispatchouli::Global(3)
