diff options
Diffstat (limited to 'SDL_Core/src/thirdPartyLibs/logger/log4cplus-1.1.0/include/log4cplus/ndc.h')
| -rw-r--r-- | SDL_Core/src/thirdPartyLibs/logger/log4cplus-1.1.0/include/log4cplus/ndc.h | 332 |
1 files changed, 332 insertions, 0 deletions
diff --git a/SDL_Core/src/thirdPartyLibs/logger/log4cplus-1.1.0/include/log4cplus/ndc.h b/SDL_Core/src/thirdPartyLibs/logger/log4cplus-1.1.0/include/log4cplus/ndc.h new file mode 100644 index 000000000..8acf49d09 --- /dev/null +++ b/SDL_Core/src/thirdPartyLibs/logger/log4cplus-1.1.0/include/log4cplus/ndc.h @@ -0,0 +1,332 @@ +// -*- C++ -*- +// Module: Log4CPLUS +// File: ndc.h +// Created: 6/2001 +// Author: Tad E. Smith +// +// +// Copyright 2001-2010 Tad E. Smith +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +/** @file + * This header defined the NDC class. + */ + +#ifndef _LO4CPLUS_NDC_HEADER_ +#define _LO4CPLUS_NDC_HEADER_ + +#include <log4cplus/config.hxx> + +#if defined (LOG4CPLUS_HAVE_PRAGMA_ONCE) +#pragma once +#endif + +#include <log4cplus/tstring.h> + +#include <map> +#include <deque> + + +namespace log4cplus { + // Forward declarations + struct DiagnosticContext; + typedef std::deque<DiagnosticContext> DiagnosticContextStack; + + /** + * 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. + * + * 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 had a distinctive stamp. This is where NDCs + * come into play. + * + * <em><b>Note that NDCs are managed on a per thread + * basis</b></em>. NDC operations such as {@link #push}, {@link + * #pop}, {@link #clear}, {@link #getDepth} and {@link #setMaxDepth} + * affect the NDC of the <em>current</em> thread only. NDCs of other + * threads remain unaffected. + * + * For example, a server can build a per client request NDC + * consisting the clients host name and other information contained in + * the the request. <em>Cookies</em> are another source of distinctive + * information. To build an NDC one uses the {@link #push} + * operation. Simply put, + * + * <ul> + * <li>Contexts can be nested. + * + * <li>When entering a context, call <code>getNDC().push()</code>. As a + * side effect, if there is no nested diagnostic context for the + * current thread, this method will create it. + * + * <li>When leaving a context, call <code>getNDC().pop()</code>. + * + * <li><b>When exiting a thread make sure to call {@link #remove + * NDC.remove()}</b>. + * </ul> + * + * 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. Use of the {@link NDCContextCreator} + * class can automate this process and make your code exception-safe. + * + * If configured to do so, {@link log4cplus::PatternLayout} and + * {@link log4cplus::TTCCLayout} instances automatically retrieve + * the nested diagnostic context for the current thread 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 logger) can still be + * distinguished because each client request will have a different + * NDC tag. + * + * Heavy duty systems should call the {@link #remove} method when + * leaving the run method of a thread. This ensures that the memory + * used by the thread can be freed. + * + * A thread may inherit the nested diagnostic context of another + * (possibly parent) thread using the {@link #inherit inherit} + * method. A thread may obtain a copy of its NDC with the {@link + * #cloneStack cloneStack} method and pass the reference to any other + * thread, in particular to a child. + */ + class LOG4CPLUS_EXPORT NDC + { + public: + /** + * 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. + * + * This method is equivalent to calling the {@link #setMaxDepth} + * method with a zero <code>maxDepth</code> argument. + */ + void clear(); + + /** + * 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 {@link #inherit inherit} method to + * inherit the parent's diagnostic context. + * + * @return Stack A clone of the current thread's diagnostic context. + */ + DiagnosticContextStack cloneStack() const; + + /** + * Inherit the diagnostic context of another thread. + * + * The parent thread can obtain a reference to its diagnostic + * context using the {@link #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. + * + * @param stack The diagnostic context of the parent thread. + */ + void inherit(const DiagnosticContextStack& stack); + + /** + * Used when printing the diagnostic context. + */ + log4cplus::tstring const & get() const; + + /** + * Get the current nesting depth of this diagnostic context. + * + * @see #setMaxDepth + */ + std::size_t getDepth() const; + + /** + * Clients should call this method before leaving a diagnostic + * context. + * + * The returned value is the value that was pushed last. If no + * context is available, then the empty string "" is + * returned. If each call to push() is paired with a call to + * pop() (even in presence of thrown exceptions), the last + * pop() call frees the memory used by NDC for this + * thread. Otherwise, remove() must be called at the end of + * the thread to free the memory used by NDC for the thread. + * + * @return String The innermost diagnostic context. + * + * @see NDCContextCreator, remove(), push() + */ + log4cplus::tstring pop(); + + /** + * Same as pop() but without the return value. + */ + void pop_void (); + + /** + * Looks at the last diagnostic context at the top of this NDC + * without removing it. + * + * 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. + */ + log4cplus::tstring const & peek() const; + + /** + * Push new diagnostic context information for the current thread. + * + * The contents of the <code>message</code> parameter is + * determined solely by the client. Each call to push() should + * be paired with a call to pop(). + * + * @param message The new diagnostic context information. + * + * @see NDCContextCreator, pop(), remove() + */ + void push(const log4cplus::tstring& message); + void push(tchar const * message); + + /** + * Remove the diagnostic context for this thread. + * + * Each thread that created a diagnostic context by calling + * push() should call this method before exiting. Otherwise, + * the memory used by the thread cannot be reclaimed. It is + * possible to omit this call if and only if each push() call + * is always paired with a pop() call (even in presence of + * thrown exceptions). Then the memory used by NDC will be + * returned by the last pop() call and a call to remove() will + * be no-op. + */ + void remove(); + + /** + * Set maximum depth of this diagnostic context. If the current + * depth is smaller or equal to <code>maxDepth</code>, then no + * action is taken. + * + * This method is a convenient alternative to multiple {@link + * #pop} calls. Moreover, it is often the case that at the end of + * complex call sequences, the depth of the NDC is + * unpredictable. The <code>setMaxDepth</code> method circumvents + * this problem. + * + * For example, the combination + * <pre> + * void foo() { + * std::size_t depth = NDC.getDepth(); + * + * ... complex sequence of calls + * + * NDC.setMaxDepth(depth); + * } + * </pre> + * + * ensures that between the entry and exit of foo the depth of the + * diagnostic stack is conserved. + * + * <b>Note:</b> Use of the {@link NDCContextCreator} class will solve + * this particular problem. + * + * @see #getDepth + */ + void setMaxDepth(std::size_t maxDepth); + + // Public ctor but only to be used by internal::DefaultContext. + NDC(); + + // Dtor + virtual ~NDC(); + + private: + // Methods + LOG4CPLUS_PRIVATE static DiagnosticContextStack* getPtr(); + + template <typename StringType> + LOG4CPLUS_PRIVATE + void push_worker (StringType const &); + + // Disallow construction (and copying) except by getNDC() + NDC(const NDC&); + NDC& operator=(const NDC&); + }; + + + /** + * Return a reference to the singleton object. + */ + LOG4CPLUS_EXPORT NDC& getNDC(); + + + /** + * This is the internal object that is stored on the NDC stack. + */ + struct LOG4CPLUS_EXPORT DiagnosticContext + { + // Ctors + DiagnosticContext(const log4cplus::tstring& message, + DiagnosticContext const * parent); + DiagnosticContext(tchar const * message, + DiagnosticContext const * parent); + DiagnosticContext(const log4cplus::tstring& message); + DiagnosticContext(tchar const * message); + DiagnosticContext(DiagnosticContext const &); + DiagnosticContext & operator = (DiagnosticContext const &); + +#if defined (LOG4CPLUS_HAVE_RVALUE_REFS) + DiagnosticContext(DiagnosticContext &&); + DiagnosticContext & operator = (DiagnosticContext &&); +#endif + + void swap (DiagnosticContext &); + + // Data + log4cplus::tstring message; /*!< The message at this context level. */ + log4cplus::tstring fullMessage; /*!< The entire message stack. */ + }; + + + /** + * This class ensures that a {@link NDC#push} call is always matched with + * a {@link NDC#pop} call even in the face of exceptions. + */ + class LOG4CPLUS_EXPORT NDCContextCreator { + public: + /** Pushes <code>msg</code> onto the NDC stack. */ + NDCContextCreator(const log4cplus::tstring& msg); + NDCContextCreator(tchar const * msg); + + /** Pops the NDC stack. */ + ~NDCContextCreator(); + }; + +} // end namespace log4cplus + + +#endif // _LO4CPLUS_NDC_HEADER_ |