Poco

class NestedDiagnosticContext

Library: Foundation
Package: Core
Header: Poco/NestedDiagnosticContext.h

Description

This class implements a Nested Diagnostic Context (NDC), as described in Neil Harrison's article "Patterns for Logging Diagnostic Messages" in "Pattern Languages of Program Design 3" (Addison-Wesley).

A NDC maintains a stack of context information, consisting of an informational string (e.g., a method name), as well as an optional source code line number and file name. NDCs are especially useful for tagging log messages with context information which is very helpful in a multithreaded server scenario. Every thread has its own private NDC, which is automatically created when needed and destroyed when the thread terminates.

The NDCScope (or NDC::Scope) class can be used to automatically push information at the beginning of a scope, and to pop it at the end. The poco_ndc(info) macro augments the information with a source code line number and file name.

Member Summary

Member Functions: clear, current, depth, dump, operator =, pop, push, toString

Types

Scope

typedef NDCScope Scope;

Constructors

NestedDiagnosticContext

NestedDiagnosticContext();

NestedDiagnosticContext

NestedDiagnosticContext(
    const NestedDiagnosticContext & ctx
);

Copy constructor.

Destructor

~NestedDiagnosticContext

~NestedDiagnosticContext();

Destroys the NestedDiagnosticContext.

Member Functions

clear

void clear();

Clears the NDC stack.

current static

static NestedDiagnosticContext & current();

Returns the current thread's NDC.

depth

int depth() const;

Returns the depth (number of contexts) of the stack.

dump

void dump(
    std::ostream & ostr
) const;

Dumps the stack (including line number and filenames) to the given stream. The entries are delimited by a newline.

dump

void dump(
    std::ostream & ostr,
    const std::string & delimiter
) const;

Dumps the stack (including line number and filenames) to the given stream.

operator =

NestedDiagnosticContext & operator = (
    const NestedDiagnosticContext & ctx
);

Assignment operator.

pop

void pop();

Pops the top-most context off the stack.

push

void push(
    const std::string & info
);

Pushes a context (without line number and filename) onto the stack.

push

void push(
    const std::string & info,
    int line,
    const char * filename
);

Pushes a context (including line number and filename) onto the stack. Filename must be a static string, such as the one produced by the __FILE__ preprocessor macro.

toString

std::string toString() const;

Returns the stack as a string with entries delimited by colons. The string does not contain line numbers and filenames.