JrmDebugLog.hpp File Reference

Copyright

JRM Enterprises, Inc.

More...

Go to the source code of this file.

Classes
class	jrm::DebugStreamAdapter
	This class implements a mechanism that logs to an arbitrary ostream. More...

Namespaces
namespace	jrm

Macros
#define	JRM_DBG1_STMT   JRM_DBG(jrm::DebugLevel_Debug1)
	These are shorthand for declaring debug statements at the globally-defined levels.
#define	JRM_DBG2_STMT   JRM_DBG(jrm::DebugLevel_Debug2)
	These are shorthand for declaring debug statements at the globally-defined levels.
#define	JRM_DBG3_STMT   JRM_DBG(jrm::DebugLevel_Debug3)
	These are shorthand for declaring debug statements at the globally-defined levels.
#define	JRM_DBG4_STMT   JRM_DBG(jrm::DebugLevel_Debug4)
	These are shorthand for declaring debug statements at the globally-defined levels.
#define	JRM_DBG5_STMT   JRM_DBG(jrm::DebugLevel_Debug5)
	These are shorthand for declaring debug statements at the globally-defined levels.
#define	JRM_ERR   JRM_LOG(jrm::DebugLevel_LogError)
	Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.
#define	JRM_CRI   JRM_LOG(jrm::DebugLevel_LogCritical)
	Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.
#define	JRM_WRN   JRM_LOG(jrm::DebugLevel_LogWarning)
	Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.
#define	JRM_INF   JRM_LOG(jrm::DebugLevel_LogInfo)
	Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.
#define	JRM_DBG1   JRM_LOG(jrm::DebugLevel_Debug1)
	Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.
#define	JRM_DBG2   JRM_LOG(jrm::DebugLevel_Debug2)
	Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.
#define	JRM_DBG3   JRM_LOG(jrm::DebugLevel_Debug3)
	Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.
#define	JRM_DBG4   JRM_LOG(jrm::DebugLevel_Debug4)
	Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.
#define	JRM_DBG5   JRM_LOG(jrm::DebugLevel_Debug5)
	Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.
#define	JRM_ERR2(insertions)   JRM_LOG2(jrm::DebugLevel_LogError, std::cerr, insertions)
	Writes the given stream insertions to both the log and associated stream.
#define	JRM_CRI2(insertions)   JRM_LOG2(jrm::DebugLevel_LogCritical, std::cout, insertions)
	Writes the given stream insertions to both the log and associated stream.
#define	JRM_WRN2(insertions)   JRM_LOG2(jrm::DebugLevel_LogWarning, std::cerr, insertions)
	Writes the given stream insertions to both the log and associated stream.
#define	JRM_INF2(insertions)   JRM_LOG2(jrm::DebugLevel_LogInfo, std::cout, insertions)
	Writes the given stream insertions to both the log and associated stream.
#define	JRM_HERE   (boost::filesystem::path(__FILE__).filename().string() + "[" + boost::lexical_cast<std::string>(__LINE__) + "]")
	Expands to a std::string containing the current file name, line number, and function.
#define	JRM_DBG(level)
	Executes the next statement if module debugging is "on" and the module debug level meets or exceeds the given statement level.
#define	JRM_LOG(level)   JRM_LOG_HELPER((level))
	Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the specified threshold debug level is met or exceeded.
#define	JRM_LOG_HELPER(level)
#define	JRM_LOG2(level, ostream, insertions)
	Applies the given stream insertions to both the log and the given stream.

Enumerations
enum	jrm::DebugLevel {   jrm::DebugLevel_Off, jrm::DebugLevel_UseGlobal, jrm::DebugLevel_LogError, jrm::DebugLevel_LogCritical,   jrm::DebugLevel_LogWarning, jrm::DebugLevel_LogInfo, jrm::DebugLevel_Debug1, jrm::DebugLevel_Debug2,   jrm::DebugLevel_Debug3, jrm::DebugLevel_Debug4, jrm::DebugLevel_Debug5, jrm::DebugLevel_CustomBase }
	Defines debug levels having special meaning. More...

Functions
JrmUtilsDllLinkage std::string	jrm::ToString (const DebugLevel &value)
	Returns a human-readable string representation of the given value.

Variables
static DebugLevel	jrm::ModuleDebugLevel = DebugLevel_UseGlobal
	Threshold value used to control debug code execution and logging verbosity for the current "module" (i.e.
JrmUtilsDllLinkage DebugLevel	jrm::GlobalDebugLevel
	Threshold value used to control debug code execution and logging verbosity for any module whose module-relative debug level is set to DebugLevel_UseGlobal.

Detailed Description

Copyright

JRM Enterprises, Inc.

2006 - 2013. All rights reserved.

Attention

This code is the intellectual property of JRM Enterprises, Inc. It may not be used or released as source or compiled binary form without the prior written consent of JRM Enterprises, Inc.

Author

Lou Barbieri

Date

2013-11-06

This module implements a logging mechanism that may be throttled based upon module-relative and / or global thresholds.

This module implements:

1. A simple "debug level / threshold" mechanism that may be used to control execution of debugging code based upon an associated debug level and module-relative threshold. A block of debugging code specifies the minimum debug threshold at which the code is executed. Only when the module's debug level is set equal or higher will the code be run. The higher the module's debug level is set, the more debugging code is run. An enum is used to assign meaning to certain debug levels. Modules may associate arbitrary meaning to levels higher than "info", e.g. "debug1" means log all method parameters, "debug2" means calculate extra diagnostic info, etc.

1. A simple "debug log" mechanism that writes formatted messages to an arbitrary ostream. The format is a table that includes these columns (items a-c are auto-generated): a. A high-resolution timestamp. b. Invoking thread ID. c. Invoking code location (i.e. file name, line number, and function name). d. An arbitrary message.

   The log mechanism leverages the debug level mechanism to be more verbose at higher debug levels.

Example usage:

Overview:

    In general, each module or main() method should add this code once to use the mechanisms described here:

        // Must call this for logging to be enabled.  Only the first call actually creates the object, so main() should call it early to preempt any calls by subordinate modules.
        // Optionally takes an ostream to which to write.  Default is std::cout.
        jrm::DebugStreamAdapter::Create();

        // Optional, but may be useful to set in main() from a command line parameter or environment variable.  Default is jrm::DebugLevel_Info.
        jrm::GlobalDebugLevel = jrm::DebugLevel_Info;

Debug statements:

    By default, the module-relative debug level is set to a value meaning to use whatever the global debug level is.
    This allows a module to use the log mechanism without any added effort.  However you may change this on a per-module basis by setting
    jrm::ModuleDebugLevel directly, e.g. "jrm::ModuleDebugLevel = jrm::DebugLevel_Off" to disable the mechanism for the current compilation unit.

    1.  JRM_DBG1_STMT
        {
            // Multiple lines of debugging code that is only executed at debug levels >= jrm::DebugLevel_Debug1.
        }

    2.  JRM_DBG3_STMT singleDbgStmt();

Log statements:

    For log statements to be written anywhere, first call:

        jrm::DebugStreamAdapter::Create();

    Otherwise logging will be disabled and statements will simply be ignored.

    1.  JRM_INF << "stuff to log at log level " << jrm::DebugLevel_Info << endl;

    2.  JRM_ERR << "log an error!" << endl;

    3.  JRM_DBG3 << "log this when we've cranked-up the log level" << endl;

Note

Most functionality defined here is desiged to be invoked via macros also defined here (e.g. JRM_*).

See Also

See the macro(s) at the top of this file for typical usage.

Macro Definition Documentation

#define JRM_DBG1_STMT   JRM_DBG(jrm::DebugLevel_Debug1)

These are shorthand for declaring debug statements at the globally-defined levels.

Use these per the examples given in the Detailed Description of this file.

#define JRM_DBG2_STMT   JRM_DBG(jrm::DebugLevel_Debug2)

These are shorthand for declaring debug statements at the globally-defined levels.

Use these per the examples given in the Detailed Description of this file.

#define JRM_DBG3_STMT   JRM_DBG(jrm::DebugLevel_Debug3)

These are shorthand for declaring debug statements at the globally-defined levels.

Use these per the examples given in the Detailed Description of this file.

#define JRM_DBG4_STMT   JRM_DBG(jrm::DebugLevel_Debug4)

These are shorthand for declaring debug statements at the globally-defined levels.

Use these per the examples given in the Detailed Description of this file.

#define JRM_DBG5_STMT   JRM_DBG(jrm::DebugLevel_Debug5)

These are shorthand for declaring debug statements at the globally-defined levels.

Use these per the examples given in the Detailed Description of this file.

#define JRM_ERR   JRM_LOG(jrm::DebugLevel_LogError)

Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.

Use these per the examples given in the Detailed Description of this file, e.g.:

JRM_WRN << "my message to be logged when debug level is >= warning" << endl; 

#define JRM_CRI   JRM_LOG(jrm::DebugLevel_LogCritical)

Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.

Use these per the examples given in the Detailed Description of this file, e.g.:

JRM_WRN << "my message to be logged when debug level is >= warning" << endl; 

#define JRM_WRN   JRM_LOG(jrm::DebugLevel_LogWarning)

Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.

Use these per the examples given in the Detailed Description of this file, e.g.:

JRM_WRN << "my message to be logged when debug level is >= warning" << endl; 

#define JRM_INF   JRM_LOG(jrm::DebugLevel_LogInfo)

Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.

Use these per the examples given in the Detailed Description of this file, e.g.:

JRM_WRN << "my message to be logged when debug level is >= warning" << endl; 

#define JRM_DBG1   JRM_LOG(jrm::DebugLevel_Debug1)

Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.

Use these per the examples given in the Detailed Description of this file, e.g.:

JRM_WRN << "my message to be logged when debug level is >= warning" << endl; 

#define JRM_DBG2   JRM_LOG(jrm::DebugLevel_Debug2)

Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.

Use these per the examples given in the Detailed Description of this file, e.g.:

JRM_WRN << "my message to be logged when debug level is >= warning" << endl; 

#define JRM_DBG3   JRM_LOG(jrm::DebugLevel_Debug3)

Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.

Use these per the examples given in the Detailed Description of this file, e.g.:

JRM_WRN << "my message to be logged when debug level is >= warning" << endl; 

#define JRM_DBG4   JRM_LOG(jrm::DebugLevel_Debug4)

Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.

Use these per the examples given in the Detailed Description of this file, e.g.:

JRM_WRN << "my message to be logged when debug level is >= warning" << endl; 

#define JRM_DBG5   JRM_LOG(jrm::DebugLevel_Debug5)

Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the named debug level is met or exceeded.

Use these per the examples given in the Detailed Description of this file, e.g.:

JRM_WRN << "my message to be logged when debug level is >= warning" << endl; 

#define JRM_ERR2

(

insertions

)

JRM_LOG2(jrm::DebugLevel_LogError, std::cerr, insertions)

Writes the given stream insertions to both the log and associated stream.

Applies the given stream insertions to:

• The log, if it has been created and the named threshold debug level is met or exceeded, AND
• The stream associated with the named debug level, unless it is the same stream used to create the log. So the insertions are ALWAYS written to the given stream EXCEPT in the special case where the given stream was used to create the log, and the debug level prevents it (or is turned "off"). Example usage:

  JRM_ERR2("Failure doing some stupid thing:  " << errMsg << ", " << errCode << endl); 

Note

This is extremely useful when used from an application's main() function to be sure a message is seen, either in the log or on a standard stream.

Stderr is associated with JRM_ERR2 and JRM_WRN2, and stdout is associated with all others.

Warning

THE MESSAGE WILL NOT SHOW UP ANYWHERE IF you create the log from the same stream associated with your message but the log level prevents it (or is set to "off"). This is by design.

Parameters

[in]

insertions

Chain of stream insertion operations to apply (without the usual leading stream) e.g.: "stuff you want " << " to be sure " << " gets logged " << endl

#define JRM_CRI2

(

insertions

)

JRM_LOG2(jrm::DebugLevel_LogCritical, std::cout, insertions)

Writes the given stream insertions to both the log and associated stream.

Applies the given stream insertions to:

• The log, if it has been created and the named threshold debug level is met or exceeded, AND
• The stream associated with the named debug level, unless it is the same stream used to create the log. So the insertions are ALWAYS written to the given stream EXCEPT in the special case where the given stream was used to create the log, and the debug level prevents it (or is turned "off"). Example usage:

  JRM_ERR2("Failure doing some stupid thing:  " << errMsg << ", " << errCode << endl); 

Note

This is extremely useful when used from an application's main() function to be sure a message is seen, either in the log or on a standard stream.

Stderr is associated with JRM_ERR2 and JRM_WRN2, and stdout is associated with all others.

Warning

THE MESSAGE WILL NOT SHOW UP ANYWHERE IF you create the log from the same stream associated with your message but the log level prevents it (or is set to "off"). This is by design.

Parameters

[in]

insertions

Chain of stream insertion operations to apply (without the usual leading stream) e.g.: "stuff you want " << " to be sure " << " gets logged " << endl

#define JRM_WRN2

(

insertions

)

JRM_LOG2(jrm::DebugLevel_LogWarning, std::cerr, insertions)

Writes the given stream insertions to both the log and associated stream.

Applies the given stream insertions to:

• The log, if it has been created and the named threshold debug level is met or exceeded, AND
• The stream associated with the named debug level, unless it is the same stream used to create the log. So the insertions are ALWAYS written to the given stream EXCEPT in the special case where the given stream was used to create the log, and the debug level prevents it (or is turned "off"). Example usage:

  JRM_ERR2("Failure doing some stupid thing:  " << errMsg << ", " << errCode << endl); 

Note

This is extremely useful when used from an application's main() function to be sure a message is seen, either in the log or on a standard stream.

Stderr is associated with JRM_ERR2 and JRM_WRN2, and stdout is associated with all others.

Warning

THE MESSAGE WILL NOT SHOW UP ANYWHERE IF you create the log from the same stream associated with your message but the log level prevents it (or is set to "off"). This is by design.

Parameters

[in]

insertions

Chain of stream insertion operations to apply (without the usual leading stream) e.g.: "stuff you want " << " to be sure " << " gets logged " << endl

#define JRM_INF2

(

insertions

)

JRM_LOG2(jrm::DebugLevel_LogInfo, std::cout, insertions)

Writes the given stream insertions to both the log and associated stream.

Applies the given stream insertions to:

• The log, if it has been created and the named threshold debug level is met or exceeded, AND
• The stream associated with the named debug level, unless it is the same stream used to create the log. So the insertions are ALWAYS written to the given stream EXCEPT in the special case where the given stream was used to create the log, and the debug level prevents it (or is turned "off"). Example usage:

  JRM_ERR2("Failure doing some stupid thing:  " << errMsg << ", " << errCode << endl); 

Note

This is extremely useful when used from an application's main() function to be sure a message is seen, either in the log or on a standard stream.

Stderr is associated with JRM_ERR2 and JRM_WRN2, and stdout is associated with all others.

Warning

THE MESSAGE WILL NOT SHOW UP ANYWHERE IF you create the log from the same stream associated with your message but the log level prevents it (or is set to "off"). This is by design.

Parameters

[in]

insertions

Chain of stream insertion operations to apply (without the usual leading stream) e.g.: "stuff you want " << " to be sure " << " gets logged " << endl

#define JRM_HERE   (boost::filesystem::path(__FILE__).filename().string() + "[" + boost::lexical_cast<std::string>(__LINE__) + "]")

Expands to a std::string containing the current file name, line number, and function.

#define JRM_DBG

(

level

)

Value:

if (jrm::ModuleDebugLevel != jrm::DebugLevel_Off && \
            ((jrm::ModuleDebugLevel == jrm::DebugLevel_UseGlobal) ? (jrm::GlobalDebugLevel) : (jrm::ModuleDebugLevel)) >= (level))

Executes the next statement if module debugging is "on" and the module debug level meets or exceeds the given statement level.

    The next statement may be a compound statement (i.e. enclosed in curly braces) to guard multiple lines of debug code based upon the debugging level.

Parameters

[in]

level

The debug level at which the module-relative debug threshold must be set (or above) for the next statement to be executed. This should be a jrm::DebugLevel value, as it defines levels with global meaning.

Note

When the module debugging is "off", or the module's debug level is below the given level, the guarded code is not executed and so incurs no performance hit.

#define JRM_LOG

(

level

)

JRM_LOG_HELPER((level))

Logs the stream insertions that follow to the stream passed to jrm::DebugStreamAdapter::Create() when the specified threshold debug level is met or exceeded.

Parameters

[in]

level

The debug level at which the module-relative debug threshold must be set (or above) for the next statement to be executed. This should be a jrm::DebugLevel value, as it defines levels with global meaning.

Warning

Not intented to be used directly. Instead use macros JRM_INF, JRM_WRN, JRM_ERR, etc.

#define JRM_LOG_HELPER

(

level

)

Value:

JRM_DBG(level) \
    if (jrm::DebugStreamAdapter::Get()) \
        (*jrm::DebugStreamAdapter::Get()) = (jrm::DebugStreamAdapter::Get()->prepare(level, JRM_HERE))

#define JRM_LOG2	(		level,
			ostream,
			insertions
	)

Value:

{ /* Important that these are grouped into a statement block to support usage like "if (cond) JRM_INF2 << "stuff" << endl;" */ \
    { JRM_LOG((level)) << insertions; } \
    if (!jrm::DebugStreamAdapter::Get() || typeid(jrm::DebugStreamAdapter::Get()->stream()) != typeid(ostream)) { (ostream) << insertions; } \
    }

Applies the given stream insertions to both the log and the given stream.

Applies the given stream insertions to:

• The log, if it has been created and the given threshold debug level is met or exceeded, AND
• The given stream, unless it is the same stream used to create the log. So the insertions are ALWAYS written to the given stream EXCEPT in the special case where the given stream was used to create the log, and the debug level prevents it (or is turned "off").

Parameters

[in]	level	The debug level at which the module-relative debug threshold must be set (or above) for the next statement to be executed. This should be a jrm::DebugLevel value, as it defines levels with global meaning.
[in,out]	ostream	Stream to which to apply the given insertions in the absence of the log, e.g. std::cout, std::cerr.
[in]	insertions	Chain of stream insertion operations to apply (without the usual leading stream) e.g.: "stuff you want " << " to be sure " << " gets logged " << endl

Warning

Not intented to be used directly. Instead use macros JRM_INF2, JRM_WRN2, JRM_ERR2, etc.

Note

The braces in the macro defintion are required for this to work.