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