1Log::Dispatchouli::GlobUasle(r3)Contributed Perl DocumenLtoagt:i:oDnispatchouli::Global(3)
2
6 Log::Dispatchouli::Global - a system for sharing a global,
7 dynamically-scoped logger
8
10 version 2.022
11
13 Warning: This interface is still experimental.
14 Log::Dispatchouli::Global is a framework for a global logger object. In
16 your top-level programs that are actually executed, you'd add something
17 like this:
18 use Log::Dispatchouli::Global '$Logger' => {
20 init => {
21 ident => 'My::Daemon',
22 facility => 'local2',
23 to_stdout => 1,
24 },
25 };
26 This will import a $Logger into your program, and more importantly will
28 initialize it with a new Log::Dispatchouli object created by passing
29 the value for the "init" parameter to Log::Dispatchouli's "new" method.
30 Much of the rest of your program, across various libraries, can then
32 just use this:
33 use Log::Dispatchouli::Global '$Logger';
35 sub whatever {
37 ...
38 $Logger->log("about to do something");
40 local $Logger = $Logger->proxy({ proxy_prefix => "whatever: " });
42 for (@things) {
44 $Logger->log([ "doing thing %s", $_ ]);
45 ...
46 }
47 }
48 This eliminates the need to pass around what is effectively a global,
50 while still allowing it to be specialized within certain contexts of
51 your program.
52 Warning! Although you could just use Log::Dispatchouli::Global as your
54 shared logging library, you almost certainly want to write a subclass
55 that will only be shared amongst your application's classes.
56 Log::Dispatchouli::Global is meant to be subclassed and shared only
57 within controlled systems. Remember, sharing your state with code you
58 don't control is dangerous.
59
61 In general, you will either be using a Log::Dispatchouli::Global class
62 to get a $Logger or to initialize it (and then get $Logger). These are
63 both demonstrated above. Also, when importing $Logger you may request
64 it be imported under a different name:
65 use Log::Dispatchouli::Global '$Logger' => { -as => 'L' };
67 $L->log( ... );
69 There is only one class method that you are likely to use:
71 "current_logger". This provides the value of the shared logger from
72 the caller's context, initializing it to a default if needed. Even
73 this method is unlikely to be required frequently, but it does allow
74 users to see $Logger without importing it.
75
77 Before using Log::Dispatchouli::Global in your application, you should
78 subclass it. When you subclass it, you should provide the following
79 methods:
80 logger_globref
82 This method should return a globref in which the shared logger will be
83 stored. Subclasses will be in their own package, so barring any need
84 for cleverness, every implementation of this method can look like the
85 following:
86 sub logger_globref { no warnings 'once'; return \*Logger }
88 default_logger
90 If no logger has been initialized, but something tries to log, it gets
91 the default logger, created by calling this method.
92 The default implementation calls "new" on the "default_logger_class"
94 with the result of "default_logger_args" as the arguments.
95 default_logger_class
97 This returns the class on which "new" will be called when initializing
98 a logger, either from the "init" argument when importing or the default
99 logger.
100 Its default value is Log::Dispatchouli.
102 default_logger_args
104 If no logger has been initialized, but something tries to log, it gets
105 the default logger, created by calling "new" on the
106 "default_logger_class" and passing the results of calling this method.
107 Its default return value creates a sink, so that anything logged
109 without an initialized logger is lost.
110 default_logger_ref
112 This method returns a scalar reference in which the cached default
113 value is stored for comparison. This is used when someone tries to
114 "init" the global. When someone tries to initialize the global logger,
115 and it's already set, then:
116 • if the current value is the same as the default, the new value is
118 set
119 • if the current value is not the same as the default, we die
121 Since you want the default to be isolated to your application's logger,
123 the default behavior is default loggers are associated with the glob
124 reference to which the default might be assigned. It is unlikely that
125 you will need to interact with this method.
126
128 Common Logger Recipes
129 Say you often use the same configuration for one kind of program, like
130 automated tests. You've already written your own subclass to get your
131 own storage and defaults, maybe "MyApp::Logger".
132 You can't just write a subclass with a different default, because if
134 another class using the same global has set the global with its
135 default, yours won't be honored. You don't just want this new value to
136 be the default, you want it to be the logger. What you want to do in
137 this case is to initialize your logger normally, then reexport it, like
138 this:
139 package MyApp::Logger::Test;
141 use parent 'MyApp::Logger';
142 use MyApp::Logger '$Logger' => {
144 init => {
145 ident => "Tester($0)",
146 to_self => 1,
147 facility => undef,
148 },
149 };
150 This will set up the logger and re-export it, and will properly die if
152 anything else attempts to initialize the logger to something else.
153
155 Ricardo SIGNES <rjbs@cpan.org>
156
158 This software is copyright (c) 2020 by Ricardo SIGNES.
159 This is free software; you can redistribute it and/or modify it under
161 the same terms as the Perl 5 programming language system itself.
162perl v5.32.1 2021-01-27 Log::Dispatchouli::Global(3)