Utility code for throwing exceptions and setting breakpoints.
[Teuchos Language Support Utilities]


Defines

#define TEST_FOR_EXCEPTION(throw_exception_test, Exception, msg)
 Macro for throwing an exception with breakpointing to ease debugging.
#define TEST_FOR_EXCEPT(throw_exception_test)   TEST_FOR_EXCEPTION(throw_exception_test,std::logic_error,"Error!")
 This macro is designed to be a short version of TEST_FOR_EXCEPTION() that is easier to call.
#define TEST_FOR_EXCEPTION_PRINT(throw_exception_test, Exception, msg, out_ptr)
 This macro is the same as TEST_FOR_EXCEPTION() except that the exception will be caught, the message printed, and then rethrown.
#define TEST_FOR_EXCEPT_PRINT(throw_exception_test, out_ptr)   TEST_FOR_EXCEPTION_PRINT(throw_exception_test,std::logic_error,"Error!",out_ptr)
 This macro is the same as TEST_FOR_EXCEPT() except that the exception will be caught, the message printed, and then rethrown.
#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.

Functions

void TestForException_break ()
 The only purpose for this function is to set a breakpoint.

Define Documentation

#define TEST_FOR_EXCEPTION throw_exception_test,
Exception,
msg   ) 
 

Value:

{ \
    const bool throw_exception = (throw_exception_test); \
    if(throw_exception) { \
        TestForException_break(); \
      TeuchosOStringStream omsg; \
      omsg << __FILE__ << ":" << __LINE__ << ": " \
             << #throw_exception_test << ": " << msg; \
      throw Exception(TEUCHOS_OSTRINGSTREAM_GET_C_STR(omsg)); \
    } \
}
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 and null terminated C string (i.e. const char*).
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):

 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:


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

 double obj1_val = obj1->val(), obj2_val = obj2->val();
 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().

Definition at line 109 of file Teuchos_TestForException.hpp.

#define TEST_FOR_EXCEPT throw_exception_test   )     TEST_FOR_EXCEPTION(throw_exception_test,std::logic_error,"Error!")
 

This macro is designed to be a short version of 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:
test/RefCountPtr/cxx_main.cpp.

Definition at line 132 of file Teuchos_TestForException.hpp.

#define TEST_FOR_EXCEPTION_PRINT throw_exception_test,
Exception,
msg,
out_ptr   ) 
 

Value:

try { \
  TEST_FOR_EXCEPTION(throw_exception_test,Exception,msg); \
} \
catch(const std::exception &except) { \
  ostream *l_out_ptr = (out_ptr); \
  if(l_out_ptr) { \
    *l_out_ptr \
      << "\nThorwing an std::exception of type \'"<<typeid(except).name()<<"\' with the error message: " \
      << except.what(); \
  } \
  throw; \
}
This macro is the same as TEST_FOR_EXCEPTION() except that the exception will be caught, the message printed, and then rethrown.

Parameters:
throw_exception_test [in] See TEST_FOR_EXCEPTION().
Exception [in] See TEST_FOR_EXCEPTION().
msg [in] See 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.

Definition at line 147 of file Teuchos_TestForException.hpp.

#define TEST_FOR_EXCEPT_PRINT throw_exception_test,
out_ptr   )     TEST_FOR_EXCEPTION_PRINT(throw_exception_test,std::logic_error,"Error!",out_ptr)
 

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

Parameters:
throw_exception_test [in] See 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.
Examples:
FancyOutputting_test.cpp.

Definition at line 171 of file Teuchos_TestForException.hpp.

#define TEUCHOS_TRACE exc   ) 
 

Value:

{ \
  TeuchosOStringStream omsg; \
  omsg << exc.what() << endl \
  << "caught in " << __FILE__ << ":" << __LINE__ << endl ; \
  throw std::runtime_error(TEUCHOS_OSTRINGSTREAM_GET_C_STR(omsg));  \
}
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 178 of file Teuchos_TestForException.hpp.


Function Documentation

void TestForException_break  ) 
 

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

Definition at line 31 of file Teuchos_TestForException.cpp.


Generated on Thu Sep 18 12:30:31 2008 for Teuchos - Trilinos Tools Package by doxygen 1.3.9.1