A Nested Diagnostic Context, or NDC in short, is an instrument to distinguish interleaved log output from different sources. More...

#include <ndc.h>

Public Types
typedef std::pair< LogString, LogString >	DiagnosticContext
	Pair of Message and FullMessage.

typedef std::stack< DiagnosticContext >	Stack

Public Member Functions
	NDC (const std::string &message)
	Add `message` onto the context stack.

	~NDC ()
	Remove the topmost element from the context stack associated with the current thread.

	NDC (const std::wstring &message)
	Add `message` onto the context stack.

	NDC (const std::basic_string< UniChar > &message)
	Add `message` onto the context stack.

	NDC (const CFStringRef &message)
	Add `message` onto the context stack.

Static Public Member Functions
static void	clear ()
	Clear any nested diagnostic information if any.

static Stack *	cloneStack ()
	Clone the diagnostic context for the current thread.

static void	inherit (Stack *stack)
	Inherit the diagnostic context of another thread.

static bool	get (LogString &dest)
	Get the current value of the NDC of the currrent thread.

static int	getDepth ()
	Get the current nesting depth of this diagnostic context.

static bool	empty ()
	Tests if the NDC is empty.

static LogString	pop ()
	Get the value at the top of the stack associated with the current thread and then remove it.

static bool	pop (std::string &buf)
	Append to `buf` the top value in the stack associated with the current thread and then remove it.

static LogString	peek ()
	Get the value at the top of the stack associated with the current thread without removing it.

static bool	peek (std::string &buf)
	Append to `buf` the top value in the stack associated with the current thread without removing it.

static void	push (const std::string &message)
	Add `message` to the stack associated with the current thread.

static void	pushLS (const LogString &message)
	Add `message` to the stack associated with the current thread.

static void	remove ()
	Remove all the diagnostic context data for this thread.

static void	push (const std::wstring &message)
	Add `message` to the stack associated with the current thread.

static bool	peek (std::wstring &dst)
	Append to `dst` the top value in the stack associated with the current thread without removing it.

static bool	pop (std::wstring &dst)
	Appends the current NDC content to the provided string and removes the value from the NDC.

static void	push (const std::basic_string< UniChar > &message)
	Add `message` to the stack associated with the current thread.

static bool	peek (std::basic_string< UniChar > &dst)
	Append to `dst` the top value in the stack associated with the current thread without removing it.

static bool	pop (std::basic_string< UniChar > &dst)
	Append to `dst` the top value in the stack associated with the current thread and then remove it.

static void	push (const CFStringRef &message)
	Add `message` to the stack associated with the current thread.

static bool	peek (CFStringRef &dst)
	Append to `dst` the top value in the stack associated with the current thread without removing it.

static bool	pop (CFStringRef &dst)
	Append to `dst` the top value in the stack associated with the current thread and then remove it.

Detailed Description

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-simultaneously. Interleaved log output can still be meaningful if each log entry from different contexts have a distinctive stamp. This is where contexts come into play.

NDC provides a constructor and destructor which simply call the push and pop methods, allowing for automatic cleanup when the current scope ends.

NDC operations such as push, pop, clear and remove affect only logging events emitted in the calling thread. The contexts of other threads are not changed. That is, contexts are managed on a per thread basis.

For example, a servlet can build a per client request context consisting of the client's host name and other information contained in the the request. Cookies are another source of distinctive information.

Contexts can be nested:

when entering a context, initialize a log4cxx::NDC type variable with a distinctive string. If there is no nested diagnostic context for the current thread, a NDC stack will be created. The distinctive string will be automatically removed from the current thread's context stack when the variable goes out of scope.
when exiting a thread call NDC::remove to deal with any push operation not matched with a corresponding pop.

If configured to do so, PatternLayout, xml::XMLLayout and JSONLayout instances automatically retrieve the nested diagnostic context for the current thread without any user intervention. hence, even if a process is serving multiple clients simultaneously, the logging events emanating from the same code (belonging to the same logger) can still be distinguished because each client request will have a different tag.

NDC implements nested diagnostic contexts as defined by Neil Harrison in the article "Patterns for Logging Diagnostic Messages" part of the book "Pattern Languages of Program Design 3" edited by Martin et al.

Examples: trivial.cpp.

Member Typedef Documentation

◆ DiagnosticContext

typedef std::pair<LogString, LogString> log4cxx::NDC::DiagnosticContext

Pair of Message and FullMessage.

◆ Stack

typedef std::stack<DiagnosticContext> log4cxx::NDC::Stack

Constructor & Destructor Documentation

◆ NDC() [1/4]

log4cxx::NDC::NDC ( const std::string & message )

Add message onto the context stack.

See also: The push method.

Parameters

message The text added to the diagnostic context information.

◆ ~NDC()

log4cxx::NDC::~NDC ( )

Remove the topmost element from the context stack associated with the current thread.

See also: The pop method.

◆ NDC() [2/4]

log4cxx::NDC::NDC ( const std::wstring & message )

Add message onto the context stack.

See also: The push method.

Parameters

message The text added to the diagnostic context information.

◆ NDC() [3/4]

log4cxx::NDC::NDC ( const std::basic_string< UniChar > & message )

Add message onto the context stack.

See also: The push method.

Parameters

message The text added to the diagnostic context information.

◆ NDC() [4/4]

log4cxx::NDC::NDC ( const CFStringRef & message )

Add message onto the context stack.

See also: The push method.

Parameters

message The text added to the diagnostic context information.

Member Function Documentation

◆ clear()

static void log4cxx::NDC::clear ( )

static

Clear any nested diagnostic information if any.

This method is useful in cases where the same thread can be potentially used over and over in different unrelated contexts.

◆ cloneStack()

static Stack * log4cxx::NDC::cloneStack ( )

static

Clone the diagnostic context for the current thread.

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.

The child thread uses the inherit method to inherit the parent's diagnostic context.

If not passed to inherit, returned stack should be deleted by caller.

Returns: Stack A clone of the current thread's diagnostic context, will not be null.

◆ empty()

static bool log4cxx::NDC::empty ( )

static

Tests if the NDC is empty.

◆ get()

static bool log4cxx::NDC::get ( LogString & dest )

static

Get the current value of the NDC of the currrent thread.

Parameters

dest	destination to which to append content of NDC.

Returns: true if NDC is set.

◆ getDepth()

static int log4cxx::NDC::getDepth ( )

static

Get the current nesting depth of this diagnostic context.

◆ inherit()

static void log4cxx::NDC::inherit ( Stack * stack )

static

Inherit the diagnostic context of another thread.

The parent thread can obtain a reference to its diagnostic context using the cloneStack method. It should communicate this information to its child so that it may inherit the parent's diagnostic context.

The parent's diagnostic context is cloned before being inherited. In other words, once inherited, the two diagnostic contexts can be managed independently.

Parameters

stack The diagnostic context of the parent thread, will be deleted during call. If NULL, NDC will not be modified.

◆ peek() [1/5]

static LogString log4cxx::NDC::peek ( )

static

Get the value at the top of the stack associated with the current thread without removing it.

The returned value is the value that was pushed last. If no context is available, then the empty string "" is returned.

Returns: String The text of the innermost diagnostic context.

◆ peek() [2/5]

static bool log4cxx::NDC::peek ( CFStringRef & dst )

static

Append to dst the top value in the stack associated with the current thread without removing it.

Parameters

dst	to which top value is appended.

Returns: true if NDC contained at least one value.

◆ peek() [3/5]

static bool log4cxx::NDC::peek ( std::basic_string< UniChar > & dst )

static

Append to dst the top value in the stack associated with the current thread without removing it.

Parameters

dst	to which top value is appended.

Returns: true if NDC contained at least one value.

◆ peek() [4/5]

static bool log4cxx::NDC::peek ( std::string & buf )

static

Append to buf the top value in the stack associated with the current thread without removing it.

Parameters

buf	to which top value is appended.

Returns: true if NDC contained at least one value.

◆ peek() [5/5]

static bool log4cxx::NDC::peek ( std::wstring & dst )

static

Append to dst the top value in the stack associated with the current thread without removing it.

Parameters

dst	to which top value is appended.

Returns: true if NDC contained at least one value.

◆ pop() [1/5]

static LogString log4cxx::NDC::pop ( )

static

Get the value at the top of the stack associated with the current thread and then remove it.

The returned value is the value that was pushed last. If no context is available, then the empty string "" is returned.

Returns: String The text of the innermost diagnostic context.

◆ pop() [2/5]

static bool log4cxx::NDC::pop ( CFStringRef & dst )

static

Append to dst the top value in the stack associated with the current thread and then remove it.

Parameters

dst	to which top value is appended.

Returns: true if NDC contained at least one value.

◆ pop() [3/5]

static bool log4cxx::NDC::pop ( std::basic_string< UniChar > & dst )

static

Append to dst the top value in the stack associated with the current thread and then remove it.

Parameters

dst	to which top value is appended.

Returns: true if NDC contained at least one value.

◆ pop() [4/5]

static bool log4cxx::NDC::pop ( std::string & buf )

static

Append to buf the top value in the stack associated with the current thread and then remove it.

Parameters

buf	to which top value is appended.

Returns: true if NDC contained at least one value.

◆ pop() [5/5]

static bool log4cxx::NDC::pop ( std::wstring & dst )

static

Appends the current NDC content to the provided string and removes the value from the NDC.

Parameters

dst	destination.

Returns: true if NDC value set.

◆ push() [1/4]

static void log4cxx::NDC::push ( const CFStringRef & message )

static

Add message to the stack associated with the current thread.

Parameters

message The text added to the diagnostic context information.

◆ push() [2/4]

static void log4cxx::NDC::push ( const std::basic_string< UniChar > & message )

static

Add message to the stack associated with the current thread.

The contents of the message parameter is determined solely by the client.

Parameters

message The text added to the diagnostic context information.

◆ push() [3/4]

static void log4cxx::NDC::push ( const std::string & message )

static

Add message to the stack associated with the current thread.

The contents of the message parameter is determined solely by the client.

Parameters

message The text added to the diagnostic context information.

◆ push() [4/4]

static void log4cxx::NDC::push ( const std::wstring & message )

static

Add message to the stack associated with the current thread.

Parameters

message The text added to the diagnostic context information.

◆ pushLS()

static void log4cxx::NDC::pushLS ( const LogString & message )

static

Add message to the stack associated with the current thread.

The contents of the message parameter is determined solely by the client.

Parameters

message The text added to the diagnostic context information.

◆ remove()

static void log4cxx::NDC::remove ( )

static

Remove all the diagnostic context data for this thread.

A thread that adds to a diagnostic context by calling push should call this method before exiting to prevent unbounded memory usage.

The documentation for this class was generated from the following file:

ndc.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ DiagnosticContext

◆ Stack

Constructor & Destructor Documentation

◆ NDC() [1/4]

◆ ~NDC()

◆ NDC() [2/4]

◆ NDC() [3/4]

◆ NDC() [4/4]

Member Function Documentation

◆ clear()

◆ cloneStack()

◆ empty()

◆ get()

◆ getDepth()

◆ inherit()

◆ peek() [1/5]

◆ peek() [2/5]

◆ peek() [3/5]

◆ peek() [4/5]

◆ peek() [5/5]

◆ pop() [1/5]

◆ pop() [2/5]

◆ pop() [3/5]

◆ pop() [4/5]

◆ pop() [5/5]

◆ push() [1/4]

◆ push() [2/4]

◆ push() [3/4]

◆ push() [4/4]

◆ pushLS()

◆ remove()