Teuchos - Trilinos Tools Package  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Macros | Functions
Utility code for throwing exceptions and setting breakpoints.

Macros

#define TEUCHOS_ASSERT(assertion_test)   TEUCHOS_TEST_FOR_EXCEPT(!(assertion_test))
 This macro is throws when an assert fails. More...
 
#define TEUCHOS_ASSERT_IN_RANGE_UPPER_EXCLUSIVE(index, lower_inclusive, upper_exclusive)
 This macro asserts that an integral number fallis in the range [lower_inclusive,upper_exclusive) More...
 
#define TEUCHOS_ASSERT_EQUALITY(val1, val2)
 This macro is checks that to numbers are equal and if not then throws an exception with a good error message. More...
 
#define TEUCHOS_ASSERT_INEQUALITY(val1, comp, val2)
 This macro is checks that an inequality between two numbers is satisified and if not then throws a good exception message. More...
 
#define TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, Exception, msg)
 Macro for throwing an exception with breakpointing to ease debugging. More...
 
#define TEUCHOS_TEST_FOR_EXCEPTION_CLASS_FUNC(throw_exception_test, Exception, msg)
 Macro for throwing an exception from within a class method with breakpointing to ease debugging. More...
 
#define TEUCHOS_TEST_FOR_EXCEPTION_PURE_MSG(throw_exception_test, Exception, msg)
 Macro for throwing an exception with breakpointing to ease debugging. More...
 
#define TEUCHOS_TEST_FOR_EXCEPTION_PRINT(throw_exception_test, Exception, msg, out_ptr)
 This macro is the same as TEUCHOS_TEST_FOR_EXCEPTION() except that the exception will be caught, the message printed, and then rethrown. More...
 
#define TEUCHOS_TEST_FOR_EXCEPT(throw_exception_test)   TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, std::logic_error, "Error!")
 This macro is designed to be a short version of TEUCHOS_TEST_FOR_EXCEPTION() that is easier to call. More...
 
#define TEUCHOS_TEST_FOR_EXCEPT_MSG(throw_exception_test, msg)   TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, std::logic_error, msg)
 This macro is designed to be a short version of TEUCHOS_TEST_FOR_EXCEPTION() that is easier to call. More...
 
#define TEUCHOS_TEST_FOR_EXCEPT_PRINT(throw_exception_test, out_ptr)   TEUCHOS_TEST_FOR_EXCEPTION_PRINT(throw_exception_test, std::logic_error, "Error!", out_ptr)
 This macro is the same as TEUCHOS_TEST_FOR_EXCEPT() except that the exception will be caught, the message printed, and then rethrown. More...
 
#define TEUCHOS_TRACE(exc)
 This macro intercepts an exception, prints a standardized message including the current filename and line number, and then throws the exception up the stack. More...
 
#define TEUCHOS_TEST_FOR_TERMINATION(terminate_test, msg)
 This macro is to be used instead of TEUCHOS_TEST_FOR_EXCEPTION() to report an error in situations where an exception can't be throw (like in an destructor). More...
 

Functions

TEUCHOSCORE_LIB_DLL_EXPORT void Teuchos::TestForException_incrThrowNumber ()
 Increment the throw number. More...
 
TEUCHOSCORE_LIB_DLL_EXPORT int Teuchos::TestForException_getThrowNumber ()
 Increment the throw number. More...
 
TEUCHOSCORE_LIB_DLL_EXPORT void Teuchos::TestForException_break (const std::string &msg, int throwNumber)
 The only purpose for this function is to set a breakpoint. More...
 
TEUCHOSCORE_LIB_DLL_EXPORT void Teuchos::TestForException_setEnableStacktrace (bool enableStrackTrace)
 Set at runtime if stacktracing functionality is enabled when * exceptions are thrown. More...
 

Detailed Description

Macro Definition Documentation

#define TEUCHOS_ASSERT (   assertion_test)    TEUCHOS_TEST_FOR_EXCEPT(!(assertion_test))

This macro is throws when an assert fails.

Note
The std::exception thrown is std::logic_error.
Examples:
FancyOutputting_test.cpp.

Definition at line 55 of file Teuchos_Assert.hpp.

#define TEUCHOS_ASSERT_IN_RANGE_UPPER_EXCLUSIVE (   index,
  lower_inclusive,
  upper_exclusive 
)
Value:
{ \
!( (lower_inclusive) <= (index) && (index) < (upper_exclusive) ), \
std::out_of_range, \
"Error, the index " #index " = " << (index) << " does not fall in the range" \
"["<<(lower_inclusive)<<","<<(upper_exclusive)<<")!" ); \
}
#define TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, Exception, msg)
Macro for throwing an exception with breakpointing to ease debugging.

This macro asserts that an integral number fallis in the range [lower_inclusive,upper_exclusive)

Note
The std::exception thrown is std::out_of_range.

WARNING: This assert will evaluate index, lower_inclusive, and upper_inclusive more than once if there is a failure which will cause the side-effect of an additional evaluation. This is needed because the return types of these values are unknown. Therefore, only pass in arguments that are objects or function calls that have not side-effects!

Definition at line 82 of file Teuchos_Assert.hpp.

#define TEUCHOS_ASSERT_EQUALITY (   val1,
  val2 
)
Value:
{ \
(val1) != (val2), std::out_of_range, \
"Error, (" #val1 " = " << (val1) << ") != (" #val2 " = " << (val2) << ")!" ); \
}
#define TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, Exception, msg)
Macro for throwing an exception with breakpointing to ease debugging.

This macro is checks that to numbers are equal and if not then throws an exception with a good error message.

Note
The std::exception thrown is std::out_of_range.

WARNING: This assert will evaluate val1 and val2 more than once if there is a failure which will cause the side-effect of an additional evaluation. This is needed because the return types of val1 and val2 are unknown. Therefore, only pass in arguments that are objects or function calls that have not side-effects!

Examples:
ArrayRCP_test.cpp, DenseMatrix/cxx_main.cpp, DenseMatrix/cxx_main_sym.cpp, example/RefCountPtr/cxx_main.cpp, ParameterList/cxx_main.cpp, and test/MemoryManagement/RCP_test.cpp.

Definition at line 105 of file Teuchos_Assert.hpp.

#define TEUCHOS_ASSERT_INEQUALITY (   val1,
  comp,
  val2 
)
Value:
{ \
!( (val1) comp (val2) ), std::out_of_range, \
"Error, (" #val1 " = " << (val1) << ") " \
#comp " (" #val2 " = " << (val2) << ")! FAILED!" ); \
}
#define TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, Exception, msg)
Macro for throwing an exception with breakpointing to ease debugging.

This macro is checks that an inequality between two numbers is satisified and if not then throws a good exception message.

Note
The std::exception thrown is std::out_of_range.

WARNING: This assert will evaluate val1 and val2 more than once if there is a failure which will cause the side-effect of an additional evaluation. This is needed because the return types of val1 and val2 are unknown. Therefore, only pass in arguments that are objects or function calls that have not side-effects!

Definition at line 126 of file Teuchos_Assert.hpp.

#define TEUCHOS_TEST_FOR_EXCEPTION (   throw_exception_test,
  Exception,
  msg 
)
Value:
{ \
const bool throw_exception = (throw_exception_test); \
if(throw_exception) { \
const int throwNumber = Teuchos::TestForException_getThrowNumber(); \
std::ostringstream omsg; \
omsg \
<< __FILE__ << ":" << __LINE__ << ":\n\n" \
<< "Throw number = " << throwNumber \
<< "\n\n" \
<< "Throw test that evaluated to true: "#throw_exception_test \
<< "\n\n" \
<< msg; \
const std::string &omsgstr = omsg.str(); \
TEUCHOS_STORE_STACKTRACE(); \
Teuchos::TestForException_break(omsgstr, throwNumber); \
throw Exception(omsgstr); \
} \
}
TEUCHOSCORE_LIB_DLL_EXPORT int TestForException_getThrowNumber()
Increment the throw number.
TEUCHOSCORE_LIB_DLL_EXPORT void TestForException_incrThrowNumber()
Increment the throw number.
TEUCHOSCORE_LIB_DLL_EXPORT void TestForException_break(const std::string &msg, int throwNumber)
The only purpose for this function is to set a breakpoint.

Macro for throwing an exception with breakpointing to ease debugging.

Parameters
throw_exception_test[in] Test for when to throw the exception. This can and should be an expression that may mean something to the user. The text verbatim of this expression is included in the formed error string.
Exception[in] This should be the name of an exception class. The only requirement for this class is that it have a constructor that accepts an std::string object (as all of the standard exception classes do).
msg[in] This is any expression that can be included in an output stream operation. This is useful when buinding error messages on the fly. Note that the code in this argument only gets evaluated if throw_exception_test evaluates to true when an exception is throw.

The way that this macro is intended to be used is to call it in the source code like a function. For example, suppose that in a piece of code in the file my_source_file.cpp that the exception std::out_of_range is thrown if n > 100. To use the macro, the source code would contain (at line 225 for instance):

TEUCHOS_TEST_FOR_EXCEPTION( n > 100, std::out_of_range,
   "Error, n = " << n << is bad" );

When the program runs and with n = 125 > 100 for instance, the std::out_of_range exception would be thrown with the error message:

/home/bob/project/src/my_source_file.cpp:225: n > 100: Error, n = 125 is bad

In order to debug this, simply open your debugger (gdb for instance), set a break point at my_soure_file.cpp:225 and then set the condition to break for n > 100 (e.g. in gdb the command is cond break_point_number n > 100 and then run the program. The program should stop a the point in the source file right where the exception will be thrown at but before the exception is thrown. Try not to use expression for throw_exception_test that includes virtual function calls, etc. as most debuggers will not be able to check these types of conditions in order to stop at a breakpoint. For example, instead of:

TEUCHOS_TEST_FOR_EXCEPTION( obj1->val() > obj2->val(), std::logic_error, "Oh no!" );

try:

double obj1_val = obj1->val(), obj2_val = obj2->val();
TEUCHOS_TEST_FOR_EXCEPTION( obj1_val > obj2_val, std::logic_error, "Oh no!" );

If the developer goes to the line in the source file that is contained in the error message of the exception thrown, he/she will see the underlying condition.

As an alternative, you can set a breakpoint for any exception thrown by setting a breakpoint in the function ThrowException_break(). If multiple exceptions are thrown, then set a conditional breakpoint to break on the exact exception using the throwNumber. For example, if the throw number printed in the exception message is 10 then set the break point as (assuming this is the first breakpoint):

(gdb) b 'Teuchos::TestForException_break( [TAB] [ENTER]
(gdb) cond 1 thrownNumber==10

NOTE: This macro will only evaluate throw_exception_test once reguardless if the test fails and the exception is thrown or not. Therefore, it is safe to call a function with side-effects as the throw_exception_test argument.

NOTE: This macro will result in creating a stacktrace snapshot in some cases (see the main doc page for details) and will be printed automatically when main() uses TEUCHOS_STANDARD_CATCH_STATEMENTS() to catch uncaught excpetions.

Definition at line 178 of file Teuchos_TestForException.hpp.

#define TEUCHOS_TEST_FOR_EXCEPTION_CLASS_FUNC (   throw_exception_test,
  Exception,
  msg 
)
Value:
{ \
TEUCHOS_TEST_FOR_EXCEPTION( (throw_exception_test), Exception, \
Teuchos::typeName(*this) << "::" << tfecfFuncName << msg ) \
}
#define TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, Exception, msg)
Macro for throwing an exception with breakpointing to ease debugging.
std::string typeName(const T &t)
Template function for returning the concrete type name of a passed-in object.

Macro for throwing an exception from within a class method with breakpointing to ease debugging.

Parameters
throw_exception_test[in] Test for when to throw the exception. This can and should be an expression that may mean something to the user. The text verbatim of this expression is included in the formed error string.
Exception[in] This should be the name of an exception class. The only requirement for this class is that it have a constructor that accepts an std::string object (as all of the standard exception classes do).
msg[in] This is any expression that can be included in an output stream operation. This is useful when buinding error messages on the fly. Note that the code in this argument only gets evaluated if throw_exception_test evaluates to true when an exception is throw.
tfecfFuncName[implicit] This is a variable in the current scope that is required to exist and assumed to contain the name of the current class method.
this[implicit] This is the variable (*this), used for printing the typename of the enclosing class.

The way that this macro is intended to be used is to call it from a member of of a class. It is used similarly to TEUCHOS_TEST_FOR_EXCEPTION, except that it assumes that the (above) variables this and fecfFuncName exist and are properly defined. Example usage is:

std::string tfecfFuncName("someMethod");
TEUCHOS_TEST_FOR_EXCEPTION_CLASS_FUNC( test, std::runtime_error,
": can't call this method in that way.");

See TEUCHOS_TEST_FOR_EXCEPTION() for more details.

Definition at line 241 of file Teuchos_TestForException.hpp.

#define TEUCHOS_TEST_FOR_EXCEPTION_PURE_MSG (   throw_exception_test,
  Exception,
  msg 
)
Value:
{ \
const bool throw_exception = (throw_exception_test); \
if(throw_exception) { \
const int throwNumber = Teuchos::TestForException_getThrowNumber(); \
std::ostringstream omsg; \
omsg << msg; \
omsg << "\n\nThrow number = " << throwNumber << "\n\n"; \
const std::string &omsgstr = omsg.str(); \
Teuchos::TestForException_break(omsgstr, throwNumber); \
TEUCHOS_STORE_STACKTRACE(); \
throw Exception(omsgstr); \
} \
}
TEUCHOSCORE_LIB_DLL_EXPORT int TestForException_getThrowNumber()
Increment the throw number.
TEUCHOSCORE_LIB_DLL_EXPORT void TestForException_incrThrowNumber()
Increment the throw number.
TEUCHOSCORE_LIB_DLL_EXPORT void TestForException_break(const std::string &msg, int throwNumber)
The only purpose for this function is to set a breakpoint.

Macro for throwing an exception with breakpointing to ease debugging.

This macro is equivalent to the TEUCHOS_TEST_FOR_EXCEPTION() macro except the file name, line number, and test condition are not printed.

Definition at line 255 of file Teuchos_TestForException.hpp.

#define TEUCHOS_TEST_FOR_EXCEPTION_PRINT (   throw_exception_test,
  Exception,
  msg,
  out_ptr 
)
Value:
try { \
TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, Exception, msg); \
} \
catch(const std::exception &except) { \
std::ostream *l_out_ptr = (out_ptr); \
if(l_out_ptr) { \
*l_out_ptr \
<< "\nThrowing an std::exception of type \'"<<Teuchos::typeName(except) \
<<"\' with the error message: " \
<< except.what(); \
} \
throw; \
}
#define TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, Exception, msg)
Macro for throwing an exception with breakpointing to ease debugging.
std::string typeName(const T &t)
Template function for returning the concrete type name of a passed-in object.

This macro is the same as TEUCHOS_TEST_FOR_EXCEPTION() except that the exception will be caught, the message printed, and then rethrown.

Parameters
throw_exception_test[in] See TEUCHOS_TEST_FOR_EXCEPTION().
Exception[in] See TEUCHOS_TEST_FOR_EXCEPTION().
msg[in] See TEUCHOS_TEST_FOR_EXCEPTION().
out_ptr[in] If out_ptr!=NULL then *out_ptr will receive a printout of a line of output that gives the exception type and the error message that is generated.

See TEUCHOS_TEST_FOR_EXCEPTION() for more details.

Definition at line 289 of file Teuchos_TestForException.hpp.

#define TEUCHOS_TEST_FOR_EXCEPT (   throw_exception_test)    TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, std::logic_error, "Error!")

This macro is designed to be a short version of TEUCHOS_TEST_FOR_EXCEPTION() that is easier to call.

Parameters
throw_exception_test[in] Test for when to throw the exception. This can and should be an expression that may mean something to the user. The text verbatim of this expression is included in the formed error string.
Note
The exception thrown is std::logic_error.
Examples:
ArrayRCP_test.cpp, and test/MemoryManagement/RCP_test.cpp.

Definition at line 317 of file Teuchos_TestForException.hpp.

#define TEUCHOS_TEST_FOR_EXCEPT_MSG (   throw_exception_test,
  msg 
)    TEUCHOS_TEST_FOR_EXCEPTION(throw_exception_test, std::logic_error, msg)

This macro is designed to be a short version of TEUCHOS_TEST_FOR_EXCEPTION() that is easier to call.

Parameters
throw_exception_test[in] Test for when to throw the exception. This can and should be an expression that may mean something to the user. The text verbatim of this expression is included in the formed error string.
msg[in] The error message.
Note
The exception thrown is std::logic_error.

See TEUCHOS_TEST_FOR_EXCEPTION() for more details.

Definition at line 337 of file Teuchos_TestForException.hpp.

#define TEUCHOS_TEST_FOR_EXCEPT_PRINT (   throw_exception_test,
  out_ptr 
)    TEUCHOS_TEST_FOR_EXCEPTION_PRINT(throw_exception_test, std::logic_error, "Error!", out_ptr)

This macro is the same as TEUCHOS_TEST_FOR_EXCEPT() except that the exception will be caught, the message printed, and then rethrown.

Parameters
throw_exception_test[in] See TEUCHOS_TEST_FOR_EXCEPT().
out_ptr[in] If out_ptr!=NULL then *out_ptr will receive a printout of a line of output that gives the exception type and the error message that is generated.

See TEUCHOS_TEST_FOR_EXCEPTION() for more details.

Examples:
FancyOutputting_test.cpp.

Definition at line 354 of file Teuchos_TestForException.hpp.

#define TEUCHOS_TRACE (   exc)
Value:
{ \
std::ostringstream omsg; \
omsg << exc.what() << std::endl \
<< "caught in " << __FILE__ << ":" << __LINE__ << std::endl ; \
throw std::runtime_error(omsg.str()); \
}

This macro intercepts an exception, prints a standardized message including the current filename and line number, and then throws the exception up the stack.

Parameters
exc[in] the exception that has been caught

Definition at line 366 of file Teuchos_TestForException.hpp.

#define TEUCHOS_TEST_FOR_TERMINATION (   terminate_test,
  msg 
)
Value:
{ \
const bool call_terminate = (terminate_test); \
if (call_terminate) { \
std::ostringstream omsg; \
omsg \
<< __FILE__ << ":" << __LINE__ << ":\n\n" \
<< "Terminate test that evaluated to true: "#terminate_test \
<< "\n\n" \
<< msg << "\n\n"; \
auto str = omsg.str(); \
} \
}
TEUCHOSCORE_LIB_DLL_EXPORT void TestForTermination_terminate(const std::string &msg)
Prints the message to std::cerr and calls std::terminate.

This macro is to be used instead of TEUCHOS_TEST_FOR_EXCEPTION() to report an error in situations where an exception can't be throw (like in an destructor).

Parameters
terminate_test[in] See TEUCHOS_TEST_FOR_EXCEPTION().
msg[in] See TEUCHOS_TEST_FOR_EXCEPTION().

If the termination test evaluates to true, then std::terminate() is called (which should bring down an entire multi-process MPI program even if only one process calls std::terminate() with most MPI implementations).

Definition at line 389 of file Teuchos_TestForException.hpp.

Function Documentation

void Teuchos::TestForException_incrThrowNumber ( )

Increment the throw number.

Definition at line 74 of file Teuchos_TestForException.cpp.

int Teuchos::TestForException_getThrowNumber ( )

Increment the throw number.

Definition at line 80 of file Teuchos_TestForException.cpp.

void Teuchos::TestForException_break ( const std::string &  msg,
int  throwNumber 
)

The only purpose for this function is to set a breakpoint.

Definition at line 86 of file Teuchos_TestForException.cpp.

void Teuchos::TestForException_setEnableStacktrace ( bool  enableStrackTrace)

Set at runtime if stacktracing functionality is enabled when * exceptions are thrown.

Definition at line 105 of file Teuchos_TestForException.cpp.