class Poco::NestedDiagnosticContext

Overview

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). More…

#include <NestedDiagnosticContext.h>

class NestedDiagnosticContext
{
public:
    // typedefs

    typedef NDCScope Scope;

    // structs

    struct Context;

    // construction

    NestedDiagnosticContext();
    NestedDiagnosticContext(const NestedDiagnosticContext& ctx);

    // methods

    NestedDiagnosticContext&
    operator=(const NestedDiagnosticContext& ctx);

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

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

    void
    pop();

    int
    depth() const;

    std::string
    toString() const;

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

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

    void
    clear();

    static
    NestedDiagnosticContext&
    current();
};

Detailed Documentation

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.

Construction

NestedDiagnosticContext()

Creates the NestedDiagnosticContext.

NestedDiagnosticContext(const NestedDiagnosticContext& ctx)

Copy constructor.

Methods

NestedDiagnosticContext&
operator=(const NestedDiagnosticContext& ctx)

Assignment operator.

void
push(const std::string& info)

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

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.

void
pop()

Pops the top-most context off the stack.

int
depth() const

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

std::string
toString() const

Returns the stack as a string with entries delimited by colons.

The string does not contain line numbers and filenames.

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.

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

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

void
clear()

Clears the NDC stack.

static
NestedDiagnosticContext&
current()

Returns the current thread’s NDC.