|
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. | |
See Guide To Diagnostic Facilities for a discussion of diagnostic techniques.
#define TF_AXIOM | ( | cond | ) |
Aborts if the condition cond
is not met.
cond | is 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.
#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.
#define TF_DEV_AXIOM | ( | cond | ) |
The same as TF_AXIOM, but compiled only in dev builds.
cond | is 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.
#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.
#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.
#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,
Should display something like: "Debugging info about function YourClass::SomeMethod."
Definition at line 292 of file diagnostic.h.
#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.
#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:
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.
A piece of arbitrary data can also be passed in along with the diagnostic code and status message as follows:
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.
#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.
cond | is any expression convertible to bool. |
Usage generally follows patterns like these:
Here are some examples:
The macro also optionally accepts printf-style arguments to generate a message emitted in case the condition is not met. For example:
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.
#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:
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.
A piece of arbitrary data can also be passed in along with the diagnostic code and warning message as follows:
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.
std::string TfGetProgramNameForErrors | ( | ) |
Returns currently set program info.
This function simply calls to ArchGetProgramNameForErrors().
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.
void TfSetProgramNameForErrors | ( | std::string const & | programName | ) |
Sets program name for reporting errors.
This function simply calls to ArchSetProgramNameForErrors().