TfDebug Class Reference

#include <debug.h>

Classes
struct	_Node
struct	_Traits
struct	Helper
struct	ScopeHelper
struct	TimedScopeHelper
struct	TimedScopeHelper< false >

Static Public Member Functions
template<class T >
static void	Enable (T val)
template<class T >
static void	Disable (T val)
	Mark debugging as disabled for enum value val. More...
template<class T >
static void	EnableAll ()
template<class T >
static void	DisableAll ()
	Mark debugging as disabled for all enum values of type T. More...
template<class T >
static bool	IsEnabled (T val)
template<class T >
static bool	IsCompileTimeEnabled ()
template<class T >
static size_t	GetNumDebugCodes ()
static TF_API std::vector < std::string >	SetDebugSymbolsByName (const std::string &pattern, bool value)
static TF_API bool	IsDebugSymbolNameEnabled (const std::string &name)
	True if the specified debug symbol is set. More...
static TF_API std::string	GetDebugSymbolDescriptions ()
static TF_API std::vector < std::string >	GetDebugSymbolNames ()
	Get a listing of all debug symbols. More...
static TF_API std::string	GetDebugSymbolDescription (const std::string &name)
static TF_API void	SetOutputFile (FILE *file)
template<class T >
static void	_RegisterDebugSymbol (T enumVal, char const *name, char const *descrip)
static TF_API void	_RegisterDebugSymbolImpl (_Node *addr, char const *enumName, char const *descrip)

Friends
class	Tf_DebugSymbolRegistry

Detailed Description

Enum-based debugging messages.

The TfDebug class encapsulates a simple enum-based conditional debugging message system. It is meant as a tool for developers, and NOT as a means of issuing diagnostic messages to end-users. (This is not strictly true. The TfDebug class is extremely useful and has many properties that make its use attractive for issuing messages to end-users. However, for this purpose, please use the TF_INFO macro which more clearly indicates its intent.)

The features of TfDebug are:

• Debugging messages/calls for an entire enum group can be compiled out-of-existence.
• The cost of checking if a specific message should be printed at runtime (assuming the enum group of the message has not been compile-time disabled) is a single inline array lookup, with a compile-time index into a global array.

The use of the facility is simple:

// header file
#include "pxr/base/tf/debug.h"
TF_DEBUG_CODES(MY_E1, MY_E2, MY_E3);

// source file
TF_DEBUG(MY_E2).Msg("something about e2\n");

TF_DEBUG(MY_E3).Msg("val = %d\n", value);

The code in the header file declares the debug symbols to use. Under the hood, this creates an enum with the values given in the argument to TF_DEBUG_CODES, along with a first and last sentinel values and passes that to TF_DEBUG_RANGE.

If you need to obtain the enum type name, use decltype(SOME_ENUM_VALUE).

In the source file, the indicated debugging messages are printed only if the debugging symbols are enabled. Effectively, the construct

TF_DEBUG(MY_E1).Msg(msgExpr)

is translated to

if (symbol-MY_E1-is-enabled)
    output(msgExpr)

The implications are that msgExpr is only evaluated if symbol MY_E1 symbol is enabled.

To totally disable TF_DEBUG output for a set of codes at compile time, declare the codes using TF_CONDITIONALLY_COMPILE_TIME_ENABLED_DEBUG_CODES(condition, ...) where ... is all the debug codes. If 'condition' is false at compile time then all TF_DEBUG().Msg()s for these codes are elminated at compile time, so they have zero cost.

Most commonly debug symbols are inactive by default, but can be turned on either by an environment variable TF_DEBUG, or interactively once a program has started.

TfDebug::DisableAll<MyDebugCodes>();     // disable everything

TfDebug::Enable(MY_E1);                  // enable just MY_E1

Description strings may be associated with debug codes as follows:

// source file xyz/debugCodes.cpp

#include "proj/my/debugCodes.h"
#include "pxr/base/tf/debug.h"
#include "pxr/base/tf/registryManager.h"

TF_REGISTRY_FUNCTION(TfDebug) {
    TF_DEBUG_ENVIRONMENT_SYMBOL(MY_E1, "loading of blah-blah files");
    TF_DEBUG_ENVIRONMENT_SYMBOL(MY_E2, "parsing of mdl code");
    // etc.
}

Definition at line 139 of file debug.h.

Member Function Documentation

template<class T >

static void TfDebug::_RegisterDebugSymbol ( T  enumVal, char const *  name, char const *  descrip  )

inlinestatic

Definition at line 312 of file debug.h.

static TF_API void TfDebug::_RegisterDebugSymbolImpl ( _Node *  addr, char const *  enumName, char const *  descrip  )

static

template<class T >

static void TfDebug::Disable ( T  val )

inlinestatic

Mark debugging as disabled for enum value val.

Definition at line 157 of file debug.h.

template<class T >

static void TfDebug::DisableAll ( )

inlinestatic

Mark debugging as disabled for all enum values of type T.

Definition at line 178 of file debug.h.

template<class T >

static void TfDebug::Enable ( T  val )

inlinestatic

Mark debugging as enabled for enum value val.

The default state for all debugging symbols is disabled. Note that the template parameter is deduced from val:

TfDebug::Enable(MY_E3);

Definition at line 151 of file debug.h.

template<class T >

static void TfDebug::EnableAll ( )

inlinestatic

Mark debugging as enabled for all enum values of type T.

Note that the template parameter must be explicitly supplied:

TfDebug::EnableAll<MyDebugCodes>()

Definition at line 168 of file debug.h.

static TF_API std::string TfDebug::GetDebugSymbolDescription ( const std::string &  name )

static

Get a description for the specified debug symbol.

A short description of the debug symbol is returned. This is the same description string that is embedded in the return value of GetDebugSymbolDescriptions.

static TF_API std::string TfDebug::GetDebugSymbolDescriptions ( )

static

Get a description of all debug symbols and their purpose.

A single string describing all registered debug symbols along with short descriptions is returned.

static TF_API std::vector<std::string> TfDebug::GetDebugSymbolNames ( )

static

Get a listing of all debug symbols.

template<class T >

static size_t TfDebug::GetNumDebugCodes ( )

inlinestatic

Return the number of debugging symbols of this type.

Returns the number of different enums in the range.

Definition at line 221 of file debug.h.

template<class T >

static bool TfDebug::IsCompileTimeEnabled ( )

inlinestatic

True if debugging can be activated at run-time, whether or not it is currently enabled.

Definition at line 211 of file debug.h.

static TF_API bool TfDebug::IsDebugSymbolNameEnabled ( const std::string &  name )

static

True if the specified debug symbol is set.

template<class T >

static bool TfDebug::IsEnabled ( T  val )

inlinestatic

True if debugging is enabled for the enum value val.

Note that not only must the specific enum value val be marked as enabled, but the enum type T must be globally enabled; this is controlled by the first argument to the TF_CONDITIONALLY_COMPILE_TIME_ENABLED_DEBUG_CODES() macro.

Definition at line 193 of file debug.h.

static TF_API std::vector<std::string> TfDebug::SetDebugSymbolsByName ( const std::string &  pattern, bool  value  )

static

Set registered debug symbols matching pattern to value.

All registered debug symbols matching pattern are set to value. The only matching is an exact match with pattern, or if pattern ends with an '*' as is otherwise a prefix of a debug symbols. The names of all debug symbols set by this call are returned as a vector.

static TF_API void TfDebug::SetOutputFile ( FILE *  file )

static

Direct debug output to either stdout or stderr.

Note that file MUST be either stdout or stderr. If not, issue an error and do nothing. Debug output is issued to stdout by default. If the environment variable TF_DEBUG_OUTPUT_FILE is set to 'stderr', then output is issued to stderr by default.

Friends And Related Function Documentation

friend class Tf_DebugSymbolRegistry

friend

Definition at line 356 of file debug.h.

---

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

• pxr/base/tf/debug.h