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