All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups 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. More...
 
#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_RANGE(enumType, first, last, enabled)
 Define the range for an enum class for debugging symbols. More...
 
#define TF_DEBUG_MSG(enumVal,...)
 Evaluate and print debugging message msg if enumVal is enabled for debugging. More...
 
#define TF_DEBUG(enumVal)
 Evaluate and print debugging message msg if enumVal is enabled for debugging. More...
 
#define TF_INFO(x)
 Evaluate and print diagnostic messages intended for end-users. More...
 
#define TF_DEBUG_TIMED_SCOPE(enumVal,...)
 Print description and time spent in scope upon beginning and exiting it if enumVal is enabled for debugging. More...
 
#define TF_DEBUG_ENVIRONMENT_SYMBOL(VAL, descrip)
 Register an enum symbol for debugging. More...
 

Functions

TF_API std::ostream & operator<< (std::ostream &out, const TfEnum &e)
 Output a TfEnum value. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
TF_API std::ostream & operator<< (std::ostream &out, const TfStopwatch &s)
 Output a TfStopwatch, using the format seconds. More...
 
TF_API std::ostream & operator<< (std::ostream &out, const TfType &t)
 Output a TfType, using the machine-independent type name. More...
 

Variables

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

Detailed Description

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

Macro Definition Documentation

#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);
*

If enumVal is of enumerated type enumType, and enumType has been enabled for debugging (see TF_DEBUG_RANGE()), 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 497 of file debug.h.

#define TF_DEBUG_CODES (   ...)

Define debugging symbols.

This is a simple macro that takes care of declaring your enum, providing a first and last symbol and declaring the range. Use it as follows:

* MY_E1,
* MY_E2
* );
*

Definition at line 397 of file debug.h.

#define TF_DEBUG_ENVIRONMENT_SYMBOL (   VAL,
  descrip 
)

Register an enum symbol 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_RANGE() call. For example:

* 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.
* }
*

Definition at line 561 of file debug.h.

#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, ...);
*

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

#define TF_DEBUG_RANGE (   enumType,
  first,
  last,
  enabled 
)

Define the range for an enum class for debugging symbols.

The parameters first and last should be constant values of enumerated type enumType; furthermore, first should be numerically less than (or equal to) last when compared as integers. The fourth parameter enabled should be a constant boolean value; if false, then all debugging symbols for enumerated type enumType are treated as disabled, regardless of any calls to TfDebug::Enable() or TfDebug::EnableAll(). Furthermore, this mode of disabling is discernible at compile time, rendering the TF_DEBUG() macro a literal no-op in terms of code-generation for this enumeration class.

Definition at line 431 of file debug.h.

#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());
* ...
* }
*

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

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

Function Documentation

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

Output an STL vector using [ ] as delimiters.

Definition at line 71 of file ostreamMethods.h.

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

Output an STL set using ( ) as delimiters.

Definition at line 85 of file ostreamMethods.h.

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

Output an STL list using { } as delimiters.

Definition at line 99 of file ostreamMethods.h.

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

Output an TfHashMap using < > as delimiters.

Definition at line 114 of file ostreamMethods.h.

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

Output an STL map using < > as delimiters.

Definition at line 128 of file ostreamMethods.h.

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.

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

Output a TfEnum value.

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

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