Back to Exceptions
Continue to Item 10: Prevent resource leaks in constructors

Item 9: Use destructors to prevent resource leaks.

Say good-bye to pointers. Admit it: you never really liked them that much anyway.

Okay, you don't have to say good-bye to all pointers, but you do need to say sayonara to pointers that are used to manipulate local resources. Suppose, for example, you're writing software at the Shelter for Adorable Little Animals, an organization that finds homes for puppies and kittens. Each day the shelter creates a file containing information on the adoptions it arranged that day, and your job is to write a program to read these files and do the appropriate processing for each adoption.

A reasonable approach to this task is to define an abstract base class, `ALA` ("Adorable Little Animal"), plus concrete derived classes for puppies and kittens. A virtual function, `processAdoption`, handles the necessary species-specific processing:

    class ALA {
    public:
      virtual void processAdoption() = 0;
      ...
    };

    class Puppy: public ALA {
    public:
      virtual void processAdoption();
      ...
    };

    class Kitten: public ALA {
    public:
      virtual void processAdoption();
      ...
    };

You'll need a function that can read information from a file and produce either a `Puppy` object or a `Kitten` object, depending on the information in the file. This is a perfect job for a virtual constructor, a kind of function described in Item 25. For our purposes here, the function's declaration is all we need:

    // read animal information from s, then return a pointer
    // to a newly allocated object of the appropriate type
    ALA * readALA(istream& s);

The heart of your program is likely to be a function that looks something like this:

    void processAdoptions(istream& dataSource)
    {
      while (dataSource) {                  // while there's data
        ALA *pa = readALA(dataSource);      // get next animal
        pa->processAdoption();              // process adoption
        delete pa;                          // delete object that
      }                                     // readALA returned
    }

This function loops through the information in `dataSource`, processing each entry as it goes. The only mildly tricky thing is the need to remember to delete `pa` at the end of each iteration. This is necessary because `readALA` creates a new heap object each time it's called. Without the call to `delete`, the loop would contain a resource leak.

Now consider what would happen if `pa->processAdoption` threw an exception. `processAdoptions` fails to catch exceptions, so the exception would propagate to `processAdoptions`'s caller. In doing so, all statements in `processAdoptions` after the call to `pa->processAdoption` would be skipped, and that means `pa` would never be deleted. As a result, anytime `pa->processAdoption` throws an exception, `processAdoptions` contains a resource leak.

Plugging the leak is easy enough,

    void processAdoptions(istream& dataSource)
    {
      while (dataSource) {
        ALA *pa = readALA(dataSource);

      try {
          pa->processAdoption();
      }
      catch (...) {              // catch all exceptions

        delete pa;               // avoid resource leak when an
                                 // exception is thrown

        throw;                   // propagate exception to caller
      }

      delete pa;                 // avoid resource leak when no
     }                           // exception is thrown
    }

but then you have to litter your code with `try` and `catch` blocks. More importantly, you are forced to duplicate cleanup code that is common to both normal and exceptional paths of control. In this case, the call to `delete` must be duplicated. Like all replicated code, this is annoying to write and difficult to maintain, but it also feels wrong. Regardless of whether we leave `processAdoptions` by a normal return or by throwing an exception, we need to delete `pa`, so why should we have to say that in more than one place?

We don't have to if we can somehow move the cleanup code that must always be executed into the destructor for an object local to `processAdoptions`. That's because local objects are always destroyed when leaving a function, regardless of how that function is exited. (The only exception to this rule is when you call `longjmp`, and this shortcoming of `longjmp` is the primary reason why C++ has support for exceptions in the first place.) Our real concern, then, is moving the `delete` from `processAdoptions` into a destructor for an object local to `processAdoptions`.

The solution is to replace the pointer `pa` with an object that acts like a pointer. That way, when the pointer-like object is (automatically) destroyed, we can have its destructor call `delete`. Objects that act like pointers, but do more, are called smart pointers, and, as Item 28 explains, you can make pointer-like objects very smart indeed. In this case, we don't need a particularly brainy pointer, we just need a pointer-like object that knows enough to delete what it points to when the pointer-like object goes out of scope.

It's not difficult to write a class for such objects, but we don't need to. The standard C++ library (see Item E49) contains a class template called `auto_ptr` that does just what we want. Each `auto_ptr` class takes a pointer to a heap object in its constructor and deletes that object in its destructor. Boiled down to these essential functions, `auto_ptr` looks like this:

    template<class T>
    class auto_ptr {
    public:
      auto_ptr(T *p = 0): ptr(p) {}        // save ptr to object
      ~auto_ptr() { delete ptr; }          // delete ptr to object

    private:
      T *ptr;                              // raw ptr to object
    };

The standard version of `auto_ptr` is much fancier, and this stripped-down implementation isn't suitable for real use3 (we must add at least the copy constructor, assignment operator, and pointer-emulating functions discussed in Item 28), but the concept behind it should be clear: use `auto_ptr` objects instead of raw pointers, and you won't have to worry about heap objects not being deleted, not even when exceptions are thrown. (Because the `auto_ptr` destructor uses the single-object form of `delete`, `auto_ptr` is not suitable for use with pointers to arrays of objects. If you'd like an `auto_ptr`-like template for arrays, you'll have to write your own. In such cases, however, it's often a better design decision to use a `vector` instead of an array, anyway.)

Using an `auto_ptr` object instead of a raw pointer, `processAdoptions` looks like this:

    void processAdoptions(istream& dataSource)
    {
      while (dataSource) {
        auto_ptr<ALA> pa(readALA(dataSource));
        pa->processAdoption();
      }
    }

This version of `processAdoptions` differs from the original in only two ways. First, `pa` is declared to be an `auto_ptr<ALA>` object, not a raw `ALA*` pointer. Second, there is no `delete` statement at the end of the loop. That's it. Everything else is identical, because, except for destruction, `auto_ptr` objects act just like normal pointers. Easy, huh?

The idea behind `auto_ptr` — using an object to store a resource that needs to be automatically released and relying on that object's destructor to release it — applies to more than just pointer-based resources. Consider a function in a GUI application that needs to create a window to display some information:

    // this function may leak resources if an exception
    // is thrown
    void displayInfo(const Information& info)
    {
      WINDOW_HANDLE w(createWindow());

      display info in window corresponding to w;

      destroyWindow(w);
    }

Many window systems have C-like interfaces that use functions like `createWindow` and `destroyWindow` to acquire and release window resources. If an exception is thrown during the process of displaying `info` in `w`, the window for which `w` is a handle will be lost just as surely as any other dynamically allocated resource.

The solution is the same as it was before. Create a class whose constructor and destructor acquire and release the resource:

    // class for acquiring and releasing a window handle
    class WindowHandle {
    public:
       WindowHandle(WINDOW_HANDLE handle): w(handle) {}
      ~WindowHandle() { destroyWindow(w); }

       operator WINDOW_HANDLE() { return w; }        // see below

    private:
      WINDOW_HANDLE w;

      // The following functions are declared private to prevent
      // multiple copies of a WINDOW_HANDLE from being created.
      // See Item 28 for a discussion of a more flexible approach.
      WindowHandle(const WindowHandle&);
      WindowHandle& operator=(const WindowHandle&);
    };

This looks just like the `auto_ptr` template, except that assignment and copying are explicitly prohibited (see Item E27), and there is an implicit conversion operator that can be used to turn a `WindowHandle` into a `WINDOW_HANDLE`. This capability is essential to the practical application of a `WindowHandle` object, because it means you can use a `WindowHandle` just about anywhere you would normally use a raw `WINDOW_HANDLE`. (See Item 5, however, for why you should generally be leery of implicit type conversion operators.)

Given the `WindowHandle` class, we can rewrite `displayInfo` as follows:

    // this function avoids leaking resources if an
    // exception is thrown
    void displayInfo(const Information& info)
    {
      WindowHandle w(createWindow());

      display info in window corresponding to w;

    }

Even if an exception is thrown within `displayInfo`, the window created by `createWindow` will always be destroyed.

By adhering to the rule that resources should be encapsulated inside objects, you can usually avoid resource leaks in the presence of exceptions. But what happens if an exception is thrown while you're in the process of acquiring a resource, e.g., while you're in the constructor of a resource-acquiring class? What happens if an exception is thrown during the automatic destruction of such resources? Don't constructors and destructors call for special techniques? They do, and you can read about them in Items 10 and 11.

Back to Exceptions
Continue to Item 10: Prevent resource leaks in constructors

3 A complete version of an almost-standard `auto_ptr` appears on pages 291-294.
Return