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
Diagnostic Facilities

See Guide To Diagnostic Facilities for a discussion of diagnostic techniques. More...

Files

file  diagnostic.h
 Low-level utilities for informing users of various internal and external diagnostic conditions.
 
file  exception.h
 

Classes

class  TfDiagnosticMgr
 Singleton class through which all errors and diagnostics pass. More...
 
class  TfError
 Represents an object that contains error information. More...
 
class  TfStatus
 Represents an object that contains information about a status message. More...
 
class  TfWarning
 Represents an object that contains information about a warning. More...
 

Macros

#define TF_ERROR(...)
 Issue an internal programming error, but continue execution.
 
#define TF_CODING_ERROR(fmt, args)
 Issue an internal programming error, but continue execution.
 
#define TF_RUNTIME_ERROR(fmt, args)
 Issue a generic runtime error, but continue execution.
 
#define TF_FATAL_ERROR(fmt, args)
 Issue a fatal error and end the program.
 
#define TF_WARN(...)
 Issue a warning, but continue execution.
 
#define TF_STATUS(...)
 Issue a status message, but continue execution.
 
#define TF_AXIOM(cond)
 Aborts if the condition cond is not met.
 
#define TF_DEV_AXIOM(cond)
 The same as TF_AXIOM, but compiled only in dev builds.
 
#define TF_VERIFY(cond, format, ...)
 Checks a condition and reports an error if it evaluates false.
 
#define TF_FUNC_NAME()
 Get the name of the current function as a std::string.
 

Functions

void TfSetProgramNameForErrors (std::string const &programName)
 Sets program name for reporting errors.
 
std::string TfGetProgramNameForErrors ()
 Returns currently set program info.
 
TF_API void TfInstallTerminateAndCrashHandlers ()
 (Re)install Tf's crash handler.
 

Detailed Description

See Guide To Diagnostic Facilities for a discussion of diagnostic techniques.

Macro Definition Documentation

◆ TF_AXIOM

#define TF_AXIOM (   cond)

Aborts if the condition cond is not met.

Parameters
condis any expression convertible to bool; if the condition evaluates to false, program execution ends with this call.

Note that the diagnostic message sent is the code cond, in the form of a string. Unless the condition expression is self-explanatory, use TF_FATAL_ERROR(). See Fatal Errors for further discussion.

Currently, a TF_AXIOM() statement is not made a no-op in optimized builds; however, it always possible that either (a) the axiom statement might be removed at some point if the code is deemed correct or (b) in the future, some flavor of build might choose to make axioms be no-ops. Thus, programmers must make certain that the code in cond is entirely free of side effects.

Definition at line 193 of file diagnostic.h.

◆ TF_CODING_ERROR

#define TF_CODING_ERROR (   fmt,
  args 
)

Issue an internal programming error, but continue execution.

This macro is a convenience. It produces a TF_ERROR() with an error code indicating a coding error. It takes a printf-like format specification or a std::string. Generally, an error handling delegate will take action to turn this error into a python exception, and if it remains unhandled at the end of an application iteration will roll-back the undo stack to a last-known-good state.

This is safe to call in secondary threads.

Definition at line 68 of file diagnostic.h.

◆ TF_DEV_AXIOM

#define TF_DEV_AXIOM (   cond)

The same as TF_AXIOM, but compiled only in dev builds.

Parameters
condis any expression convertible to bool; if the condition evaluates to false, program execution ends with this call.

This macro has the same behavior as TF_AXIOM, but it is compiled only in dev builds. This version should only be used in code that is known (not just suspected!) to be performance critical.

Definition at line 205 of file diagnostic.h.

◆ TF_ERROR

#define TF_ERROR (   ...)

Issue an internal programming error, but continue execution.

Please see The TfError Error Posting System for more information about how to use TF_ERROR().

This is safe to call in secondary threads.

Definition at line 54 of file diagnostic.h.

◆ TF_FATAL_ERROR

#define TF_FATAL_ERROR (   fmt,
  args 
)

Issue a fatal error and end the program.

This macro takes a printf-like format specification or a std::string. The program will generally terminate upon a fatal error.

Definition at line 91 of file diagnostic.h.

◆ TF_FUNC_NAME

#define TF_FUNC_NAME ( )

Get the name of the current function as a std::string.

This macro will return the name of the current function, nicely formatted, as an std::string. This is meant primarily for diagnostics. Code should not rely on a specific format, because it may change in the future or vary across architectures. For example,

void YourClass::SomeMethod(int x) {
cout << "Debugging info about function " << TF_FUNC_NAME() << "." << endl;
...
}
#define TF_FUNC_NAME()
Get the name of the current function as a std::string.
Definition: diagnostic.h:292

Should display something like: "Debugging info about function YourClass::SomeMethod."

Definition at line 292 of file diagnostic.h.

◆ TF_RUNTIME_ERROR

#define TF_RUNTIME_ERROR (   fmt,
  args 
)

Issue a generic runtime error, but continue execution.

This macro is a convenience. It produces a TF_ERROR() with an error code indicating a generic runtime error. It is preferred over TF_ERROR(0), but using a specific error code is preferred over this. It takes a printf-like format specification or a std::string. Generally, an error handling delegate will take action to turn this error into a python exception, and if it remains unhandled at the end of an application iteration will roll-back the undo stack to a last-known-good state.

This is safe to call in secondary threads.

Definition at line 83 of file diagnostic.h.

◆ TF_STATUS

#define TF_STATUS (   ...)

Issue a status message, but continue execution.

This macro works with a variety of argument sets. It supports simple printf-like format specification or a std::string. It also supports specification of a diagnostic code and a piece of arbitrary information in the form of a TfDiagnosticInfo. The following is a full list of supported argument lists:

TF_STATUS(const char *) // plain old string
TF_STATUS(const char *, ...) // printf like formatting
TF_STATUS(std::string) // stl string
#define TF_STATUS(...)
Issue a status message, but continue execution.
Definition: diagnostic.h:173
STL namespace.

A diagnostic code can be passed in along with the status message. See Enum Conventions for an example of registering an enum type and it's values as diagnostic codes.

TF_STATUS(DIAGNOSTIC_ENUM, const char *)
TF_STATUS(DIAGNOSTIC_ENUM, const char *, ...)
TF_STATUS(DIAGNOSTIC_ENUM, std::string)

A piece of arbitrary data can also be passed in along with the diagnostic code and status message as follows:

TF_STATUS(info, DIAGNOSTIC_ENUM, const char *)
TF_STATUS(info, DIAGNOSTIC_ENUM, const char *, ...)
TF_STATUS(info, DIAGNOSTIC_ENUM, std::string)

Generally, no adjustment to program state should occur as the result of this macro. This is in contrast with errors as mentioned above.

This is safe to call in secondary threads.

Definition at line 173 of file diagnostic.h.

◆ TF_VERIFY

#define TF_VERIFY (   cond,
  format,
  ... 
)

Checks a condition and reports an error if it evaluates false.

This can be thought of as something like a softer, recoverable TF_AXIOM.

The macro expands to an expression whose value is either true or false depending on cond. If cond evaluates to false, issues a coding error indicating the failure.

Parameters
condis any expression convertible to bool.

Usage generally follows patterns like these:

// Simple check. This is like a non-fatal TF_AXIOM.
TF_VERIFY(condition);
// Avoiding code that requires the condition be met.
if (TF_VERIFY(condition)) {
// code requiring condition be met.
}
// Executing recovery code in case the condition is not met.
if (not TF_VERIFY(condition)) {
// recovery code to execute since condition was not met.
}
#define TF_VERIFY(cond, format,...)
Checks a condition and reports an error if it evaluates false.
Definition: diagnostic.h:266

Here are some examples:

// List should be empty. If not, issue an error, clear it out and continue.
if (not TF_VERIFY(list.empty()) {
// The list was unexpectedly not empty. TF_VERIFY will have
// issued a coding error with details. We clear the list and continue.
list.clear();
}
// Only add to string if ptr is valid.
string result = ...;
if (TF_VERIFY(ptr != NULL)) {
result += ptr->Method();
}

The macro also optionally accepts printf-style arguments to generate a message emitted in case the condition is not met. For example:

if (not TF_VERIFY(index < size,
"Index out of bounds (%zu >= %zu)", index, size)) {
// Recovery code...
}

Unmet conditions generate TF_CODING_ERRORs by default, but setting the environment variable TF_FATAL_VERIFY to 1 will make unmet conditions generate TF_FATAL_ERRORs instead and abort the program. This is intended for testing.

This is safe to call in secondary threads.

Definition at line 266 of file diagnostic.h.

◆ TF_WARN

#define TF_WARN (   ...)

Issue a warning, but continue execution.

This macro works with a variety of argument sets. It supports simple printf-like format specification or a std::string. It also supports specification of a diagnostic code and a piece of arbitrary information in the form of a TfDiagnosticInfo. The following is a full list of supported argument lists:

TF_WARN(const char *) // plain old string
TF_WARN(const char *, ...) // printf like formatting
TF_WARN(std::string) // stl string
#define TF_WARN(...)
Issue a warning, but continue execution.
Definition: diagnostic.h:132

A diagnostic code can be passed in along with the warning message. See Enum Conventions for an example of registering an enum type and it's values as diagnostic codes.

TF_WARN(DIAGNOSTIC_ENUM, const char *)
TF_WARN(DIAGNOSTIC_ENUM, const char *, ...)
TF_WARN(DIAGNOSTIC_ENUM, std::string)

A piece of arbitrary data can also be passed in along with the diagnostic code and warning message as follows:

TF_WARN(info, DIAGNOSTIC_ENUM, const char *)
TF_WARN(info, DIAGNOSTIC_ENUM, const char *, ...)
TF_WARN(info, DIAGNOSTIC_ENUM, std::string)

Generally, no adjustment to program state should occur as the result of this macro. This is in contrast with errors as mentioned above.

This is safe to call in secondary threads.

Definition at line 132 of file diagnostic.h.

Function Documentation

◆ TfGetProgramNameForErrors()

std::string TfGetProgramNameForErrors ( )

Returns currently set program info.

This function simply calls to ArchGetProgramNameForErrors().

◆ TfInstallTerminateAndCrashHandlers()

TF_API void TfInstallTerminateAndCrashHandlers ( )

(Re)install Tf's crash handler.

This should not generally need to be called since Tf does this itself when loaded. However, when run in 3rd party environments that install their own signal handlers, possibly overriding Tf's, this provides a way to reinstall them, in hopes that they'll stick.

This calls std::set_terminate() and installs signal handlers for SIGSEGV, SIGBUS, SIGFPE, and SIGABRT.

◆ TfSetProgramNameForErrors()

void TfSetProgramNameForErrors ( std::string const &  programName)

Sets program name for reporting errors.

This function simply calls to ArchSetProgramNameForErrors().