9.4 Using the Thread-compatible Exception Classes

The base class in the Thread-compatible Exception package is RWTHRxmsg, which derives from the Tools.h++ class RWxmsg. A thread-compatible exception can be copied and stored, so that it can be rethrown in the future. This capability, which makes passing across thread boundaries possible, comes from the RWTHRxmsg member functions clone() and raise(). For more information about passing exceptions across thread boundaries, see Section 3.5.8, "Catching and Rethrowing Exceptions."

9.4.1 Creating Your Own Exception Classes

Any special-purpose exception classes you derive from RWTHRxmsg will be thread-compatible. You must redefine the clone() and raise() members in your exception classes. For your convenience, Threads.h++ provides the following macros that expand into the clone() and raise() code.

RW_THR_DECLARE_EXCEPTION(yourClassName)

Declares the clone() and raise() member functions. This macro must be placed inside your class declaration.

RW_THR_IMPLEMENT_EXCEPTION(yourClassName)

Provides the definitions for the clone() and raise() member functions declared by the matching DECLARE macro (above). This macro must be placed in the implementation (.cpp) file for your class.

RW_THR_IMPLEMENT_TRACEABLE_EXCEPTION(yourClassName)

Used instead of the RW_THR_IMPLEMENT_EXCEPTION macro where entry/exit tracing is desired for the clone() and raise() member functions. (See Chapter 6, "The Execution Tracing Package.")

RW_THR_DECLARE_INLINE_EXCEPTION(yourClassName)

Used instead of the RW_THR_DECLARE_EXCEPTION macro to provide inline definitions for the clone() and raise() member functions. This macro must be placed inside your class declaration. You use this macro alone for inline definitions; you do not need either of the IMPLEMENT macros listed above. If you want your functions to have entry/exit tracing, you cannot define them inline.

9.4.2 Creating Your Own Error Handler

If you want to handle all types of exceptions the same way, such as writing out their messages, you need only one catch block for the base class. For example, suppose that your application uses the combination of predefined and user-defined exception classes shown in Figure 55.

Figure 55 -- Hierarchy of Rogue Wave and user-defined exceptions

You could log all the exceptions of type RWxmsg, RWTHRxmsg, and MYxmsg with the simple statement shown in Example 78.

Example 78 -- Implementing a simple error handler

catch(RWxmsg& emsg) {
  ...
  cout << "Oh-oh: " << emsg.why() << endl;
  ...
}

Because RWTHRxmsg and MYxmsg derive from RWXmsg, this code catches all these exceptions.

If you want to do something different with each exception type, however, you need three separate catch blocks with the most derived type handled first, as shown in Example 79.

Example 79 -- Handling multiple exception types differently

catch(MYxmsg& emsg) {
  ...
  handle my special-purpose thread-compatible exceptions
  ...
}

catch(RWTHRxmsg& emsg) {
  ...
  handle the generic thread-compatible exceptions
  ...
}

catch(RWxmsg& emsg) {
  ...
  handle the non-thread-compatible C++ exceptions
  ...
}

For more information, see the discussion of error handlers in the Tools.h++ User's Guide.

9.4.3 Making Existing Exceptions Thread-Compatible

You can create a thread-compatible exception from any existing non-compatible exception class. Thread-compatible Exception provides the template class RWTTHRCompatibleException<Exception>, which acts as a wrapper to your legacy exception class. An RWTTHRCompatibleException is stored like any other exception type. But instead of rethrowing itself, its raise() member function causes the legacy exception to be rethrown. See the Threads.h++ Reference Guide for more information.