Thinking in C++ - Volume 2

If you're inside a function and you throw an exception (or a called function throws an exception), the function exits because of the thrown exception. If you don't want a throw to leave a function, you can set up a special block within the function where you try to solve your actual programming problem (and potentially generate exceptions). This block is called the try block because you try your various function calls there. The try block is an ordinary scope, preceded by the keyword try:

try {
  // Code that may generate exceptions
}

If you check for errors by carefully examining the return codes from the functions you use, you need to surround every function call with setup and test code, even if you call the same function several times. With exception handling, you put everything in a try block and handle exceptions after the try block. Thus, your code is a lot easier to write and to read because the goal of the code is not confused with the error handling.

Of course, the thrown exception must end up some place. This place is the exception handler, and you need one exception handler for every exception type you want to catch. However, polymorphism also works for exceptions, so one exception handler can work with an exception type and classes derived from that type.

Exception handlers immediately follow the try block and are denoted by the keyword catch:

try {
  // Code that may generate exceptions
} catch(type1 id1) {
  // Handle exceptions of type1
} catch(type2 id2) {
  // Handle exceptions of type2
} catch(type3 id3)
  // Etc...
} catch(typeN idN)
  // Handle exceptions of typeN
}
// Normal execution resumes here...

The syntax of a catch clause resembles functions that take a single argument. The identifier (id1, id2, and so on) can be used inside the handler, just like a function argument, although you can omit the identifier if it's not needed in the handler. The exception type usually gives you enough information to deal with it.

The handlers must appear directly after the try block. If an exception is thrown, the exception-handling mechanism goes hunting for the first handler with an argument that matches the type of the exception. It then enters that catch clause, and the exception is considered handled. (The search for handlers stops once the catch clause is found.) Only the matching catch clause executes; control then resumes after the last handler associated with that try block.

Notice that, within the try block, a number of different function calls might generate the same type of exception, but you need only one handler.

To illustrate try and catch, the following variation of Nonlocal.cpp replaces the call to setjmp( ) with a try block and replaces the call to longjmp( ) with a throw statement:

//: C01:Nonlocal2.cpp
// Illustrates exceptions.
#include <iostream>
using namespace std;
 
class Rainbow {
public:
  Rainbow() { cout << "Rainbow()"
<< endl; }
  ~Rainbow() { cout << "~Rainbow()"
<< endl; }
};
 
void oz() {
  Rainbow rb;
  for(int i = 0; i < 3; i++)
    cout << "there's no place like
home" << endl;
  throw 47;
}
 
int main() {
  try {
    cout << "tornado, witch, munchkins..."
<< endl;
    oz();
  } catch(int) {
    cout << "Auntie Em! I had the strangest
dream..."
         << endl;
  }
} ///:~

When the throw statement in oz( ) executes, program control backtracks until it finds the catch clause that takes an int parameter. Execution resumes with the body of that catch clause. The most important difference between this program and Nonlocal.cpp is that the destructor for the object rb is called when the throw statement causes execution to leave the function oz( ).

There are two basic models in exception-handling theory: termination and resumption. In termination (which is what C++ supports), you assume the error is so critical that there's no way to automatically resume execution at the point where the exception occurred. In other words, whoever threw the exception decided there was no way to salvage the situation, and they don't want to come back.

The alternative error-handling model is called resumption, first introduced with the PL/I language in the 1960s.(2) Using resumption semantics means that the exception handler is expected to do something to rectify the situation, and then the faulting code is automatically retried, presuming success the second time. If you want resumption in C++, you must explicitly transfer execution back to the code where the error occurred, usually by repeating the function call that sent you there in the first place. It is not unusual to place your try block inside a while loop that keeps reentering the try block until the result is satisfactory.

Historically, programmers using operating systems that supported resumptive exception handling eventually ended up using termination-like code and skipping resumption. Although resumption sounds attractive at first, it seems it isn't quite so useful in practice. One reason may be the distance that can occur between the exception and its handler. It is one thing to terminate to a handler that's far away, but to jump to that handler and then back again may be too conceptually difficult for large systems where the exception is generated from many points.

Sometimes you want to create a handler that catches any type of exception. You do this using the ellipsis in the argument list:

catch(...) {
  cout << "an exception was thrown"
<< endl;
}

Because an ellipsis catches any exception, you'll want to put it at the end of your list of handlers to avoid pre-empting any that follow it.

The ellipsis gives you no possibility to have an argument, so you can't know anything about the exception or its type. It's a “catchall.” Such a catch clause is often used to clean up some resources and then rethrow the exception.

You usually want to rethrow an exception when you have some resource that needs to be released, such as a network connection or heap memory that needs to be deallocated. (See the section “Resource Management” later in this chapter for more detail). If an exception occurs, you don't necessarily care what error caused the exception—you just want to close the connection you opened previously. After that, you'll want to let some other context closer to the user (that is, higher up in the call chain) handle the exception. In this case the ellipsis specification is just what you want. You want to catch any exception, clean up your resource, and then rethrow the exception for handling elsewhere. You rethrow an exception by using throw with no argument inside a handler:

catch(...) {
cout << "an exception was
thrown" << endl;
// Deallocate your resource here,
and then rethrow
  throw;
}

Any further catch clauses for the same try block are still ignored—the throw causes the exception to go to the exception handlers in the next-higher context. In addition, everything about the exception object is preserved, so the handler at the higher context that catches the specific exception type can extract any information the object may contain.

As we explained in the beginning of this chapter, exception handling is considered better than the traditional return-an-error-code technique because exceptions can't be ignored, and because the error handling logic is separated from the problem at hand. If none of the exception handlers following a particular try block matches an exception, that exception moves to the next-higher context, that is, the function or try block surrounding the try block that did not catch the exception. (The location of this try block is not always obvious at first glance, since it's higher up in the call chain.) This process continues until, at some level, a handler matches the exception. At that point, the exception is considered “caught,” and no further searching occurs.

The terminate( ) function

If no handler at any level catches the exception, the special library function terminate( ) (declared in the <exception> header) is automatically called. By default, terminate( ) calls the Standard C library function abort( ) , which abruptly exits the program. On Unix systems, abort( ) also causes a core dump. When abort( ) is called, no calls to normal program termination functions occur, which means that destructors for global and static objects do not execute. The terminate( ) function also executes if a destructor for a local object throws an exception while the stack is unwinding (interrupting the exception that was in progress) or if a global or static object's constructor or destructor throws an exception. (In general, do not allow a destructor to throw an exception.)

The set_terminate( ) function

You can install your own terminate( ) function using the standard set_terminate( ) function, which returns a pointer to the terminate( ) function you are replacing (which will be the default library version the first time you call it), so you can restore it later if you want. Your custom terminate( ) must take no arguments and have a void return value. In addition, any terminate( ) handler you install must not return or throw an exception, but instead must execute some sort of program-termination logic. If terminate( ) is called, the problem is unrecoverable.

The following example shows the use of set_terminate( ). Here, the return value is saved and restored so that the terminate( ) function can be used to help isolate the section of code where the uncaught exception occurs:

//: C01:Terminator.cpp
// Use of set_terminate(). Also shows uncaught
exceptions.
#include <exception>
#include <iostream>
using namespace std;
 
void terminator() {
  cout << "I'll be back!" <<
endl;
  exit(0);
}
 
void (*old_terminate)() = set_terminate(terminator);
 
class Botch {
public:
  class Fruit {};
  void f() {
    cout << "Botch::f()" << endl;
    throw Fruit();
  }
  ~Botch() { throw 'c'; }
};
 
int main() {
  try {
    Botch b;
    b.f();
  } catch(...) {
    cout << "inside catch(...)"
<< endl;
  }
} ///:~

The definition of old_terminate looks a bit confusing at first: it not only creates a pointer to a function, but it initializes that pointer to the return value of set_terminate( ). Even though you might be familiar with seeing a semicolon right after a pointer-to-function declaration, here it's just another kind of variable and can be initialized when it is defined.

The class Botch not only throws an exception inside f( ), but also in its destructor. This causes a call to terminate( ), as you can see in main( ). Even though the exception handler says catch(...), which would seem to catch everything and leave no cause for terminate( ) to be called, terminate( ) is called anyway. In the process of cleaning up the objects on the stack to handle one exception, the Botch destructor is called, and that generates a second exception, forcing a call to terminate( ). Thus, a destructor that throws an exception or causes one to be thrown is usually a sign of poor design or sloppy coding.

When writing code with exceptions, it's particularly important that you always ask, “If an exception occurs, will my resources be properly cleaned up?” Most of the time you're fairly safe, but in constructors there's a particular problem: if an exception is thrown before a constructor is completed, the associated destructor will not be called for that object. Thus, you must be especially diligent while writing your constructor.

The difficulty is in allocating resources in constructors. If an exception occurs in the constructor, the destructor doesn't get a chance to deallocate the resource. This problem occurs most often with “naked” pointers. For example:

//: C01:Rawp.cpp
// Naked pointers.
#include <iostream>
#include <cstddef>
using namespace std;
 
class Cat {
public:
  Cat() { cout << "Cat()" <<
endl; }
  ~Cat() { cout << "~Cat()" <<
endl; }
};
 
class Dog {
public:
  void* operator new(size_t sz) {
    cout << "allocating a Dog" <<
endl;
    throw 47;
  }
  void operator delete(void* p) {
    cout << "deallocating a Dog"
<< endl;
    ::operator delete(p);
  }
};
 
class UseResources {
  Cat* bp;
  Dog* op;
public:
  UseResources(int count = 1) {
    cout << "UseResources()" <<
endl;
    bp = new Cat[count];
    op = new Dog;
  }
  ~UseResources() {
    cout << "~UseResources()" <<
endl;
    delete [] bp; // Array delete
    delete op;
  }
};
 
int main() {
  try {
    UseResources ur(3);
  } catch(int) {
    cout << "inside handler" <<
endl;
  }
} ///:~

The output is

UseResources()
Cat()
Cat()
Cat()
allocating a Dog
inside handler

The UseResources constructor is entered, and the Cat constructor is successfully completed for the three array objects. However, inside Dog::operator new( ), an exception is thrown (to simulate an out-of-memory error). Suddenly, you end up inside the handler, without the UseResources destructor being called. This is correct because the UseResources constructor was unable to finish, but it also means the Cat objects that were successfully created on the heap were never destroyed.

To prevent such resource leaks, you must guard against these “raw” resource allocations in one of two ways:

• You can catch exceptions inside the constructor and then release the resource.
• You can place the allocations inside an object's constructor, and you can place the deallocations inside an object's destructor.

Using the latter approach, each allocation becomes atomic, by virtue of being part of the lifetime of a local object, and if it fails, the other resource allocation objects are properly cleaned up during stack unwinding. This technique is called Resource Acquisition Is Initialization (RAII for short) because it equates resource control with object lifetime. Using templates is an excellent way to modify the previous example to achieve this:

//: C01:Wrapped.cpp
// Safe, atomic pointers.
#include <iostream>
#include <cstddef>
using namespace std;
 
// Simplified. Yours may have other arguments.
template<class T, int sz = 1> class PWrap {
  T* ptr;
public:
  class RangeError {}; // Exception class
  PWrap() {
    ptr = new T[sz];
    cout << "PWrap constructor"
<< endl;
  }
  ~PWrap() {
    delete[] ptr;
    cout << "PWrap destructor" <<
endl;
  }
  T& operator[](int i) throw(RangeError) {
    if(i >= 0 && i < sz) return ptr[i];
    throw RangeError();
  }
};
 
class Cat {
public:
  Cat() { cout << "Cat()" <<
endl; }
  ~Cat() { cout << "~Cat()" <<
endl; }
  void g() {}
};
 
class Dog {
public:
  void* operator new[](size_t) {
    cout << "Allocating a Dog" <<
endl;
    throw 47;
  }
  void operator delete[](void* p) {
    cout << "Deallocating a Dog"
<< endl;
    ::operator delete[](p);
  }
};
 
class UseResources {
  PWrap<Cat, 3> cats;
  PWrap<Dog> dog;
public:
  UseResources() { cout <<
"UseResources()" << endl; }
  ~UseResources() { cout <<
"~UseResources()" << endl; }
  void f() { cats[1].g(); }
};
 
int main() {
  try {
    UseResources ur;
  } catch(int) {
    cout << "inside handler" <<
endl;
  } catch(...) {
    cout << "inside catch(...)"
<< endl;
  }
} ///:~

The difference is the use of the template to wrap the pointers and make them into objects. The constructors for these objects are called before the body of the UseResources constructor, and any of these constructors that complete before an exception is thrown will have their associated destructors called during stack unwinding.

The PWrap template shows a more typical use of exceptions than you've seen so far: A nested class called RangeError is created to use in operator[ ] if its argument is out of range. Because operator[ ] returns a reference, it cannot return zero. (There are no null references.) This is a true exceptional condition—you don't know what to do in the current context and you can't return an improbable value. In this example, RangeError(5) is simple and assumes all the necessary information is in the class name, but you might also want to add a member that contains the value of the index, if that is useful.

Now the output is

Cat()
Cat()
Cat()
PWrap constructor
allocating a Dog
~Cat()
~Cat()
~Cat()
PWrap destructor
inside handler

Again, the storage allocation for Dog throws an exception, but this time the array of Cat objects is properly cleaned up, so there is no memory leak.

Since dynamic memory is the most frequent resource used in a typical C++ program, the standard provides an RAII wrapper for pointers to heap memory that automatically frees the memory. The auto_ptr class template, defined in the <memory> header, has a constructor that takes a pointer to its generic type (whatever you use in your code). The auto_ptr class template also overloads the pointer operators * and -> to forward these operations to the original pointer the auto_ptr object is holding. So you can use the auto_ptr object as if it were a raw pointer. Here's how it works:

//: C01:Auto_ptr.cpp
// Illustrates the RAII nature of auto_ptr.
#include <memory>
#include <iostream>
#include <cstddef>
using namespace std;
 
class TraceHeap {
  int i;
public:
  static void* operator new(size_t siz) {
    void* p = ::operator new(siz);
    cout << "Allocating TraceHeap object on
the heap "
         << "at address " << p
<< endl;
    return p;
  }
  static void operator delete(void* p) {
    cout << "Deleting TraceHeap object at
address "
         << p << endl;
    ::operator delete(p);
  }
  TraceHeap(int i) : i(i) {}
  int getVal() const { return i; }
};
 
int main() {
  auto_ptr<TraceHeap> pMyObject(new
TraceHeap(5));
  cout << pMyObject->getVal() << endl; 
// Prints 5
} ///:~

The TraceHeap class overloads the operator new and operator delete so you can see exactly what's happening. Notice that, like any other class template, you specify the type you're going to use in a template parameter. You don't say TraceHeap*, however—auto_ptr already knows that it will be storing a pointer to your type. The second line of main( ) verifies that auto_ptr's operator->( ) function applies the indirection to the original, underlying pointer. Most important, even though we didn't explicitly delete the original pointer, pMyObject's destructor deletes the original pointer during stack unwinding, as the following output verifies:

Allocating TraceHeap object on the heap at address
8930040
5
Deleting TraceHeap object at
address 8930040

The auto_ptr class template is also handy for pointer data members. Since class objects contained by value are always destructed, auto_ptr members always delete the raw pointer they wrap when the containing object is destructed.(6)

Since constructors can routinely throw exceptions, you might want to handle exceptions that occur when an object's member or base subobjects are initialized. To do this, you can place the initialization of such subobjects in a function-level try block. In a departure from the usual syntax, the try block for constructor initializers is the constructor body, and the associated catch block follows the body of the constructor, as in the following example:

//: C01:InitExcept.cpp {-bor}
// Handles exceptions from subobjects.
#include <iostream>
using namespace std;
 
class Base {
  int i;
public:
  class BaseExcept {};
  Base(int i) : i(i) { throw BaseExcept(); }
};
 
class Derived : public Base {
public:
  class DerivedExcept {
    const char* msg;
  public:
    DerivedExcept(const char* msg) : msg(msg) {}
    const char* what() const { return msg; }
  };
  Derived(int j) try : Base(j) {
    // Constructor body
    cout << "This won't print" <<
endl;
  } catch(BaseExcept&) {
    throw DerivedExcept("Base subobject
threw");;
  }
};
 
int main() {
  try {
    Derived d(3);
  } catch(Derived::DerivedExcept& d) {
    cout << d.what() << endl;  //
"Base subobject threw"
  }
} ///:~

Notice that the initializer list in the constructor for Derived goes after the try keyword but before the constructor body. If an exception does occur, the contained object is not constructed, so it makes no sense to return to the code that created it. For this reason, the only sensible thing to do is to throw an exception in the function-level catch clause.

Although it is not terribly useful, C++ also allows function-level try blocks for any function, as the following example illustrates:

//: C01:FunctionTryBlock.cpp {-bor}
// Function-level try blocks.
// {RunByHand} (Don't run automatically by the
makefile)
#include <iostream>
using namespace std;
 
int main() try {
  throw "main";
} catch(const char* msg) {
cout << msg << endl;
return 1;
} ///:~

In this case, the catch block can return in the same manner that the function body normally returns. Using this type of function-level try block isn't much different from inserting a try-catch around the code inside of the function body.

You may feel that the existing exception specification rules aren't very safe, and that

void f();

should mean that no exceptions are thrown from this function. If the programmer wants to throw any type of exception, you might think he or she should have to say

void f() throw(...); // Not in C++

This would surely be an improvement because function declarations would be more explicit. Unfortunately, you can't always know by looking at the code in a function whether an exception will be thrown—it could happen because of a memory allocation, for example. Worse, existing functions written before exception handling was introduced into the language may find themselves inadvertently throwing exceptions because of the functions they call (which might be linked into new, exception-throwing versions). Hence, the uninformative situation whereby

void f();

means, “Maybe I'll throw an exception, maybe I won't.” This ambiguity is necessary to avoid hindering code evolution. If you want to specify that f throws no exceptions, use the empty list, as in:

void f() throw();

Each public function in a class essentially forms a contract with the user; if you pass it certain arguments, it will perform certain operations and/or return a result. The same contract must hold true in derived classes; otherwise the expected “is-a” relationship between derived and base classes is violated. Since exception specifications are logically part of a function's declaration, they too must remain consistent across an inheritance hierarchy. For example, if a member function in a base class says it will only throw an exception of type A, an override of that function in a derived class must not add any other exception types to the specification list because that would break any programs that adhere to the base class interface. You can, however, specify fewer exceptions or none at all, since that doesn't require the user to do anything differently. You can also specify anything that “is-a” A in place of A in the derived function's specification. Here's an example.

//: C01:Covariance.cpp {-xo}
// Should cause compile error. {-mwcc}{-msc}
#include <iostream>
using namespace std;
 
class Base {
public:
  class BaseException {};
  class DerivedException : public BaseException {};
  virtual void f() throw(DerivedException) {
    throw DerivedException();
  }
  virtual void g() throw(BaseException) {
    throw BaseException();
  }
};
 
class Derived : public Base {
public:
  void f() throw(BaseException) {
    throw BaseException();
  }
  virtual void g() throw(DerivedException) {
    throw DerivedException();
  }
}; ///:~

A compiler should flag the override of Derived::f( ) with an error (or at least a warning) since it changes its exception specification in a way that violates the specification of Base::f( ). The specification for Derived::g( ) is acceptable because DerivedException “is-a” BaseException (not the other way around). You can think of Base/Derived and BaseException/DerivedException as parallel class hierarchies; when you are in Derived, you can replace references to BaseException in exception specifications and return values with DerivedException. This behavior is called covariance (since both sets of classes vary down their respective hierarchies together). (Reminder from Volume 1: parameter types are not covariant—you are not allowed to change the signature of an overridden virtual function.)

If you peruse the function declarations throughout the Standard C++ library, you'll find that not a single exception specification occurs anywhere! Although this might seem strange, there is a good reason for this seeming incongruity: the library consists mainly of templates, and you never know what a generic type or function might do. For example, suppose you are developing a generic stack template and attempt to affix an exception specification to your pop function, like this:

T pop() throw(logic_error);

Since the only error you anticipate is a stack underflow, you might think it's safe to specify a logic_error or some other appropriate exception type. But type T's copy constructor could throw an exception. Then unexpected( ) would be called, and your program would terminate. You can't make unsupportable guarantees. If you don't know what exceptions might occur, don't use exception specifications. That's why template classes, which constitute the majority of the Standard C++ library, do not use exception specifications—they specify the exceptions they know about in documentation and leave the rest to you. Exception specifications are mainly for non-template classes.

Exceptions aren't the answer to all problems; overuse can cause trouble. The following sections point out situations where exceptions are not warranted. The best advice for deciding when to use exceptions is to throw exceptions only when a function fails to meet its specification.

Not for asynchronous events

The Standard C signal( )system and any similar system handle asynchronous events: events that happen outside the flow of a program, and thus events the program cannot anticipate. You cannot use C++ exceptions to handle asynchronous events because the exception and its handler are on the same call stack. That is, exceptions rely on the dynamic chain of function calls on the program's runtime stack (they have “dynamic scope”), whereas asynchronous events must be handled by completely separate code that is not part of the normal program flow (typically, interrupt service routines or event loops). Don't throw exceptions from interrupt handlers.

This is not to say that asynchronous events cannot be associated with exceptions. But the interrupt handler should do its job as quickly as possible and then return. The typical way to handle this situation is to set a flag in the interrupt handler, and check it synchronously in the mainline code.

Not for benign error conditions

If you have enough information to handle an error, it's not an exception. Take care of it in the current context rather than throwing an exception to a larger context.

Also, C++ exceptions are not thrown for machine-level events such as divide-by-zero.(9) It's assumed that some other mechanism, such as the operating system or hardware, deals with these events. In this way, C++ exceptions can be reasonably efficient, and their use is isolated to program-level exceptional conditions.

Not for flow-of-control

An exception looks somewhat like an alternate return mechanism and somewhat like a switch statement, so you might be tempted to use an exception instead of these ordinary language mechanisms. This is a bad idea, partly because the exception-handling system is significantly less efficient than normal program execution. Exceptions are a rare event, so the normal program shouldn't pay for them. Also, exceptions from anything other than error conditions are quite confusing to the user of your class or function.

You're not forced to use exceptions

Some programs are quite simple (small utilities, for example). You might only need to take input and perform some processing. In these programs, you might attempt to allocate memory and fail, try to open a file and fail, and so on. It is acceptable in these programs to display a message and exit the program, allowing the system to clean up the mess, rather than to work hard to catch all exceptions and recover all the resources yourself. Basically, if you don't need exceptions, you're not forced to use them.

New exceptions, old code

Another situation that arises is the modification of an existing program that doesn't use exceptions. You might introduce a library that does use exceptions and wonder if you need to modify all your code throughout the program. Assuming you have an acceptable error-handling scheme already in place, the most straightforward thing to do is surround the largest block that uses the new library (this might be all the code in main( ))with a try block, followed by a catch(...) and basic error message). You can refine this to whatever degree necessary by adding more specific handlers, but, in any case, the code you must add can be minimal. It's even better to isolate your exception-generating code in a try block and write handlers to convert the exceptions into your existing error-handling scheme.

It's truly important to think about exceptions when you're creating a library for someone else to use, especially if you can't know how they need to respond to critical error conditions (recall the earlier discussions on exception safety and why there are no exception specifications in the Standard C++ Library).

Do use exceptions to do the following:

• Fix the problem and retry the function that caused the exception.
• Patch things up and continue without retrying the function.
• Do whatever you can in the current context and rethrow the same exception to a higher context.
• Do whatever you can in the current context and throw a different exception to a higher context.
• Terminate the program.
• Wrap functions (especially C library functions) that use ordinary error schemes so they produce exceptions instead.
• Simplify. If your error handling scheme makes things more complicated, it is painful and annoying to use. Exceptions can be used to make error handling simpler and more effective.
• Make your library and program safer. This is a short-term investment (for debugging) and a long-term investment (for application robustness).

When to use exception specifications

The exception specification is like a function prototype: it tells the user to write exception-handling code and what exceptions to handle. It tells the compiler the exceptions that might come out of this function so that it can detect violations at runtime.

You can't always look at the code and anticipate which exceptions will arise from a particular function. Sometimes, the functions it calls produce an unexpected exception, and sometimes an old function that didn't throw an exception is replaced with a new one that does, and you get a call to unexpected( ). Any time you use exception specifications or call functions that do, consider creating your own unexpected( ) function that logs a message and then either throws an exception or aborts the program.

As we explained earlier, you should avoid using exception specifications in template classes, since you can't anticipate what types of exceptions the template parameter classes might throw.

Start with standard exceptions

Check out the Standard C++ library exceptions before creating your own. If a standard exception does what you need, chances are it's a lot easier for your user to understand and handle.

If the exception type you want isn't part of the standard library, try to inherit one from an existing standard exception. It's nice if your users can always write their code to expect the what( ) function defined in the exception( ) class interface.

Nest your own exceptions

If you create exceptions for your particular class, it's a good idea to nest the exception classes either inside your class or inside a namespace containing your class, to provide a clear message to the reader that this exception is only for your class. In addition, it prevents pollution of the global namespace.

You can nest your exceptions even if you're deriving them from C++ Standard exceptions.

Use exception hierarchies

Using exception hierarchies is a valuable way to classify the types of critical errors that might be encountered with your class or library. This gives helpful information to users, assists them in organizing their code, and gives them the option of ignoring all the specific types of exceptions and just catching the base-class type. Also, any exceptions added later by inheriting from the same base class will not force all existing code to be rewritten—the base-class handler will catch the new exception.

The Standard C++ exceptions are a good example of an exception hierarchy. Build your exceptions on top of it if you can.

Multiple inheritance (MI)

As you'll read in Chapter 9, the only essential place for MI is if you need to upcast an object pointer to two different base classes—that is, if you need polymorphic behavior with both of those base classes. It turns out that exception hierarchies are useful places for multiple inheritance because a base-class handler from any of the roots of the multiply inherited exception class can handle the exception.

Catch by reference, not by value

As you saw in the section “Exception matching,” you should catch exceptions by reference for two reasons:

• To avoid making a needless copy of the exception object when it is passed to the handler.
• To avoid object slicing when catching a derived exception as a base class object.

Although you can also throw and catch pointers, by doing so you introduce more coupling—the thrower and the catcher must agree on how the exception object is allocated and cleaned up. This is a problem because the exception itself might have occurred from heap exhaustion. If you throw exception objects, the exception-handling system takes care of all storage.

Throw exceptions in constructors

Because a constructor has no return value, you've previously had two ways to report an error during construction:

• Set a nonlocal flag and hope the user checks it.
• Return an incompletely created object and hope the user checks it.

This problem is serious because C programmers expect that object creation is always successful, which is not unreasonable in C because the types are so primitive. But continuing execution after construction fails in a C++ program is a guaranteed disaster, so constructors are one of the most important places to throw exceptions—now you have a safe, effective way to handle constructor errors. However, you must also pay attention to pointers inside objects and the way cleanup occurs when an exception is thrown inside a constructor.

Don't cause exceptions in destructors

Because destructors are called in the process of throwing other exceptions, you'll never want to throw an exception in a destructor or cause another exception to be thrown by some action you perform in the destructor. If this happens, a new exception can be thrown before the catch-clause for an existing exception is reached, which will cause a call to terminate( ).

If you call any functions inside a destructor that can throw exceptions, those calls should be within a try block in the destructor, and the destructor must handle all exceptions itself. None must escape from the destructor.

Avoid naked pointers

See Wrapped.cpp earlier in this chapter. A naked pointer usually means vulnerability in the constructor if resources are allocated for that pointer. A pointer doesn't have a destructor, so those resources aren't released if an exception is thrown in the constructor. Use auto_ptr or other smart pointer types(10) for pointers that reference heap memory.

So what does a unit test look like? Too often developers just use some well-behaved input to produce some expected output, which they inspect visually. Two dangers exist in this approach. First, programs don't always receive only well-behaved input. We all know that we should test the boundaries of program input, but it's hard to think about this when you're trying to just get things working. If you write the test for a function first before you start coding, you can wear your “tester hat” and ask yourself, “What could possibly make this break?” Code a test that will prove the function you'll write isn't broken, and then put on your developer hat and make it happen. You'll write better code than if you hadn't written the test first.

The second danger is that inspecting output visually is tedious and error prone. Most any such thing a human can do a computer can do, but without human error. It's better to formulate tests as collections of Boolean expressions and have a test program report any failures.

For example, suppose you need to build a Date class that has the following properties:

• A date can be initialized with a string (YYYYMMDD), three integers (Y, M, D), or nothing (giving today's date).
• A date object can yield its year, month, and day or a string of the form “YYYYMMDD”.
• All relational comparisons are available, as well as computing the duration between two dates (in years, months, and days).
• Dates to be compared need to be able to span an arbitrary number of centuries (for example, 1600-2200).

Your class can store three integers representing the year, month, and day. (Just be sure the year is at least 16 bits in size to satisfy the last bulleted item.) The interface for your Date class might look like this:

//: C02:Date1.h
// A first pass at Date.h.
#ifndef DATE1_H
#define DATE1_H
#include <string>
 
class Date {
public:
  // A struct to hold elapsed time:
  struct Duration {
    int years;
    int months;
    int days;
    Duration(int y, int m, int d)
    : years(y), months(m), days(d) {}
  };
  Date();
  Date(int year, int month, int day);
  Date(const std::string&);
  int getYear() const;
  int getMonth() const;
  int getDay() const;
  std::string toString() const;
friend bool operator<(const
Date&, const Date&);
friend bool operator>(const
Date&, const Date&);
friend bool operator<=(const
Date&, const Date&);
friend bool operator>=(const
Date&, const Date&);
friend bool operator==(const
Date&, const Date&);
friend bool operator!=(const
Date&, const Date&);
  friend Duration duration(const Date&, const
Date&);
};
#endif // DATE1_H ///:~

Before you implement this class, you can solidify your grasp of the requirements by writing the beginnings of a test program. You might come up with something like the following:

//: C02:SimpleDateTest.cpp
//{L} Date
#include <iostream>
#include "Date.h" // From Appendix B
using namespace std;
 
// Test machinery
int nPass = 0, nFail = 0;
void test(bool t) { if(t) nPass++; else nFail++; }
 
int main() {
  Date mybday(1951, 10, 1);
  test(mybday.getYear() == 1951);
  test(mybday.getMonth() == 10);
  test(mybday.getDay() == 1);
  cout << "Passed: " << nPass
<< ", Failed: "
       << nFail << endl;
}
/* Expected output:
Passed: 3, Failed: 0
*/ ///:~

In this trivial case, the function test( ) maintains the global variables nPass and nFail. The only visual inspection you do is to read the final score. If a test failed, a more sophisticated test( ) displays an appropriate message. The framework described later in this chapter has such a test function, among other things.

You can now implement enough of the Date class to get these tests to pass, and then you can proceed iteratively until all the requirements are met. By writing tests first, you are more likely to think of corner cases that might break your upcoming implementation, and you're more likely to write the code correctly the first time. Such an exercise might produce the following version of a test for the Date class:

//: C02:SimpleDateTest2.cpp
//{L} Date
#include <iostream>
#include "Date.h"
using namespace std;
 
// Test machinery
int nPass = 0, nFail = 0;
void test(bool t) { if(t) ++nPass; else ++nFail; }
 
int main() {
  Date mybday(1951, 10, 1);
  Date today;
Date
myevebday("19510930");
 
  // Test the operators
  test(mybday < today);
  test(mybday <= today);
  test(mybday != today);
  test(mybday == mybday);
  test(mybday >= mybday);
  test(mybday <= mybday);
  test(myevebday < mybday);
  test(mybday > myevebday);
  test(mybday >= myevebday);
  test(mybday != myevebday);
 
  // Test the functions
  test(mybday.getYear() == 1951);
  test(mybday.getMonth() == 10);
  test(mybday.getDay() == 1);
  test(myevebday.getYear() == 1951);
  test(myevebday.getMonth() == 9);
  test(myevebday.getDay() == 30);
  test(mybday.toString() == "19511001");
  test(myevebday.toString() == "19510930");
 
  // Test duration
  Date d2(2003, 7, 4);
  Date::Duration dur = duration(mybday, d2);
  test(dur.years == 51);
  test(dur.months == 9);
  test(dur.days == 3);
 
  // Report results:
  cout << "Passed: " << nPass
<< ", Failed: "
       << nFail << endl;
} ///:~

This test can be more fully developed. For example, we haven't tested that long durations are handled correctly. We'll stop here, but you get the idea. The full implementation for the Date class is available in the files Date.h and Date.cpp in the appendix.(23)

Some automated C++ unit test tools are available on the World Wide Web for download, such as CppUnit.(24) Our purpose here is not only to present a test mechanism that is easy to use, but also easy to understand internally and even modify if necessary. So, in the spirit of “Do The Simplest Thing That Could Possibly Work,”(25) we have developed the TestSuite Framework, a namespace named TestSuite that contains two key classes: Test and Suite.

The Test class is an abstract base class from which you derive a test object. It keeps track of the number of passes and failures and displays the text of any test condition that fails. You simply to override the run( ) member function, which should in turn call the test_( ) macro for each Boolean test condition you define.

To define a test for the Date class using the framework, you can inherit from Test as shown in the following program:

//: C02:DateTest.h
#ifndef DATETEST_H
#define DATETEST_H
#include "Date.h"
#include "../TestSuite/Test.h"
 
class DateTest : public TestSuite::Test {
  Date mybday;
  Date today;
  Date myevebday;
public:
  DateTest(): mybday(1951, 10, 1),
myevebday("19510930") {}
  void run() {
    testOps();
    testFunctions();
    testDuration();
  }
  void testOps() {
    test_(mybday < today);
    test_(mybday <= today);
    test_(mybday != today);
    test_(mybday == mybday);
    test_(mybday >= mybday);
    test_(mybday <= mybday);
    test_(myevebday < mybday);
    test_(mybday > myevebday);
    test_(mybday >= myevebday);
    test_(mybday != myevebday);
  }
  void testFunctions() {
    test_(mybday.getYear() == 1951);
    test_(mybday.getMonth() == 10);
    test_(mybday.getDay() == 1);
    test_(myevebday.getYear() == 1951);
    test_(myevebday.getMonth() == 9);
    test_(myevebday.getDay() == 30);
    test_(mybday.toString() == "19511001");
    test_(myevebday.toString() ==
"19510930");
  }
  void testDuration() {
    Date d2(2003, 7, 4);
    Date::Duration dur = duration(mybday, d2);
    test_(dur.years == 51);
    test_(dur.months == 9);
    test_(dur.days == 3);
  }
};
#endif // DATETEST_H ///:~

Running the test is a simple matter of instantiating a DateTest object and calling its run( ) member function:

//: C02:DateTest.cpp
// Automated testing (with a framework).
//{L} Date ../TestSuite/Test
#include <iostream>
#include "DateTest.h"
using namespace std;
 
int main() {
  DateTest test;
  test.run();
  return test.report();
}
/* Output:
Test "DateTest":
        Passed: 21,      Failed: 0
*/ ///:~

The Test::report( ) function displays the previous output and returns the number of failures, so it is suitable to use as a return value from main( ).

The Test class uses RTTI(26) to get the name of your class (for example, DateTest) for the report. There is also a setStream( ) member function if you want the test results sent to a file instead of to the standard output (the default). You'll see the Test class implementation later in this chapter.

The test_( ) macro can extract the text of the Boolean condition that fails, along with its file name and line number.(27) To see what happens when a failure occurs, you can introduce an intentional error in the code, for example by reversing the condition in the first call to test_( ) in DateTest::testOps( ) in the previous example code. The output indicates exactly what test was in error and where it happened:

DateTest failure: (mybday > today) , DateTest.h
(line 31)
Test "DateTest":
        Passed: 20      Failed: 1

In addition to test_( ), the framework includes the functions succeed_( ) and fail_( ), for cases where a Boolean test won't do. These functions apply when the class you're testing might throw exceptions. During testing, create an input set that will cause the exception to occur. If it doesn't, it's an error and you call fail_( ) explicitly to display a message and update the failure count. If it does throw the exception as expected, you call succeed_( ) to update the success count.

To illustrate, suppose we modify the specification of the two non-default Date constructors to throw a DateError exception (a type nested inside Date and derived from std::logic_error) if the input parameters do not represent a valid date:

Date(const string& s) throw(DateError);
Date(int year, int month, int day) throw(DateError);

The DateTest::run( ) member function can now call the following function to test the exception handling:

  void testExceptions() {
    try {
      Date d(0,0,0);  // Invalid
      fail_("Invalid date undetected in Date int
ctor");
    } catch(Date::DateError&) {
      succeed_();
    }
    try {
      Date d("");  // Invalid
      fail_("Invalid date undetected in Date
string ctor");
    } catch(Date::DateError&) {
      succeed_();
    }
  }

In both cases, if an exception is not thrown, it is an error. Notice that you must manually pass a message to fail_( ), since no Boolean expression is being evaluated.

Real projects usually contain many classes, so you need a way to group tests so that you can just push a single button to test the entire project.(28) The Suite class collects tests into a functional unit. You add Test objects to a Suite with the addTest( ) member function, or you can include an entire existing suite with addSuite( ). To illustrate, the following example collects the programs in Chapter 3 that use the Test class into a single suite. Note that this file will appear in the Chapter 3 subdirectory:

//: C03:StringSuite.cpp
//{L} ../TestSuite/Test
../TestSuite/Suite
//{L} TrimTest
// Illustrates a test suite
for code from Chapter 3
#include <iostream>
#include
"../TestSuite/Suite.h"
#include
"StringStorage.h"
#include "Sieve.h"
#include "Find.h"
#include "Rparse.h"
#include
"TrimTest.h"
#include "CompStr.h"
using namespace std;
using namespace TestSuite;
 
int main() {
    Suite suite("String
Tests");
    suite.addTest(new
StringStorageTest);
    suite.addTest(new
SieveTest);
    suite.addTest(new
FindTest);
    suite.addTest(new
RparseTest);
    suite.addTest(new TrimTest);
    suite.addTest(new
CompStrTest);
    suite.run();
    long nFail =
suite.report();
    suite.free();
    return nFail;
}
/* Output:
s1 = 62345
s2 = 12345
Suite "String Tests"
====================
Test
"StringStorageTest":
   Passed: 2   Failed: 0
Test "SieveTest":
   Passed: 50  Failed: 0
Test "FindTest":
   Passed: 9   Failed: 0
Test "RparseTest":
   Passed: 8   Failed: 0
Test "TrimTest":
   Passed: 11  Failed: 0
Test "CompStrTest":
   Passed: 8   Failed: 0
*/ ///:~

Five of the above tests are completely contained in header files. TrimTest is not, because it contains static data that must be defined in an implementation file. The two first two output lines are trace lines from the StringStorage test. You must give the suite a name as a constructor argument. The Suite::run( ) member function calls Test::run( ) for each of its contained tests. Much the same thing happens for Suite::report( ), except that you can send the individual test reports to a different destination stream than that of the suite report. If the test passed to addSuite( ) already has a stream pointer assigned, it keeps it. Otherwise, it gets its stream from the Suite object. (As with Test, there is an optional second argument to the suite constructor that defaults to std::cout.) The destructor for Suite does not automatically delete the contained Test pointers because they don't need to reside on the heap; that's the job of Suite::free( ).

The test framework code is in a subdirectory called TestSuite in the code distribution available at www.MindView.net. To use it, include the search path for the TestSuite subdirectory in your header, link the object files, and include the TestSuite subdirectory in the library search path. Here is the header for Test.h:

//: TestSuite:Test.h
#ifndef TEST_H
#define TEST_H
#include <string>
#include <iostream>
#include <cassert>
using std::string;
using std::ostream;
using std::cout;
 
// fail_() has an underscore to prevent collision with
// ios::fail(). For consistency, test_() and succeed_()
// also have underscores.
 
#define test_(cond) \
  do_test(cond, #cond, __FILE__, __LINE__)
#define fail_(str) \
  do_fail(str, __FILE__, __LINE__)
 
namespace TestSuite {
 
class Test {
  ostream* osptr;
  long nPass;
  long nFail;
  // Disallowed:
  Test(const Test&);
  Test& operator=(const Test&);
protected:
  void do_test(bool cond, const string& lbl,
    const char* fname, long lineno);
  void do_fail(const string& lbl,
    const char* fname, long lineno);
public:
  Test(ostream* osptr = &cout) {
    this->osptr = osptr;
    nPass = nFail = 0;
  }
  virtual ~Test() {}
  virtual void run() = 0;
  long getNumPassed() const { return nPass; }
  long getNumFailed() const { return nFail; }
  const ostream* getStream() const { return osptr; }
  void setStream(ostream* osptr) { this->osptr =
osptr; }
  void succeed_() { ++nPass; }
  long report() const;
  virtual void reset() { nPass = nFail = 0; }
};
 
} // namespace TestSuite
#endif // TEST_H ///:~

There are three virtual functions in the Test class:

• A virtual destructor
• The function reset( )
• The pure virtual function run( )

As explained in Volume 1, it is an error to delete a derived heap object through a base pointer unless the base class has a virtual destructor. Any class intended to be a base class (usually evidenced by the presence of at least one other virtual function) should have a virtual destructor. The default implementation of the Test::reset( ) resets the success and failure counters to zero. You might want to override this function to reset the state of the data in your derived test object; just be sure to call Test::reset( ) explicitly in your override so that the counters are reset. The Test::run( ) member function is pure virtual since you are required to override it in your derived class.

The test_( ) and fail_( ) macros can include file name and line number information available from the preprocessor. We originally omitted the trailing underscores in the names, but the fail( ) macro then collided with ios::fail( ), causing compiler errors.

Here is the implementation of the remainder of the Test functions:

//: TestSuite:Test.cpp {O}
#include "Test.h"
#include <iostream>
#include <typeinfo>
using namespace std;
using namespace TestSuite;
 
void Test::do_test(bool cond, const std::string&
lbl,
  const char* fname, long lineno) {
  if(!cond)
    do_fail(lbl, fname, lineno);
  else
    succeed_();
}
 
void Test::do_fail(const std::string& lbl,
  const char* fname, long lineno) {
  ++nFail;
  if(osptr) {
    *osptr << typeid(*this).name()
           << "failure: (" << lbl
<< ") , " << fname
           << " (line " << lineno
<< ")" << endl;
  }
}
 
long Test::report() const {
  if(osptr) {
    *osptr << "Test \"" <<
typeid(*this).name()
           << "\":\n\tPassed: "
<< nPass
           << "\tFailed: " <<
nFail
           << endl;
  }
  return nFail;
} ///:~

The Test class keeps track of the number of successes and failures as well as the stream where you want Test::report( ) to display the results. The test_( ) and fail_( ) macros extract the current file name and line number information from the preprocessor and pass the file name to do_test( ) and the line number to do_fail( ), which do the actual work of displaying a message and updating the appropriate counter. We can't think of a good reason to allow copy and assignment of test objects, so we have disallowed these operations by making their prototypes private and omitting their respective function bodies.

Here is the header file for Suite:

//: TestSuite:Suite.h
#ifndef SUITE_H
#define SUITE_H
#include <vector>
#include <stdexcept>
#include "../TestSuite/Test.h"
using std::vector;
using std::logic_error;
 
namespace TestSuite {
 
class TestSuiteError : public logic_error {
public:
  TestSuiteError(const string& s = "")
  : logic_error(s) {}
};
 
class Suite {
  string name;
  ostream* osptr;
  vector<Test*> tests;
  void reset();
  // Disallowed ops:
  Suite(const Suite&);
  Suite& operator=(const Suite&);
public:
  Suite(const string& name, ostream* osptr =
&cout)
  : name(name) { this->osptr = osptr; }
  string getName() const { return name; }
  long getNumPassed() const;
  long getNumFailed() const;
  const ostream* getStream() const { return osptr; }
  void setStream(ostream* osptr) { this->osptr =
osptr; }
  void addTest(Test* t) throw(TestSuiteError);
  void addSuite(const Suite&);
  void run();  // Calls Test::run() repeatedly
  long report() const;
  void free();  // Deletes tests
};
 
} // namespace TestSuite
#endif // SUITE_H ///:~

The Suite class holds pointers to its Test objects in a vector. Notice the exception specification on the addTest( ) member function. When you add a test to a suite, Suite::addTest( ) verifies that the pointer you pass is not null; if it is null, it throws a TestSuiteError exception. Since this makes it impossible to add a null pointer to a suite, addSuite( ) asserts this condition on each of its tests, as do the other functions that traverse the vector of tests (see the following implementation). Copy and assignment are disallowed as they are in the Test class.

//: TestSuite:Suite.cpp {O}
#include "Suite.h"
#include <iostream>
#include <cassert>
#include <cstddef>
using namespace std;
using namespace TestSuite;
 
void Suite::addTest(Test* t) throw(TestSuiteError) {
  // Verify test is valid and has a stream:
  if(t == 0)
    throw TestSuiteError("Null test in
Suite::addTest");
  else if(osptr && !t->getStream())
    t->setStream(osptr);
  tests.push_back(t);
  t->reset();
}
 
void Suite::addSuite(const Suite& s) {
for(size_t i = 0; i <
s.tests.size(); ++i) {
  assert(tests[i]);
addTest(s.tests[i]);
  }
}
 
void Suite::free() {
  for(size_t i = 0; i < tests.size(); ++i) {
    delete tests[i];
    tests[i] = 0;
  }
}
 
void Suite::run() {
  reset();
  for(size_t i = 0; i < tests.size(); ++i) {
    assert(tests[i]);
    tests[i]->run();
  }
}
 
long Suite::report() const {
  if(osptr) {
    long totFail = 0;
    *osptr << "Suite \"" <<
name
             << "\"\n=======";
    size_t i;
    for(i = 0; i < name.size(); ++i)
      *osptr << '=';
    *osptr << "="
<< endl;
    for(i = 0; i <
tests.size(); ++i) {
      assert(tests[i]);
      totFail += tests[i]->report();
    }
    *osptr << "=======";
    for(i = 0; i < name.size(); ++i)
      *osptr << '=';
    *osptr << "="
<< endl;
    return totFail;
  }
  else
    return getNumFailed();
}
 
long Suite::getNumPassed() const {
  long totPass = 0;
  for(size_t i = 0; i < tests.size(); ++i) {
    assert(tests[i]);
    totPass += tests[i]->getNumPassed();
  }
  return totPass;
}
 
long Suite::getNumFailed() const {
  long totFail = 0;
  for(size_t i = 0; i < tests.size(); ++i) {
    assert(tests[i]);
    totFail += tests[i]->getNumFailed();
  }
  return totFail;
}
 
void Suite::reset() {
  for(size_t i = 0; i < tests.size(); ++i) {
    assert(tests[i]);
    tests[i]->reset();
  }
} ///:~

We will be using the TestSuite framework wherever it applies throughout the rest of this book.

Sometimes it's useful to print the code of each statement as it is executed, either to cout or to a trace file. Here's a preprocessor macro to accomplish this:

#define TRACE(ARG) cout << #ARG << endl; ARG

Now you can go through and surround the statements you trace with this macro. However, this can introduce problems. For example, if you take the statement:

for(int i = 0; i < 100; i++)
  cout << i << endl;

and put both lines inside TRACE( ) macros, you get this:

TRACE(for(int i = 0; i < 100; i++))
TRACE(  cout << i << endl;)

which expands to this:

cout << "for(int i = 0; i < 100;
i++)" << endl;
for(int i = 0; i < 100; i++)
  cout << "cout << i <<
endl;" << endl;
cout << i << endl;

which isn't exactly what you want. Thus, you must use this technique carefully.

The following is a variation on the TRACE( ) macro:

#define D(a) cout << #a "=[" << a <<
"]" << endl;

If you want to display an expression, you simply put it inside a call to D( ). The expression is displayed, followed by its value (assuming there's an overloaded operator << for the result type). For example, you can say D(a + b). You can use this macro any time you want to check an intermediate value.

These two macros represent the two most fundamental things you do with a debugger: trace through the code execution and display values. A good debugger is an excellent productivity tool, but sometimes debuggers are not available, or it's not convenient to use them. These techniques always work, regardless of the situation.

DISCLAIMER: This section and the next contain code which is officially unsanctioned by the C++ Standard. In particular, we redefine cout and new via macros, which can cause surprising results if you're not careful. Our examples work on all the compilers we use, however, and provide useful information. This is the only place in this book where we will depart from the sanctity of standard-compliant coding practice. Use at your own risk! Note that in order for this to work, a using-declaration must be used, so that cout isn't prefixed by its namespace, i.e. std::cout will not work.

The following code easily creates a trace file and sends all the output that would normally go to cout into that file. All you must do is #define TRACEON and include the header file (of course, it's fairly easy just to write the two key lines right into your file):

//: C03:Trace.h
// Creating a trace file.
#ifndef TRACE_H
#define TRACE_H
#include <fstream>
 
#ifdef TRACEON
std::ofstream TRACEFILE__("TRACE.OUT");
#define cout TRACEFILE__
#endif
 
#endif // TRACE_H ///:~

Here's a simple test of the previous file:

//: C03:Tracetst.cpp {-bor}
#include <iostream>
#include <fstream>
#include "../require.h"
using namespace std;
 
#define TRACEON
#include "Trace.h"
 
int main() {
  ifstream
f("Tracetst.cpp");
  assure(f, "Tracetst.cpp");
  cout << f.rdbuf(); // Dumps file contents to
file
} ///:~

Because cout has been textually turned into something else by Trace.h, all the cout statements in your program now send information to the trace file. This is a convenient way of capturing your output into a file, in case your operating system doesn't make output redirection easy.

The following straightforward debugging techniques are explained in Volume 1:

1.  For array bounds checking, use the Array template in C16:Array3.cpp of Volume 1 for all arrays. You can turn off the checking and increase efficiency when you're ready to ship. (Although this doesn't deal with the case of taking a pointer to an array.)

2.  Check for non-virtual destructors in base classes.

Tracking new/delete and malloc/free

Common problems with memory allocation include mistakenly calling delete for memory that's not on the free store, deleting the free store more than once, and, most often, forgetting to delete a pointer. This section discusses a system that can help you track down these kinds of problems.

As an additional disclaimer beyond that of the preceding section: because of the way we overload new, the following technique may not work on all platforms, and will only work for programs that do not call the function operator new( ) explicitly. We have been quite careful in this book to only present code that fully conforms to the C++ Standard, but in this one instance we're making an exception for the following reasons:

1.  Even though it's technically illegal, it works on many compilers.(29)

2.  We illustrate some useful thinking along the way.

To use the memory checking system, you simply include the header file MemCheck.h, link the MemCheck.obj file into your application to intercept all the calls to new and delete, and call the macro MEM_ON( ) (explained later in this section) to initiate memory tracing. A trace of all allocations and deallocations is printed to the standard output (via stdout). When you use this system, all calls to new store information about the file and line where they were called. This is accomplished by using the placement syntax for operator new.(30) Although you typically use the placement syntax when you need to place objects at a specific point in memory, it can also create an operator new( ) with any number of arguments. This is used in the following example to store the results of the __FILE__ and __LINE__ macros whenever new is called:

//: C02:MemCheck.h
#ifndef MEMCHECK_H
#define MEMCHECK_H
#include <cstddef>  // For size_t
 
// Usurp the new operator (both scalar and array
versions)
void* operator new(std::size_t, const char*, long);
void* operator new[](std::size_t, const char*, long);
#define new new (__FILE__, __LINE__)
 
extern bool traceFlag;
#define TRACE_ON() traceFlag = true
#define TRACE_OFF() traceFlag = false
 
extern bool activeFlag;
#define MEM_ON() activeFlag = true
#define MEM_OFF() activeFlag = false
 
#endif // MEMCHECK_H ///:~

It is important to include this file in any source file in which you want to track free store activity, but include it last (after your other #include directives). Most headers in the standard library are templates, and since most compilers use the inclusion model of template compilation (meaning all source code is in the headers), the macro that replaces new in MemCheck.h would usurp all instances of the new operator in the library source code (and would likely result in compile errors). Besides, you are only interested in tracking your own memory errors, not the library's.

In the following file, which contains the memory tracking implementation, everything is done with C standard I/O rather than with C++ iostreams. It shouldn't make a difference, since we're not interfering with iostreams' use of the free store, but when we tried it, some compilers complained. All compilers were happy with the <cstdio> version.

//: C02:MemCheck.cpp {O}
#include <cstdio>
#include <cstdlib>
#include <cassert>
#include <cstddef>
using namespace std;
#undef new
 
// Global flags set by macros in MemCheck.h
bool traceFlag = true;
bool activeFlag = false;
 
namespace {
 
// Memory map entry type
struct Info {
  void* ptr;
  const char* file;
  long line;
};
 
// Memory map data
const size_t MAXPTRS = 10000u;
Info memMap[MAXPTRS];
size_t nptrs = 0;
 
// Searches the map for an address
int findPtr(void* p) {
  for(size_t i = 0; i < nptrs; ++i)
    if(memMap[i].ptr == p)
      return i;
  return -1;
}
 
void delPtr(void* p) {
  int pos = findPtr(p);
  assert(pos >= 0);
  // Remove pointer from map
  for(size_t i = pos; i < nptrs-1; ++i)
    memMap[i] = memMap[i+1];
  --nptrs;
}
 
// Dummy type for static destructor
struct Sentinel {
  ~Sentinel() {
    if(nptrs > 0) {
      printf("Leaked memory at:\n");
      for(size_t i = 0; i < nptrs; ++i)
        printf("\t%p (file: %s, line %ld)\n",
          memMap[i].ptr, memMap[i].file,
memMap[i].line);
    }
    else
      printf("No user memory leaks!\n");
  }
};
 
// Static dummy object
Sentinel s;
 
} // End anonymous namespace
 
// Overload scalar new
void*
operator new(size_t siz, const char* file, long line) {
  void* p = malloc(siz);
  if(activeFlag) {
    if(nptrs == MAXPTRS) {
      printf("memory map too small (increase
MAXPTRS)\n");
      exit(1);
    }
    memMap[nptrs].ptr = p;
    memMap[nptrs].file = file;
    memMap[nptrs].line = line;
    ++nptrs;
  }
  if(traceFlag) {
    printf("Allocated %u bytes at address %p
", siz, p);
    printf("(file: %s, line: %ld)\n", file,
line);
  }
  return p;
}
 
// Overload array new
void*
operator new[](size_t siz, const
char* file, long line) {
  return operator new(siz, file, line);
}
 
// Override scalar delete
void operator delete(void* p) {
  if(findPtr(p) >= 0) {
    free(p);
    assert(nptrs > 0);
    delPtr(p);
    if(traceFlag)
      printf("Deleted memory at address
%p\n", p);
  }
  else if(!p && activeFlag)
    printf("Attempt to delete unknown pointer:
%p\n", p);
}
 
// Override array delete
void operator delete[](void* p) {
  operator delete(p);
} ///:~

The Boolean flags traceFlag and activeFlag are global, so they can be modified in your code by the macros TRACE_ON( ), TRACE_OFF( ), MEM_ON( ), and MEM_OFF( ). In general, enclose all the code in your main( ) within a MEM_ON( )-MEM_OFF( ) pair so that memory is always tracked. Tracing, which echoes the activity of the replacement functions for operator new( ) and operator delete( ), is on by default, but you can turn it off with TRACE_OFF( ). In any case, the final results are always printed (see the test runs later in this chapter).

The MemCheck facility tracks memory by keeping all addresses allocated by operator new( ) in an array of Info structures, which also holds the file name and line number where the call to new occurred. To prevent collision with any names you have placed in the global namespace, as much information as possible is kept inside the anonymous namespace. The Sentinel class exists solely to call a static object destructor as the program shuts down. This destructor inspects memMap to see if any pointers are waiting to be deleted (indicating a memory leak).

Our operator new( ) uses malloc( ) to get memory, and then adds the pointer and its associated file information to memMap. The operator delete( ) function undoes all that work by calling free( ) and decrementing nptrs, but first it checks to see if the pointer in question is in the map in the first place. If it isn't, either you're trying to delete an address that isn't on the free store, or you're trying to delete one that's already been deleted and removed from the map. The activeFlag variable is important here because we don't want to process any deallocations from any system shutdown activity. By calling MEM_OFF( ) at the end of your code, activeFlag will be set to false, and such subsequent calls to delete will be ignored. (That's bad in a real program, but our purpose here is to find your leaks; we're not debugging the library.) For simplicity, we forward all work for array new and delete to their scalar counterparts.

The following is a simple test using the MemCheck facility:

//: C02:MemTest.cpp
//{L} MemCheck
// Test of MemCheck system.
#include <iostream>
#include <vector>
#include <cstring>
#include "MemCheck.h"   // Must appear last!
using namespace std;
 
class Foo {
  char* s;
public:
  Foo(const char*s ) {
    this->s = new char[strlen(s) + 1];
    strcpy(this->s, s);
  }
  ~Foo() { delete [] s; }
};
 
int main() {
  MEM_ON();
  cout << "hello" << endl;
  int* p = new int;
  delete p;
  int* q = new int[3];
  delete [] q;
  int* r;
  delete r;
  vector<int> v;
  v.push_back(1);
  Foo s("goodbye");
  MEM_OFF();
} ///:~

This example verifies that you can use MemCheck in the presence of streams, standard containers, and classes that allocate memory in constructors. The pointers p and q are allocated and deallocated without any problem, but r is not a valid heap pointer, so the output indicates the error as an attempt to delete an unknown pointer:

hello
Allocated 4 bytes at address 0xa010778 (file:
memtest.cpp, line: 25)
Deleted memory at address 0xa010778
Allocated 12 bytes at address 0xa010778 (file:
memtest.cpp, line: 27)
Deleted memory at address 0xa010778
Attempt to delete unknown pointer: 0x1
Allocated 8 bytes at address 0xa0108c0 (file:
memtest.cpp, line: 14)
Deleted memory at address 0xa0108c0
No user memory leaks!

Because of the call to MEM_OFF( ), no subsequent calls to operator delete( ) by vector or ostream are processed. You still might get some calls to delete from reallocations performed by the containers.

If you call TRACE_OFF( ) at the beginning of the program, the output is

hello
Attempt to delete unknown pointer: 0x1
No user memory leaks!