/usr/include/log4shib/NDC.hh is in liblog4shib-dev 1.0.9-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 | /*
* NDC.hh
*
* Copyright 2000, LifeLine Networks BV (www.lifeline.nl). All rights reserved.
* Copyright 2000, Bastiaan Bakker. All rights reserved.
*
* See the COPYING file for the terms of usage and distribution.
*/
#ifndef _LOG4SHIB_NDC_HH
#define _LOG4SHIB_NDC_HH
#include <log4shib/Portability.hh>
#include <string>
#include <vector>
namespace log4shib {
/**
The NDC class implements <i>nested diagnostic contexts</i> as
defined by Neil Harrison in the article "Patterns for Logging
Diagnostic Messages" part of the book "<i>Pattern Languages of
Program Design 3</i>" edited by Martin et al.
<p>A Nested Diagnostic Context, or NDC in short, is an instrument
to distinguish interleaved log output from different sources. Log
output is typically interleaved when a server handles multiple
clients near-simulatanously.
<p>Interleaved log output can still be meaningful if each log entry
from different contexts had a distinctive stamp. This is where NDCs
come into play.
<p><em><b>Note that NDCs are managed on a per thread
basis</b></em>. NDC operations such as <code>push</code>, <code>
pop</code>, <code>clear</code>, <code>getDepth</code> and <code>
setMaxDepth</code> affect the NDC of the <em>current</em> thread only.
NDCs of other threads remain unaffected.
<p>To build an NDC one uses the <code>push</code> operation.
Simply put,
<p><ul>
<li>Contexts can be nested.
<p><li>When entering a context, call <code>NDC.push</code>. As a
side effect, if there is no nested diagnostic context for the
current thread, this method will create it.
<p><li>When leaving a context, call <code>NDC.pop</code>.
</ul>
<p>There is no penalty for forgetting to match each
<code>push</code> operation with a corresponding <code>pop</code>,
except the obvious mismatch between the real application context
and the context set in the NDC.
<p>Custom Layouts may include the nested diagnostic context for the
current thread in log messages, without any user intervention.
Hence, even if a server is serving multiple clients
simultaneously, the logs emanating from the same code (belonging to
the same category) can still be distinguished because each client
request will have a different NDC tag.
<p><em>Unfortunately, unlike Java, C++ does not have platform
independent multithreading support. Therefore, currently log4shib is
not multithread aware, it implicitly assumes only one thread exists,
the main process thread. </em>
**/
class LOG4SHIB_EXPORT NDC {
public:
struct DiagnosticContext {
DiagnosticContext(const std::string& message);
DiagnosticContext(const std::string& message,
const DiagnosticContext& parent);
std::string message;
std::string fullMessage;
};
typedef std::vector<DiagnosticContext> ContextStack;
/**
Clear any nested disgnostic information if any. This method is
useful in cases where the same thread can be potentially used
over and over in different unrelated contexts.
<p>This method is equivalent to calling the <code>setMaxDepth</code>
method with a zero <code>maxDepth</code> argument.
**/
static void clear();
/**
Clone the diagnostic context for the current thread.
<p>Internally a diagnostic context is represented as a stack. A
given thread can supply the stack (i.e. diagnostic context) to a
child thread so that the child can inherit the parent thread's
diagnostic context.
<p>The child thread uses the <code>inherit</code> method to
inherit the parent's diagnostic context.
@return Stack A clone of the current thread's diagnostic context.
**/
static ContextStack* cloneStack();
/**
Get the current diagnostic context string.
@return the context string.
**/
static const std::string& get();
/**
Get the current nesting depth of this diagnostic context.
@return the nesting depth
**/
static int getDepth();
static void inherit(ContextStack* stack);
/**
Clients should call this method before leaving a diagnostic
context.
<p>The returned value is the value that was pushed last. If no
context is available, then the empty string "" is returned.
@return String The innermost diagnostic context.
**/
static std::string pop();
/**
Push new diagnostic context information for the current thread.
<p>The contents of the <code>message</code> parameter is
determined solely by the client.
@param message The new diagnostic context information.
**/
static void push(const std::string& message);
/**
Set the maximum nesting depth for the current NDC. Curently NDCs
do not enforce a maximum depth and consequentially this method
has no effect.
@param maxDepth the maximum nesting depth
**/
static void setMaxDepth(int maxDepth);
/**
Return the NDC for the current thread.
@return the NDC for the current thread
**/
static NDC& getNDC();
NDC();
virtual ~NDC();
public:
virtual void _clear();
virtual ContextStack* _cloneStack();
virtual const std::string& _get() const;
virtual int _getDepth() const;
virtual void _inherit(ContextStack* stack);
virtual std::string _pop();
virtual void _push(const std::string& message);
virtual void _setMaxDepth(int maxDepth);
ContextStack _stack;
};
}
#endif // _LOG4SHIB_NDC_HH
|