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

◆ _TF_DEBUG_FIRST_CODE

#define _TF_DEBUG_FIRST_CODE	(	first,
		...
	)	first

Definition at line 442 of file debug.h.

◆ _TF_DEBUG_MAKE_STRING

#define _TF_DEBUG_MAKE_STRING ( x ) #x,

Definition at line 434 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:

TF_CONDITIONALLY_COMPILE_TIME_ENABLED_DEBUG_CODES(
  <Enabled State: a compile-time value convertible to bool>
  MY_E1,
  MY_E2
);

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 414 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);

TF_DEBUG

#define TF_DEBUG(enumVal)

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

Definition: debug.h:501

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 501 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:

TF_DEBUG_CODES(
  MY_E1,
  MY_E2
);

Definition at line 393 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_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 565 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, ...);

TF_DEBUG_MSG

#define TF_DEBUG_MSG(enumVal,...)

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

Definition: debug.h:466

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

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 540 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 511 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 138 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 123 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 152 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 109 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 95 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 75 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 348 of file debug.h.

Files

Classes

Macros

Functions

Variables