ncbidiag.hpp

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: ncbidiag.hpp,v $
 * PRODUCTION Revision 1000.4  2004/06/01 19:07:58  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.72
 * PRODUCTION
 * ===========================================================================
 */

#ifndef CORELIB___NCBIDIAG__HPP
#define CORELIB___NCBIDIAG__HPP

/*  $Id: ncbidiag.hpp,v 1000.4 2004/06/01 19:07:58 gouriano Exp $
 * ===========================================================================
 *
 *                            PUBLIC DOMAIN NOTICE
 *               National Center for Biotechnology Information
 *
 *  This software/database is a "United States Government Work" under the
 *  terms of the United States Copyright Act.  It was written as part of
 *  the author's official duties as a United States Government employee and
 *  thus cannot be copyrighted.  This software/database is freely available
 *  to the public for use. The National Library of Medicine and the U.S.
 *  Government have not placed any restriction on its use or reproduction.
 *
 *  Although all reasonable efforts have been taken to ensure the accuracy
 *  and reliability of the software and data, the NLM and the U.S.
 *  Government do not and cannot warrant the performance or results that
 *  may be obtained by using this software or data. The NLM and the U.S.
 *  Government disclaim all warranties, express or implied, including
 *  warranties of performance, merchantability or fitness for any particular
 *  purpose.
 *
 *  Please cite the author in any work or product based on this material.
 *
 * ===========================================================================
 *
 * Author:  Denis Vakatov
 *
 *
 */

/// @file ncbidiag.hpp
///
///   Defines NCBI C++ diagnostic APIs, classes, and macros.
///
///   More elaborate documentation could be found in:
///     http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/
///            programming_manual/diag.html


#include <corelib/ncbistre.hpp>
#include <list>
#include <map>
#include <stdexcept>


/** @addtogroup Diagnostics
 *
 * @{
 */


BEGIN_NCBI_SCOPE


/// Error posting with file, line number information but without error codes.
///
/// @sa
///   ERR_POST_EX macro
#define ERR_POST(message) \
    ( NCBI_NS_NCBI::CNcbiDiag(__FILE__, __LINE__) << message << NCBI_NS_NCBI::Endm )

/// Log message only without severity, location, prefix information.
///
/// @sa
///   LOG_POST_EX macro
#define LOG_POST(message) \
    ( NCBI_NS_NCBI::CNcbiDiag(eDiag_Error, eDPF_Log) << message << NCBI_NS_NCBI::Endm )

/// Error posting with error codes.
///
/// @sa
///   ERR_POST
#define ERR_POST_EX(err_code, err_subcode, message) \
    ( NCBI_NS_NCBI::CNcbiDiag(__FILE__, __LINE__) << NCBI_NS_NCBI::ErrCode(err_code, err_subcode) << message << NCBI_NS_NCBI::Endm )

/// Log posting with error codes.
///
/// @sa
///   LOG_POST
#define LOG_POST_EX(err_code, err_subcode, message) \
    ( NCBI_NS_NCBI::CNcbiDiag(eDiag_Error, eDPF_Log) << NCBI_NS_NCBI::ErrCode(err_code, err_subcode) << message << NCBI_NS_NCBI::Endm )


#define LOG_POST_N_TIMES(count, message) \
    do { \
        static volatile int sx_to_show = count; \
        int to_show = sx_to_show; \
        if ( to_show > 0 ) { \
            LOG_POST(message); \
            sx_to_show = to_show - 1; \
        } \
    } while ( false )


#define ERR_POST_N_TIMES(count, message) \
    do { \
        static volatile int sx_to_show = count; \
        int to_show = sx_to_show; \
        if ( to_show > 0 ) { \
            ERR_POST(message); \
            sx_to_show = to_show - 1; \
        } \
    } while ( false )

#define LOG_POST_ONCE(message) LOG_POST_N_TIMES(1, message)
#define ERR_POST_ONCE(message) ERR_POST_N_TIMES(1, message)


/// Severity level for the posted diagnostics.
enum EDiagSev {
    eDiag_Info = 0, ///< Informational message
    eDiag_Warning,  ///< Warning message
    eDiag_Error,    ///< Error message
    eDiag_Critical, ///< Critical error message
    eDiag_Fatal,    ///< Fatal error -- guarantees exit(or abort)
    eDiag_Trace,    ///< Trace message
    // Limits
    eDiagSevMin = eDiag_Info,  ///< Verbosity level for min. severity
    eDiagSevMax = eDiag_Trace  ///< Verbosity level for max. severity
};


/// Severity level change state.
enum EDiagSevChange {
    eDiagSC_Unknown, ///< Status of changing severity is unknown (first call)
    eDiagSC_Disable, ///< Disable change severity level 
    eDiagSC_Enable   ///< Enable change severity level 
};


/// Which parts of the diagnostic context should be posted.
///
/// Generic appearance of the posted message is as follows:
///
///   "<file>", line <line>: <severity>: (<err_code>.<err_subcode>)
///    [<prefix1>::<prefix2>::<prefixN>] <message>\n
///    <err_code_message>\n
///    <err_code_explanation>
///
/// Example: 
///
/// - If all flags are set, and prefix string is set to "My prefix", and
///   ERR_POST(eDiag_Warning, "Take care!"):
///   "/home/iam/myfile.cpp", line 33: Warning: (2.11) [aa::bb::cc] Take care!
///
/// @sa
///   SDiagMessage::Compose()
enum EDiagPostFlag {
    eDPF_File               = 0x1, ///< Set by default #if _DEBUG; else not set
    eDPF_LongFilename       = 0x2, ///< Set by default #if _DEBUG; else not set
    eDPF_Line               = 0x4, ///< Set by default #if _DEBUG; else not set
    eDPF_Prefix             = 0x8, ///< Set by default (always)
    eDPF_Severity           = 0x10,  ///< Set by default (always)
    eDPF_ErrCode            = 0x20,  ///< Set by default (always)
    eDPF_ErrSubCode         = 0x40,  ///< Set by default (always)
    eDPF_ErrCodeMessage     = 0x100, ///< Set by default (always)
    eDPF_ErrCodeExplanation = 0x200, ///< Set by default (always)
    eDPF_ErrCodeUseSeverity = 0x400, ///< Set by default (always)
    eDPF_DateTime           = 0x80,  ///< Include date and time

    /// Set all flags.
    eDPF_All                = 0x3FFF,

    // "Unusual" flags -- not included in eDPF_All
    eDPF_OmitInfoSev        = 0x4000, ///< No sev. indication if eDiag_Info 
    eDPF_PreMergeLines      = 0x10000,///< Remove EOLs before calling handler
    eDPF_MergeLines         = 0x20000,///< Ask diag.handlers to remove EOLs

    /// Default flags to use when tracing.
    eDPF_Trace              = 0x1F,

    /// Print the posted message only; without severity, location, prefix, etc.
    eDPF_Log                = 0x0,

    /// Use global default flags (merge with).
    /// @sa SetDiagPostFlag(), UnsetDiagPostFlag(), IsSetDiagPostFlag()
    eDPF_Default            = 0x8000
};

typedef int TDiagPostFlags;  ///< Binary OR of "EDiagPostFlag"


// Forward declaration of some classes.
class CDiagBuffer;
class CDiagErrCodeInfo;



/////////////////////////////////////////////////////////////////////////////
///
/// ErrCode --
///
/// Define composition of error code.
///
/// Currently the error code is an ordered pair of <code, subcode> numbers.

class ErrCode
{
public:
    /// Constructor.
    ErrCode(int code, int subcode = 0)
        : m_Code(code), m_SubCode(subcode)
    { }
    int m_Code;         ///< Major error code number
    int m_SubCode;      ///< Minor error code number
};



class CException;

/////////////////////////////////////////////////////////////////////////////
///
/// CNcbiDiag --
///
/// Define the main NCBI Diagnostic class.

class CNcbiDiag
{
public:
    /// Constructor.
    NCBI_XNCBI_EXPORT
    CNcbiDiag(EDiagSev       sev        = eDiag_Error,  ///< Severity level
              TDiagPostFlags post_flags = eDPF_Default  ///< What info.
             );


    /// Constructor -- includes file and line# information.
    NCBI_XNCBI_EXPORT
    CNcbiDiag(const char*    file,    ///< File to write diag. messages
              size_t         line,    ///< Line number
              EDiagSev       sev          = eDiag_Error,  ///< Severity level
              TDiagPostFlags post_flags = eDPF_Default  ///< What info.
             );

    /// Destructor.
    ~CNcbiDiag(void);

    /// Put object to be formatted to diagnostic stream.
    // Some compilers need to see the body right away, but others need
    // to meet CDiagBuffer first.
    template<class X> const CNcbiDiag& operator<< (const X& x) const
#ifdef NCBI_COMPILER_MSVC
    {
        m_Buffer.Put(*this, x);
        return *this;
    }
#else
      ;
#  define NCBIDIAG_DEFER_GENERIC_PUT
#endif

    /// Insert specified error code into diagnostic stream.
    ///
    /// Example:
    ///   CNcbiDiag() << ErrCode(5,3);
    const CNcbiDiag& operator<< (const ErrCode& err_code) const;

    /// Report specified exception to diagnostic stream.
    NCBI_XNCBI_EXPORT
    const CNcbiDiag& operator<< (const CException& ex) const;

    /// Function-based manipulators.
    const CNcbiDiag& operator<< (const CNcbiDiag& (*f)(const CNcbiDiag&))
        const
    {
        return f(*this);
    }

    // Output manipulators for CNcbiDiag.

    /// Reset the content of current message.
    friend const CNcbiDiag& Reset  (const CNcbiDiag& diag);

    /// Flush current message, start new one.
    friend const CNcbiDiag& Endm   (const CNcbiDiag& diag);

    /// Flush current message, then  set a severity for the next diagnostic
    /// message to Info.
    friend const CNcbiDiag& Info    (const CNcbiDiag& diag);

    /// Flush current message, then  set a severity for the next diagnostic
    /// message to Warning.
    friend const CNcbiDiag& Warning (const CNcbiDiag& diag);

    /// Flush current message, then  set a severity for the next diagnostic
    /// message to Error.
    friend const CNcbiDiag& Error   (const CNcbiDiag& diag);

    /// Flush current message, then  set a severity for the next diagnostic
    /// message to Critical.
    friend const CNcbiDiag& Critical(const CNcbiDiag& diag);

    /// Flush current message, then  set a severity for the next diagnostic
    /// message to Fatal.
    friend const CNcbiDiag& Fatal   (const CNcbiDiag& diag);

    /// Flush current message, then  set a severity for the next diagnostic
    /// message to Trace.
    friend const CNcbiDiag& Trace   (const CNcbiDiag& diag);

    /// Get a common symbolic name for the severity levels.
    static const char* SeverityName(EDiagSev sev);

    /// Get severity from string.
    ///
    /// @param str_sev
    ///   Can be the numeric value or a symbolic name (see
    ///   CDiagBuffer::sm_SeverityName[]).
    /// @param sev
    ///   Severity level. 
    /// @return
    ///   Return TRUE if severity level known; FALSE, otherwise.
    static bool StrToSeverityLevel(const char* str_sev, EDiagSev& sev);

    /// Set file name to post.
    NCBI_XNCBI_EXPORT
    const CNcbiDiag& SetFile(const char* file) const;

    /// Set line number for post.
    const CNcbiDiag& SetLine(size_t line) const;

    /// Set error code and subcode numbers.
    const CNcbiDiag& SetErrorCode(int code = 0, int subcode = 0) const;

    /// Get severity of the current message.
    EDiagSev GetSeverity(void) const;

    /// Get file used for the current message.
    const char* GetFile(void) const;

    /// Get line number for the current message.
    size_t GetLine(void) const;

    /// Get error code of the current message.
    int GetErrorCode(void) const;

    /// Get error subcode of the current message.
    int GetErrorSubCode(void) const;

    /// Get post flags for the current message.
    /// If the post flags have "eDPF_Default" set, then in the returned flags
    /// it will be reset and substituted by current default flags.
    TDiagPostFlags GetPostFlags(void) const;

    /// Display fatal error message.
    NCBI_XNCBI_EXPORT
    static void DiagFatal(const char* file, size_t line,
                          const char* message);
    /// Display trouble error message.
    NCBI_XNCBI_EXPORT
    static void DiagTrouble(const char* file, size_t line);

    /// Assert specfied expression and report results.
    NCBI_XNCBI_EXPORT
    static void DiagAssert(const char* file, size_t line,
                           const char* expression);

    /// Display validation message.
    NCBI_XNCBI_EXPORT
    static void DiagValidate(const char* file, size_t line,
                             const char* expression, const char* message);

private:
    mutable EDiagSev       m_Severity;   ///< Severity level of current msg.
    mutable char           m_File[256];  ///< File name
    mutable size_t         m_Line;       ///< Line number
    mutable int            m_ErrCode;    ///< Error code
    mutable int            m_ErrSubCode; ///< Error subcode
            CDiagBuffer&   m_Buffer;     ///< This thread's error msg. buffer
    mutable TDiagPostFlags m_PostFlags;  ///< Bitwise OR of "EDiagPostFlag"

    /// Private copy constructor to prohibit copy.
    CNcbiDiag(const CNcbiDiag&);

    /// Private assignment operator to prohibit assignment.
    CNcbiDiag& operator= (const CNcbiDiag&);
};



/////////////////////////////////////////////////////////////////////////////
// ATTENTION:  the following functions are application-wide, i.e they
//             are not local for a particular thread
/////////////////////////////////////////////////////////////////////////////