Static Public Member Functions | List of all members
TfDebug Class Reference
Output for Debugging Purposes

Enum-based debugging messages. More...

Static Public Member Functions

template<class T >
static void Enable (T val)
 Mark debugging as enabled for enum value val. More...
 
template<class T >
static void Disable (T val)
 Mark debugging as disabled for enum value val. More...
 
template<class T >
static void EnableAll ()
 Mark debugging as enabled for all enum values of type T. More...
 
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)
 True if debugging is enabled for the enum value val. More...
 
template<class T >
static bool IsCompileTimeEnabled ()
 True if debugging can be activated at run-time, whether or not it is currently enabled. More...
 
template<class T >
static size_t GetNumDebugCodes ()
 Return the number of debugging symbols of this type. More...
 
static TF_API std::vector< std::string > SetDebugSymbolsByName (const std::string &pattern, bool value)
 Set registered debug symbols matching pattern to value. More...
 
static TF_API bool IsDebugSymbolNameEnabled (const std::string &name)
 True if the specified debug symbol is set. More...
 
static TF_API std::string GetDebugSymbolDescriptions ()
 Get a description of all debug symbols and their purpose. More...
 
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)
 Get a description for the specified debug symbol. More...
 
static TF_API void SetOutputFile (FILE *file)
 Direct debug output to either stdout or stderr. More...
 
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)
 

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

◆ Disable()

static void Disable ( T  val)
inlinestatic

Mark debugging as disabled for enum value val.

Definition at line 157 of file debug.h.

◆ DisableAll()

static void DisableAll ( )
inlinestatic

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

Definition at line 178 of file debug.h.

◆ Enable()

static void 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.

◆ EnableAll()

static void 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.

◆ GetDebugSymbolDescription()

static TF_API std::string 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.

◆ GetDebugSymbolDescriptions()

static TF_API std::string 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.

◆ GetDebugSymbolNames()

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

Get a listing of all debug symbols.

◆ GetNumDebugCodes()

static size_t 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.

◆ IsCompileTimeEnabled()

static bool 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.

◆ IsDebugSymbolNameEnabled()

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

True if the specified debug symbol is set.

◆ IsEnabled()

static bool 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.

◆ SetDebugSymbolsByName()

static TF_API std::vector<std::string> 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.

◆ SetOutputFile()

static TF_API void 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.

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