File Coverage

blib/lib/Log/Log4perl/NDC.pm
Criterion Covered Total %
statement 17 21 80.9
branch 5 8 62.5
condition n/a
subroutine 6 7 85.7
pod 4 4 100.0
total 32 40 80.0


line stmt bran cond sub pod time code
1             ##################################################
2             ##################################################
3              
4             use 5.006;
5 70     70   1237 use strict;
  70         220  
6 70     70   334 use warnings;
  70         113  
  70         1801  
7 70     70   374  
  70         119  
  70         14550  
8             our @NDC_STACK = ();
9             our $MAX_SIZE = 5;
10              
11             ###########################################
12             ###########################################
13             if(@NDC_STACK) {
14             # Return elements blank separated
15 4 100   4 1 8 return join " ", @NDC_STACK;
16             } else {
17 3         16 return "[undef]";
18             }
19 1         2 }
20              
21             ###########################################
22             ###########################################
23             if(@NDC_STACK) {
24             return pop @NDC_STACK;
25             } else {
26 0 0   0 1 0 return undef;
27 0         0 }
28             }
29 0         0  
30             ###########################################
31             ###########################################
32             my($self, $text) = @_;
33              
34             unless(defined $text) {
35             # Somebody called us via Log::Log4perl::NDC::push("blah") ?
36 7     7 1 28 $text = $self;
37             }
38 7 50       12  
39             if(@NDC_STACK >= $MAX_SIZE) {
40 0         0 CORE::pop(@NDC_STACK);
41             }
42              
43 7 100       11 return push @NDC_STACK, $text;
44 1         1 }
45              
46             ###########################################
47 7         11 ###########################################
48             @NDC_STACK = ();
49             }
50              
51              
52             =encoding utf8
53 1     1 1 5  
54             =head1 NAME
55              
56             Log::Log4perl::NDC - Nested Diagnostic Context
57              
58             =head1 DESCRIPTION
59              
60             Log::Log4perl allows loggers to maintain global thread-specific data,
61             called the Nested Diagnostic Context (NDC).
62              
63             At some point, the application might decide to push a piece of
64             data onto the NDC stack, which other parts of the application might
65             want to reuse. For example, at the beginning of a web request in a server,
66             the application might decide to push the IP address of the client
67             onto the stack to provide it for other loggers down the road without
68             having to pass the data from function to function.
69              
70             The Log::Log4perl::Layout::PatternLayout class even provides the handy
71             C<%x> placeholder which is replaced by the blank-separated list
72             of elements currently on the stack.
73              
74             This module maintains a simple stack which you can push data on to, query
75             what's on top, pop it off again or delete the entire stack.
76              
77             Its purpose is to provide a thread-specific context which all
78             Log::Log4perl loggers can refer to without the application having to
79             pass around the context data between its functions.
80              
81             Since in 5.8.0 perl's threads don't share data only upon request,
82             global data is by definition thread-specific.
83              
84             =over 4
85              
86             =item Log::Log4perl::NDC->push($text);
87              
88             Push an item onto the stack. If the stack grows beyond the defined
89             limit (C<$Log::Log4perl::NDC::MAX_SIZE>), just the topmost element
90             will be replated.
91              
92             This is typically done when a context is entered.
93              
94             =item Log::Log4perl::NDC->pop();
95              
96             Discard the upmost element of the stack. This is typically done when
97             a context is left.
98              
99             =item my $text = Log::Log4perl::NDC->get();
100              
101             Retrieve the content of the stack as a string of blank-separated values
102             without disrupting the stack structure. Typically done by C<%x>.
103             If the stack is empty the value C<"[undef]"> is being returned.
104              
105             =item Log::Log4perl::NDC->remove();
106              
107             Reset the stack, remove all items.
108              
109             =back
110              
111             Please note that all of the methods above are class methods, there's no
112             instances of this class.
113              
114             =head1 LICENSE
115              
116             Copyright 2002-2013 by Mike Schilli E<lt>m@perlmeister.comE<gt>
117             and Kevin Goess E<lt>cpan@goess.orgE<gt>.
118              
119             This library is free software; you can redistribute it and/or modify
120             it under the same terms as Perl itself.
121              
122             =head1 AUTHOR
123              
124             Please contribute patches to the project on Github:
125              
126             http://github.com/mschilli/log4perl
127              
128             Send bug reports or requests for enhancements to the authors via our
129              
130             MAILING LIST (questions, bug reports, suggestions/patches):
131             log4perl-devel@lists.sourceforge.net
132              
133             Authors (please contact them via the list above, not directly):
134             Mike Schilli <m@perlmeister.com>,
135             Kevin Goess <cpan@goess.org>
136              
137             Contributors (in alphabetical order):
138             Ateeq Altaf, Cory Bennett, Jens Berthold, Jeremy Bopp, Hutton
139             Davidson, Chris R. Donnelly, Matisse Enzer, Hugh Esco, Anthony
140             Foiani, James FitzGibbon, Carl Franks, Dennis Gregorovic, Andy
141             Grundman, Paul Harrington, Alexander Hartmaier David Hull,
142             Robert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter,
143             Brett Rann, Peter Rabbitson, Erik Selberg, Aaron Straup Cope,
144             Lars Thegler, David Viner, Mac Yang.
145