Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Log::Dispatchouli::GloUser3Contributed Perl DocumeLog::Dispatchouli::Global(3)

NAME
       Log::Dispatchouli::Global - a system for	sharing	a global,
       dynamically-scoped logger

VERSION
       version 2.012

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 within	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:

       o   if the current value	is the same as the default, the	new value is
	   set

       o   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	unlikely that
       you will	need to	interact with this method.

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) 2014 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.32.1			  2014-11-30	  Log::Dispatchouli::Global(3)

NAME | VERSION | DESCRIPTION | USING | SUBCLASSING | COOKBOOK | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Log::Dispatchouli::Global&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help