bslstl_stdexceptutil

Typedefs
typedef bslstl::StdExceptUtil	bslstl_StdExceptUtil
	This alias is defined for backward compatibility.

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Pre-Throw Hooks
  • Usage

Purpose

Provide a utility to throw standard exceptions.

Classes

• bslstl::StdExceptUtil: namespace for utilities to throw standard exceptions

Canonical header: bsl_stdexcept.h

See also

stdexcept

Description

This component provides a means to throw standard exceptions without introducing a compile-time dependency on the standard exception classes. This valuable where header files define function templates or inline functions that may throw these types as exceptions.

Pre-Throw Hooks

For each exception type supported by this component, there is a "pre throw hook", a function pointer that is normally null. If that pointer is set to a function, that function is called prior to the throw. This gives the client a chance to log a message.

If the pre-throw hook is set to StdExceptUtil::logCheapStackTrace, a cheap stack trace will be logged, enabling the client to use /bb/bin/showfunc.tsk on the cheap stack trace to get a stack trace with symbols. When running showfunc.tsk, pipe the output through c++filt to get demangled symbols.

If the pre-throw hook is set to balst::StackTracePrintUtil::logExceptionStackTrace, a full multi-line stack trace with symbols will be logged, with, on some platforms, symbol demangling, line numbers, and source file names. This alternative requires considerable disk access and is therefore orders of magnitude slower than the cheap stack trace.

Usage

First we declare a function template that wants to throw a standard exception. Note that the stdexcept header is not included at this point.

#include <bslstl_stdexceptutil.h>
 
template<typename T>
void testFunction(int selector)
    //  Throw a standard exception according to the specified 'selector'.
{
switch(selector) {
  case 1: {
    bslstl::StdExceptUtil::throwRuntimeError("sample message 1");
  } break;
  case 2: {
    bslstl::StdExceptUtil::throwLogicError("sample message 2");
  } break;
  default: {
    bslstl::StdExceptUtil::throwInvalidArgument("ERROR");
  } break;
}

However, if client code wishes to catch the exception, the .cpp file must #include the appropriate header.

#include <stdexcept>
 
void callTestFunction()
{
  try {
    testFunction<int>(1);
    assert(0 == "Should throw before reaching here.");
  }
  catch(const runtime_error& ex) {
    assert(0 == std::strcmp(ex.what(), "sample message 1"));
  }
 
  try {
    testFunction<double>(2);
    assert(0 == "Should throw before reaching here.");
  }
  catch(const logic_error& ex) {
    assert(0 == std::strcmp(ex.what(), "sample message 2"));
  }
}

Typedef Documentation

bslstl_StdExceptUtil

typedef bslstl::StdExceptUtil bslstl_StdExceptUtil