This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
Output for Debugging Purposes

Functions/classes that generate output solely as a debugging aid. More...

Files

file  debug.h
 Conditional debugging output class and macros.
 
file  ostreamMethods.h
 Handy ostream output for various lib/tf and STL containers.
 

Classes

class  TfDebug
 Enum-based debugging messages. More...
 

Macros

#define TF_DEBUG_CODES(...)
 Define debugging symbols.
 
#define TF_CONDITIONALLY_COMPILE_TIME_ENABLED_DEBUG_CODES(condition, ...)
 Define debugging symbols.
 
#define _TF_DEBUG_MAKE_STRING(x)   #x,
 
#define _TF_DEBUG_ENUM_NAME(...)    TF_PP_CAT(_TF_DEBUG_FIRST_CODE(__VA_ARGS__, dummy), __DebugCodes)
 
#define _TF_DEBUG_FIRST_CODE(first, ...)   first
 
#define TF_DEBUG_MSG(enumVal, ...)
 Evaluate and print debugging message msg if enumVal is enabled for debugging.
 
#define TF_DEBUG(enumVal)
 Evaluate and print debugging message msg if enumVal is enabled for debugging.
 
#define TF_INFO(x)
 Evaluate and print diagnostic messages intended for end-users.
 
#define TF_DEBUG_TIMED_SCOPE(enumVal, ...)
 Print description and time spent in scope upon beginning and exiting it if enumVal is enabled for debugging.
 
#define TF_DEBUG_ENVIRONMENT_SYMBOL(VAL, descrip)
 Register description strings with enum symbols for debugging.
 

Functions

TF_API std::ostream & operator<< (std::ostream &out, const TfEnum &e)
 Output a TfEnum value.
 
template<class T , uint32_t N>
std::enable_if< 1::Tf_IsOstreamable< T >(), std::ostream & >::type operator<< (std::ostream &out, const TfSmallVector< T, N > &v)
 Output a TfSmallVector using [ ] as delimiters.
 
template<class T >
std::enable_if< 1::Tf_IsOstreamable< T >(), std::ostream & >::type operator<< (std::ostream &out, const std::vector< T > &v)
 Output an STL vector using [ ] as delimiters.
 
template<class T >
std::enable_if< 1::Tf_IsOstreamable< T >(), std::ostream & >::type operator<< (std::ostream &out, const std::set< T > &v)
 Output an STL set using ( ) as delimiters.
 
template<class T >
std::enable_if< 1::Tf_IsOstreamable< T >(), std::ostream & >::type operator<< (std::ostream &out, const std::list< T > &l)
 Output an STL list using { } as delimiters.
 
template<class K , class M , class H , class C , class A >
std::enable_if< 1::Tf_IsOstreamable< K >()&&1::Tf_IsOstreamable< M >(), std::ostream & >::type operator<< (std::ostream &out, const 1::TfHashMap< K, M, H, C, A > &h)
 Output an TfHashMap using < > as delimiters.
 
template<class K , class M >
std::enable_if< 1::Tf_IsOstreamable< K >()&&1::Tf_IsOstreamable< M >(), std::ostream & >::type operator<< (std::ostream &out, const std::map< K, M > &h)
 Output an STL map using < > as delimiters.
 
TF_API std::ostream & operator<< (std::ostream &out, const TfStopwatch &s)
 Output a TfStopwatch, using the format seconds.
 
TF_API std::ostream & operator<< (std::ostream &out, const TfType &t)
 Output a TfType, using the machine-independent type name.
 

Variables

static _Node nodes [_Traits< T >::NumCodes]
 

Detailed Description

Functions/classes that generate output solely as a debugging aid.

Macro Definition Documentation

◆ _TF_DEBUG_ENUM_NAME

#define _TF_DEBUG_ENUM_NAME (   ...)     TF_PP_CAT(_TF_DEBUG_FIRST_CODE(__VA_ARGS__, dummy), __DebugCodes)

Definition at line 422 of file debug.h.

◆ _TF_DEBUG_FIRST_CODE

#define _TF_DEBUG_FIRST_CODE (   first,
  ... 
)    first

Definition at line 425 of file debug.h.

◆ _TF_DEBUG_MAKE_STRING

#define _TF_DEBUG_MAKE_STRING (   x)    #x,

Definition at line 417 of file debug.h.

◆ TF_CONDITIONALLY_COMPILE_TIME_ENABLED_DEBUG_CODES

#define TF_CONDITIONALLY_COMPILE_TIME_ENABLED_DEBUG_CODES (   condition,
  ... 
)

Define debugging symbols.

This is a simple macro that takes care of declaring debug codes, subject to a compile-time condition that enables or disables them completely. Use it as follows:

<Enabled State: a compile-time value convertible to bool>
MY_E1,
MY_E2
);
#define TF_CONDITIONALLY_COMPILE_TIME_ENABLED_DEBUG_CODES(condition,...)
Define debugging symbols.
Definition: debug.h:397

If the Enabled State is true, this is equivalent to the TF_DEBUG_CODES() macro. If it is false, then these debug codes are disabled at compile time and generated code pays no cost for them.

Definition at line 397 of file debug.h.

◆ TF_DEBUG

#define TF_DEBUG (   enumVal)

Evaluate and print debugging message msg if enumVal is enabled for debugging.

The TF_DEBUG() macro is used as follows:

TF_DEBUG(enumVal).Msg("opening file %s, count = %d\n",
file.c_str(), count);
#define TF_DEBUG(enumVal)
Evaluate and print debugging message msg if enumVal is enabled for debugging.
Definition: debug.h:484

If enumVal is of enumerated type enumType, and enumType has been enabled for debugging (see TF_DEBUG_CODES()), and the specific value enumVal has been enabled for debugging by a call to TfDebug::Enable(), then the arguments in the Msg() call are evaluated and printed. The argument to Msg() may either be a const char* and a variable number of arguments, using standard printf-formatting rules, or a std::string variable:

TF_DEBUG(enumVal).Msg("opening file " + file + "\n");

Note that the arguments to Msg() are unevaluated when the value enumVal is not enabled for debugging, so Msg() must be free of side-effects; however, when enumVal is not enabled, there is no expense incurred in computing the arguments to Msg(). Note that if the entire enum type corresponding to enumVal is disabled (a compile-time determination) then the code for the entire TF_DEBUG().Msg() statement will typically not even be generated!

See also
TF_DEBUG_MSG()

Definition at line 484 of file debug.h.

◆ TF_DEBUG_CODES

#define TF_DEBUG_CODES (   ...)

Define debugging symbols.

This is a simple macro that takes care of declaring debug codes. Use it as follows:

MY_E1,
MY_E2
);
#define TF_DEBUG_CODES(...)
Define debugging symbols.
Definition: debug.h:376

Definition at line 376 of file debug.h.

◆ TF_DEBUG_ENVIRONMENT_SYMBOL

#define TF_DEBUG_ENVIRONMENT_SYMBOL (   VAL,
  descrip 
)

Register description strings with enum symbols for debugging.

This call should be used in source files, not header files, and should This macro should usually appear within a TF_REGISTRY_FUNCTION(TfDebug,...) call. The first argument should be the literal name of the enum symbol, while the second argument should be a (short) description of what debugging will be enabled if the symbol is activated. The enum being registered must be one which is contained in some TF_DEBUG_CODES() call. For example:

TF_DEBUG_ENVIRONMENT_SYMBOL(MY_E1, "loading of blah-blah files");
TF_DEBUG_ENVIRONMENT_SYMBOL(MY_E2, "parsing of mdl code");
// etc.
}
Enum-based debugging messages.
Definition: debug.h:122
#define TF_DEBUG_ENVIRONMENT_SYMBOL(VAL, descrip)
Register description strings with enum symbols for debugging.
Definition: debug.h:548
#define TF_REGISTRY_FUNCTION(KEY_TYPE)
Define a function that is called on demand by TfRegistryManager.

Definition at line 548 of file debug.h.

◆ TF_DEBUG_MSG

#define TF_DEBUG_MSG (   enumVal,
  ... 
)

Evaluate and print debugging message msg if enumVal is enabled for debugging.

This macro is a newer, more convenient form of the TF_DEBUG() macro. Writing

TF_DEBUG_MSG(enumVal, msg, ...);
#define TF_DEBUG_MSG(enumVal,...)
Evaluate and print debugging message msg if enumVal is enabled for debugging.
Definition: debug.h:449

is equivalent to

TF_DEBUG(enumVal).Msg(msg, ...);

The TF_DEBUG_MSG() macro allows either an std::string argument or a printf-like format string followed by a variable number of arguments:

TF_DEBUG_MSG(enumVal, "opening file %s\n", file.c_str());
TF_DEBUG_MSG(enumVal, "opening file " + file);

Definition at line 449 of file debug.h.

◆ TF_DEBUG_TIMED_SCOPE

#define TF_DEBUG_TIMED_SCOPE (   enumVal,
  ... 
)

Print description and time spent in scope upon beginning and exiting it if enumVal is enabled for debugging.

The TF_DEBUG_TIMED_SCOPE() macro is used as follows:

void Attribute::Compute()
{
TF_DEBUG_TIMED_SCOPE(ATTR_COMPUTE, "Computing %s", name.c_str());
...
}
#define TF_DEBUG_TIMED_SCOPE(enumVal,...)
Print description and time spent in scope upon beginning and exiting it if enumVal is enabled for deb...
Definition: debug.h:523

When the TF_DEBUG_TIMED_SCOPE macro is invoked, a timer is started and the supplied description is printed. When the enclosing scope is exited (in the example, when Attribute::Compute() finishes) the timer is stopped and the scope description and measured time are printed. This allows for very fine-grained timing of operations.

Note that if the entire enum type corresponding to enumVal is disabled (a compile-time determination) then the presence of a TF_DEBUG_TIMED_SCOPE() macro should not produce any extra generated code (in an optimized build). If the enum type is enabled, but the particular value enumVal is disabled, the cost of the macro should be quite minimal; still, it would be best not to embed the macro in functions that are called in very tight loops, in final released code.

Definition at line 523 of file debug.h.

◆ TF_INFO

#define TF_INFO (   x)

Evaluate and print diagnostic messages intended for end-users.

The TF_INFO(x) macro is cosmetic; it actually just calls the TF_DEBUG macro (see above). This macro should be used if its output is intended to be seen by end-users.

Definition at line 494 of file debug.h.

Function Documentation

◆ operator<<() [1/9]

std::enable_if< 1::Tf_IsOstreamable< K >()&&1::Tf_IsOstreamable< M >(), std::ostream & >::type operator<< ( std::ostream &  out,
const 1::TfHashMap< K, M, H, C, A > &  h 
)

Output an TfHashMap using < > as delimiters.

Definition at line 121 of file ostreamMethods.h.

◆ operator<<() [2/9]

std::enable_if< 1::Tf_IsOstreamable< T >(), std::ostream & >::type operator<< ( std::ostream &  out,
const std::list< T > &  l 
)

Output an STL list using { } as delimiters.

Definition at line 106 of file ostreamMethods.h.

◆ operator<<() [3/9]

std::enable_if< 1::Tf_IsOstreamable< K >()&&1::Tf_IsOstreamable< M >(), std::ostream & >::type operator<< ( std::ostream &  out,
const std::map< K, M > &  h 
)

Output an STL map using < > as delimiters.

Definition at line 135 of file ostreamMethods.h.

◆ operator<<() [4/9]

std::enable_if< 1::Tf_IsOstreamable< T >(), std::ostream & >::type operator<< ( std::ostream &  out,
const std::set< T > &  v 
)

Output an STL set using ( ) as delimiters.

Definition at line 92 of file ostreamMethods.h.

◆ operator<<() [5/9]

std::enable_if< 1::Tf_IsOstreamable< T >(), std::ostream & >::type operator<< ( std::ostream &  out,
const std::vector< T > &  v 
)

Output an STL vector using [ ] as delimiters.

Definition at line 78 of file ostreamMethods.h.

◆ operator<<() [6/9]

TF_API std::ostream & operator<< ( std::ostream &  out,
const TfEnum e 
)

Output a TfEnum value.

◆ operator<<() [7/9]

std::enable_if< 1::Tf_IsOstreamable< T >(), std::ostream & >::type operator<< ( std::ostream &  out,
const TfSmallVector< T, N > &  v 
)

Output a TfSmallVector using [ ] as delimiters.

Definition at line 58 of file ostreamMethods.h.

◆ operator<<() [8/9]

TF_API std::ostream & operator<< ( std::ostream &  out,
const TfStopwatch s 
)

Output a TfStopwatch, using the format seconds.

The elapsed time in the stopwatch is output in seconds. Note that the timer need not be stopped.

◆ operator<<() [9/9]

TF_API std::ostream & operator<< ( std::ostream &  out,
const TfType t 
)

Output a TfType, using the machine-independent type name.

Variable Documentation

◆ nodes

TfDebug::_Node nodes
static

Definition at line 331 of file debug.h.