1Appender::Synchronized(U3s)er Contributed Perl DocumentatAipopnender::Synchronized(3)
2
6 Log::Log4perl::Appender::Synchronized - Synchronizing other appenders
7
9 use Log::Log4perl qw(:easy);
10 my $conf = qq(
12 log4perl.category = WARN, Syncer
13 # File appender (unsynchronized)
15 log4perl.appender.Logfile = Log::Log4perl::Appender::File
16 log4perl.appender.Logfile.autoflush = 1
17 log4perl.appender.Logfile.filename = test.log
18 log4perl.appender.Logfile.mode = truncate
19 log4perl.appender.Logfile.layout = SimpleLayout
20 # Synchronizing appender, using the file appender above
22 log4perl.appender.Syncer = Log::Log4perl::Appender::Synchronized
23 log4perl.appender.Syncer.appender = Logfile
24 );
25 Log::Log4perl->init(\$conf);
27 WARN("This message is guaranteed to be complete.");
28
30 If multiple processes are using the same "Log::Log4perl" appender with‐
31 out synchronization, overwrites might happen. A typical scenario for
32 this would be a process spawning children, each of which inherits the
33 parent's Log::Log4perl configuration.
34 Usually, you should avoid this scenario and have each child have its
36 own Log::Log4perl configuration, ensuring that each e.g. writes to a
37 different logfile.
38 In cases where you need additional synchronization, however, use
40 "Log::Log4perl::Appender::Synchronized" as a gateway between your log‐
41 gers and your appenders. An appender itself, "Log::Log4perl::Appen‐
42 der::Synchronized" just takes two additional arguments:
43 "appender"
45 Specifies the name of the appender it synchronizes access to. The
46 appender specified must be defined somewhere in the configuration
47 file, not necessarily before the definition of
48 "Log::Log4perl::Appender::Synchronized".
49 "key"
51 This optional argument specifies the key for the semaphore that
52 "Log::Log4perl::Appender::Synchronized" uses internally to ensure
53 atomic operations. It defaults to "_l4p". If you define more than
54 one "Log::Log4perl::Appender::Synchronized" appender, it is impor‐
55 tant to specify different keys for them, as otherwise every new
56 "Log::Log4perl::Appender::Synchronized" appender will nuke previ‐
57 ously defined semaphores. The maximum key length is four charac‐
58 ters, longer keys will be truncated to 4 characters -- "mylongkey1"
59 and "mylongkey2" are interpreted to be the same: "mylo" (thanks to
60 David Viner <dviner@yahoo-inc.com> for pointing this out).
61 "Log::Log4perl::Appender::Synchronized" uses "IPC::Shareable" inter‐
63 nally to perform locking with semaphores provided by the operating sys‐
64 tem used.
65 Performance tips
67 The "Log::Log4perl::Appender::Synchronized" serializes access to a pro‐
69 tected resource globally, slowing down actions otherwise performed in
70 parallel.
71 Unless specified otherwise, all instances of "Log::Log4perl::Appen‐
73 der::Synchronized" objects in the system will use the same global IPC
74 key "_l4p".
75 To control access to different appender instances, it often makes sense
77 to define different keys for different synchronizing appenders. In this
78 way, Log::Log4perl serializes access to each appender instance sepa‐
79 rately:
80 log4perl.category = WARN, Syncer1, Syncer2
82 # File appender 1 (unsynchronized)
84 log4perl.appender.Logfile1 = Log::Log4perl::Appender::File
85 log4perl.appender.Logfile1.filename = test1.log
86 log4perl.appender.Logfile1.layout = SimpleLayout
87 # File appender 2 (unsynchronized)
89 log4perl.appender.Logfile2 = Log::Log4perl::Appender::File
90 log4perl.appender.Logfile2.filename = test2.log
91 log4perl.appender.Logfile2.layout = SimpleLayout
92 # Synchronizing appender, using the file appender above
94 log4perl.appender.Syncer1 = Log::Log4perl::Appender::Synchronized
95 log4perl.appender.Syncer1.appender = Logfile1
96 log4perl.appender.Syncer1.key = l4p1
97 # Synchronizing appender, using the file appender above
99 log4perl.appender.Syncer2 = Log::Log4perl::Appender::Synchronized
100 log4perl.appender.Syncer2.appender = Logfile2
101 log4perl.appender.Syncer2.key = l4p2
102 Without the ".key = l4p1" and ".key = l4p2" lines, both Synchronized
104 appenders would be using the default "_l4p" key, causing unnecessary
105 serialization of output written to different files.
106 Advanced configuration
108 To configure the underlying IPC::Shareable module, use the options
110 property and hand it a reference to a hash of options.
111 By default, the setting is equal to
113 { create=>1, destroy=>1 }
115 which has the appender create the semaphore at startup and remove it at
117 shutdown.
118 In order to add another option, e.g. a setting of 0775 for IPC::Share‐
120 able's "mode" parameter, add
121 log4perl.appender.Syncer1.options = \
123 sub { { create=>1, destroy=>1, mode=>0775 } }
124 to the Log4perl configuration file.
126
128 "Log::Log4perl::Appender::Synchronized" is a composite appender.
129 Unlike other appenders, it doesn't log any messages, it just passes
130 them on to its attached sub-appender. For this reason, it doesn't need
131 a layout (contrary to regular appenders). If it defines none, messages
132 are passed on unaltered.
133 Custom filters are also applied to the composite appender only. They
135 are not applied to the sub-appender. Same applies to appender thresh‐
136 olds. This behaviour might change in the future.
137
139 Copyright 2003 by Mike Schilli, all rights reserved. This program is
140 free software, you can redistribute it and/or modify it under the same
141 terms as Perl itself.
142
144 2003, Mike Schilli <m@perlmeister.com>
145perl v5.8.8 2002-07-10 Appender::Synchronized(3)