All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
TfDebug Class Reference

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 GetDebugRangeCount ()
 Return the number of debugging symbols of this type. More...
 
template<class T >
static T GetDebugSymbol (size_t index)
 Return the index-th debug symbol 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 _Node * _GetSymbolAddr (T val, const char *name)
 
static TF_API void _RegisterDebugSymbol (TfEnum val, _Node *addr, const char *descrip)
 
static TF_API bool _CheckEnvironmentForMatch (const std::string &enumName)
 

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'd like to be more explicit (e.g., because you need the enum type name, or need to be able to turn off the facility at compile time), you could use the following, equivalent, form:

* // header file
* #include "pxr/base/tf/debug.h"
* enum MyDebugCodes { MY_FIRST, MY_E1, MY_E2, MY_E3, MY_LAST };
* TF_DEBUG_RANGE(MyDebugCodes, MY_FIRST, MY_LAST, true);
*
* // source file
* TF_DEBUG(MY_E2).Msg("something about e2\n");
*
* TF_DEBUG(MY_E3).Msg("val = %d\n", 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. Further, if the last argument (which must be a compile-time constant) to the TF_DEBUG_RANGE() macro is false, then the test is known to fail at compile time; in this case, the compiler will even eliminate outputting the code to execute msgExpr. This scheme allows the costs of debugging code to be controlled at a fine level of detail.

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 by a script interpreter. Both of these are accomplished 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, MyDebugCodes) {
* TF_DEBUG_ENVIRONMENT_SYMBOL(MY_E1, "loading of blah-blah files");
* TF_DEBUG_ENVIRONMENT_SYMBOL(MY_E2, "parsing of mdl code");
* // etc.
* }
*

Once this is done, symbols are enabled as follows:

* TfDebug::DisableAll<MyDebugCodes>(); // disable everything
*
* TfDebug::Enable(MY_E1); // enable just MY_E1
*

Definition at line 148 of file debug.h.

Member Function Documentation

static void Disable ( val)
inlinestatic

Mark debugging as disabled for enum value val.

Definition at line 164 of file debug.h.

static void DisableAll ( )
inlinestatic

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

Definition at line 181 of file debug.h.

static void Enable ( 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 158 of file debug.h.

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 175 of file debug.h.

static size_t GetDebugRangeCount ( )
inlinestatic

Return the number of debugging symbols of this type.

Returns the number of different enums in the range specified by TF_DEBUG_RANGE().

Definition at line 208 of file debug.h.

static T GetDebugSymbol ( size_t  index)
inlinestatic

Return the index-th debug symbol of this type.

If index-th is out of range (i.e. greater than or equal to GetDebugRangeCount()) the last symbol is returned.

The above two functions can be used to print out the names of all debug symbols, if they have been registered via TF_ADD_ENUM_NAME():

* for (size_t i = 0; i < TfDebug::GetDebugRangeCount<Codes>(); i++)
* cout << TfEnum::GetName(TfDebug::GetDebugSymbol<T>(i)) << "\n";
*

Definition at line 224 of file debug.h.

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.

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.

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

Get a listing of all debug symbols.

static bool IsCompileTimeEnabled ( )
inlinestatic

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

Definition at line 199 of file debug.h.

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

True if the specified debug symbol is set.

static bool IsEnabled ( 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 last argument to the TF_DEBUG_RANGE() must have been true.

Definition at line 192 of file debug.h.

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.

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: