This concrete class provide a 'printf' tracing mechanism. More...

Detailed Description

This concrete class provide a 'printf' tracing mechanism.

The output of tracing messages typically defaults (dependent on the target platform) to stdout. However, the output cat be redirected to any Cpl::Stream::Output instance.

The trace engine is thread safe, i.e. it guarantees that outputting a single trace message (info + user msg) is an Atomic operation within a multi-thread environment.

All of the ‘methods SHOULD be access via the preprocessor macros below to allow the 'trace code’ to be compiled out of a 'release' build if desired. In addition to a compile time decision to use/exclude tracing, there are run-time switches to selective enable and/or control what is displayed.

There are numerous application customizable (at compile time) options for how the internals of how the trace engine works (see OPTION_xxx macros below).

NOTE: The trace engine supports does NOT support tracing BEFORE the Colony library is initialized. This means that constructors of objects that are created statically can NOT contain trace logging calls.


    For trace message to appear on the logging media the following
    must done:
1. Enable Trace at compile time by defining the USE_CPL_SYSTEM_TRACE
   preprocessor symbol.
2. Enable the Trace engine at run time by calling CPL_SYSTEM_TRACE_ENABLE()
3. Enable at least one 'section' by calling CPL_SYSTEM_TRACE_ENABLE_SECTION()

How to use the CPL_SYSTEM_TRACE_xxx macros


    The trace functionality is provided by the CPL_SYSTEM_TRACE and
    CPL_SYSTEM_TRACEMSG macros.  The remaining macros are used to enable/disable
    and control the actual trace output.  If the symbol, USE_CPL_SYSTEM_TRACE,
    is NOT defined at compile time – all of the trace macros are compiled
    out.  If the symbol is defined, then the trace output can be enabled
    and disabled at run time.

    CPL_SYSTEM_TRACE()    - This macro is used to trace the entry and exit of a
                            scope block (a scope block is a pair of '{}').
                            For example:
                                void foobar( int x )
                                    {
                                    // Traces the entry & exit of foobar(), when
                                    // tracing is enabled for section "bob"
                                    CPL_SYSTEM_TRACE("bob");
                                    int y = 2*x;
                                    ...
                                    }

    CPL_SYSTEM_TRACEMSG() - This macro is for the programmer/application to
                            generate formatted message that are outputted to the
                            "trace media." The macro has printf() semantics.
                            The problem is that ANSI C++03 does not directly
                            support var_args in a macro - so you HAVE TO USE AN
                            EXTRA SET OF '()'.

                            For example:
                                void foobar( int x )
                                    {
                                    // Traces the entry & exit of foobar(), when
                                    // tracing is enabled for section "bob"
                                    CPL_SYSTEM_TRACE("bob");
                                    int y = 2*x;
                                    ...
                                    // Trace message outputs when tracing is
                                    // enabled for section "bob"
                                    CPL_SYSTEM_TRACEMSG( "bob, ("This is an example Trace Msg. Y=d, X=d", y, x) );
                                    ...
                                    }

#include <Trace.h>

Public Types
enum	InfoLevel_T { eNONE =0 , eBRIEF , eINFO , eVERBOSE , eMAX }
	This enum is used to globally control the amount of 'Prologue' information that is prepended to the Trace log messages. More...

Public Member Functions
	Trace (const char filename, int linenum, const char funcname, const char section, const char scope_name)
	Constructor.

	~Trace ()
	Destructor.

Static Public Member Functions
static void	traceLocation_ (const char section, const char filename, int linenum, const char *funcname)
	This function is used to trace the 'location' for general purpose trace messages.

static void	traceUserMsg_ (const char *format,...)
	This function is used to generate general purpose trace messages.

static void	enable_ (void)
	This method enables the output/logging of trace message at run-time.

static void	disable_ (void)
	This method disables the output/logging of trace message at run-time.

static bool	isEnabled_ (void)
	Returns true if tracing is enabled, i.e.

static InfoLevel_T	setInfoLevel_ (InfoLevel_T newLevel)
	This method sets the information level for the trace messages.

static InfoLevel_T	getInfoLevel_ (void) noexcept
	This method returns the current information level setting.

static bool	enableSection_ (const char *sectionToEnable)
	This method enables the output/logging of trace message at run-time for the specified 'section'.

static void	disableSection_ (const char *sectionToDisable)
	This method disables the output/logging of trace message at run-time for the specified 'section'.

static bool	isSectionEnabled_ (const char *section)
	Returns true if tracing is enabled AND the specified 'section' has been enabled.

static unsigned	getSections_ (Cpl::Text::String &dst)
	This method returns the number of enabled 'sections' and returns the actual section name(s) via the String 'dst'.

static void	setThreadFilter_ (const char threadName1, const char threadName2=0, const char threadName3=0, const char threadName4=0)
	This method applies a filter by thread name when generating output, i.e.

static unsigned	getThreadFilters_ (Cpl::Text::String &dst)
	This method returns the number of enabled 'thread filters' and returns the actual thread name(s) via the String 'dst'.

static void	clearThreadFilter_ (void)
	This method removes that thread filter (if there is one present).

static bool	passedThreadFilter_ ()
	This method returns true if the thread filter has been set and the current thread's name 'passes' the thread filter check, i.e.

static void	redirect_ (Cpl::Io::Output &newMedia)
	This method is used to redirect the trace output to the provided Output stream.

static void	revert_ (void)
	This method is used to revert the trace output to its default output destination/stream/media.

static Cpl::Io::Output *	getDefaultOutputStream_ (void) noexcept
	This COMPONENT Scoped method provides the Output stream to the Trace Engine.

Protected Attributes
const char *	m_filename
	Caches trace info for exit message.

int	m_linenum
	Caches trace info for exit message.

const char *	m_funcname
	Caches trace info for exit message.

const char *	m_section
	Caches trace info for exit message.

const char *	m_scope
	Caches trace info for exit message.

Member Enumeration Documentation

◆ InfoLevel_T

enum Cpl::System::Trace::InfoLevel_T

This enum is used to globally control the amount of 'Prologue' information that is prepended to the Trace log messages.

The specifics of what information is added is platform specific.

Enumerator
eNONE	Turns off ALL prologue info.
eBRIEF	Default setting.
eINFO	Additional prologue info.
eVERBOSE	more prologue info
eMAX	Maximum prologue info.

Constructor & Destructor Documentation

◆ Trace()

Cpl::System::Trace::Trace	(	const char *	filename,
		int	linenum,
		const char *	funcname,
		const char *	section,
		const char *	scope_name
	)

Constructor.

◆ ~Trace()

Cpl::System::Trace::~Trace ( )

Destructor.

Member Function Documentation

◆ clearThreadFilter_()

static void Cpl::System::Trace::clearThreadFilter_ ( void )

static

This method removes that thread filter (if there is one present).

If no filter has been applied when this method is called, then this method does nothing.

NOTE: NEVER call this method directly -->use the CPL_SYSTEM_TRACE_xxx() macros.

◆ disable_()

static void Cpl::System::Trace::disable_ ( void )

static

This method disables the output/logging of trace message at run-time.

The default is start with tracing enabled.

NOTE: NEVER call this method directly -->use the CPL_SYSTEM_TRACE_xxx() macros.

◆ disableSection_()

static void Cpl::System::Trace::disableSection_ ( const char * sectionToDisable )

static

This method disables the output/logging of trace message at run-time for the specified 'section'.

Setting 'sectionToDisable' to 0 will disable all sections.

NOTE: NEVER call this method directly -->use the CPL_SYSTEM_TRACE_xxx() macros.

◆ enable_()

static void Cpl::System::Trace::enable_ ( void )

static

This method enables the output/logging of trace message at run-time.

The default is start with tracing enabled.

NOTE: NEVER call this method directly -->use the CPL_SYSTEM_TRACE_xxx() macros.

◆ enableSection_()

static bool Cpl::System::Trace::enableSection_ ( const char * sectionToEnable )

static

This method enables the output/logging of trace message at run-time for the specified 'section'.

A 'section' name can NOT contain any white space. The method returns true if the section was enabled; else false is return, i.e. exceeded max active enabled sections.

NOTE: NEVER call this method directly -->use the CPL_SYSTEM_TRACE_xxx() macros.

◆ getDefaultOutputStream_()

static Cpl::Io::Output * Cpl::System::Trace::getDefaultOutputStream_ ( void )

staticnoexcept

This COMPONENT Scoped method provides the Output stream to the Trace Engine.

The Output stream instance MUST be created statically. However, the Output stream does not necessarily need to fully 'operational' when statically constructed - it just need to be "operationally" by the time Cpl::System::Api::initialize() is called.

NOTE: The Application is RESPONSIBLE for implementing this method!

◆ getInfoLevel_()

static InfoLevel_T Cpl::System::Trace::getInfoLevel_ ( void )

staticnoexcept

This method returns the current information level setting.

NOTE: NEVER call this method directly -->use the CPL_SYSTEM_TRACE_xxx() macros.

◆ getSections_()

static unsigned Cpl::System::Trace::getSections_ ( Cpl::Text::String & dst )

static

This method returns the number of enabled 'sections' and returns the actual section name(s) via the String 'dst'.

It is the caller responsibility to ensure that 'dst' is large enough to hold all of the enable sections. If 'dst' is to short, the results will be truncated.

NOTE: NEVER call this method directly -->use the CPL_SYSTEM_TRACE_xxx() macros.

◆ getThreadFilters_()

static unsigned Cpl::System::Trace::getThreadFilters_ ( Cpl::Text::String & dst )

static

This method returns the number of enabled 'thread filters' and returns the actual thread name(s) via the String 'dst'.

It is the caller responsibility to ensure that 'dst' is large enough to hold all of the enable thread filters. If 'dst' is to short, the results will be truncated.

NOTE: NEVER call this method directly -->use the CPL_SYSTEM_TRACE_xxx() macros.

◆ isEnabled_()

static bool Cpl::System::Trace::isEnabled_ ( void )

static

Returns true if tracing is enabled, i.e.

enable_() has been called.,

NOTE: NEVER call this method directly -->use the CPL_SYSTEM_TRACE_xxx() macros.

◆ isSectionEnabled_()

static bool Cpl::System::Trace::isSectionEnabled_ ( const char * section )

static

Returns true if tracing is enabled AND the specified 'section' has been enabled.

NOTE: NEVER call this method directly -->use the CPL_SYSTEM_TRACE_xxx() macros.

◆ passedThreadFilter_()

static bool Cpl::System::Trace::passedThreadFilter_ ( )

static

This method returns true if the thread filter has been set and the current thread's name 'passes' the thread filter check, i.e.

the specified name match one of the names in the filter list.

NOTE: NEVER call this method directly -->use the CPL_SYSTEM_TRACE_xxx() macros.

◆ redirect_()

static void Cpl::System::Trace::redirect_ ( Cpl::Io::Output & newMedia )

static

This method is used to redirect the trace output to the provided Output stream.

There is no guaranty on what happens to trace message(s) during the transition to the new output/media destination.

NOTE: NEVER call this method directly -->use the CPL_SYSTEM_TRACE_xxx() macros.

◆ revert_()

static void Cpl::System::Trace::revert_ ( void )

static

This method is used to revert the trace output to its default output destination/stream/media.

There is no guaranty on what happens to trace message(s) during the transition to the default output/media destination.

NOTE: NEVER call this method directly -->use the CPL_SYSTEM_TRACE_xxx() macros.

◆ setInfoLevel_()

static InfoLevel_T Cpl::System::Trace::setInfoLevel_ ( InfoLevel_T newLevel )

static

This method sets the information level for the trace messages.

The method returns the previous level setting.

NOTE: NEVER call this method directly -->use the CPL_SYSTEM_TRACE_xxx() macros.

◆ setThreadFilter_()

static void Cpl::System::Trace::setThreadFilter_	(	const char *	threadName1,
		const char *	threadName2 = `0`,
		const char *	threadName3 = `0`,
		const char *	threadName4 = `0`
	)

static

This method applies a filter by thread name when generating output, i.e.

for a message to be output, trace must be enabled, the message's section enabled, and must be running in the one of the threads specified by the thread filter.

NOTE: NEVER call this method directly -->use the CPL_SYSTEM_TRACE_xxx() macros.

◆ traceLocation_()

static void Cpl::System::Trace::traceLocation_	(	const char *	section,
		const char *	filename,
		int	linenum,
		const char *	funcname
	)

static

This function is used to trace the 'location' for general purpose trace messages.

NOTE: NEVER call this method directly

◆ traceUserMsg_()

static void Cpl::System::Trace::traceUserMsg_	(	const char *	format,
			...
	)

static

This function is used to generate general purpose trace messages.

NOTE: NEVER call this method directly

Member Data Documentation

◆ m_filename

const char* Cpl::System::Trace::m_filename

protected

Caches trace info for exit message.

◆ m_funcname

const char* Cpl::System::Trace::m_funcname

protected

Caches trace info for exit message.

◆ m_linenum

int Cpl::System::Trace::m_linenum

protected

Caches trace info for exit message.

◆ m_scope

const char* Cpl::System::Trace::m_scope

protected

Caches trace info for exit message.

◆ m_section

const char* Cpl::System::Trace::m_section

protected

Caches trace info for exit message.

The documentation for this class was generated from the following file:

Cpl/System/Trace.h

Detailed Description

How to use the CPL_SYSTEM_TRACE_xxx macros

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Member Enumeration Documentation

◆ InfoLevel_T

Constructor & Destructor Documentation

◆ Trace()

◆ ~Trace()

Member Function Documentation

◆ clearThreadFilter_()

◆ disable_()

◆ disableSection_()

◆ enable_()

◆ enableSection_()

◆ getDefaultOutputStream_()

◆ getInfoLevel_()

◆ getSections_()

◆ getThreadFilters_()

◆ isEnabled_()

◆ isSectionEnabled_()

◆ passedThreadFilter_()

◆ redirect_()

◆ revert_()

◆ setInfoLevel_()

◆ setThreadFilter_()

◆ traceLocation_()

◆ traceUserMsg_()

Member Data Documentation

◆ m_filename

◆ m_funcname

◆ m_linenum

◆ m_scope

◆ m_section