Item 14: Think carefully about copying behavior in resource-managing classes.

For example, suppose you're using a C API to manipulate mutex objects of type Mutex offering functions lock and unlock:

void lock(Mutex *pm);               // lock mutex pointed to by pm



void unlock(Mutex *pm);             // unlock the mutex

To make sure that you never forget to unlock a Mutex you've locked, you'd like to create a class to manage locks. The basic structure of such a class is dictated by the RAII principle that resources are acquired during construction and released during destruction:

class Lock {

public:

  explicit Lock(Mutex *pm)

  : mutexPtr(pm)

  { lock(mutexPtr); }                          // acquire resource



  ~Lock() { unlock(mutexPtr); }                // release resource



private:

  Mutex *mutexPtr;

};

Clients use Lock in the conventional RAII fashion:

Mutex m;                    // define the mutex you need to use



...



{                           // create block to define critical section

 Lock ml(&m);               // lock the mutex

 

...                         // perform critical section operations



}                           // automatically unlock mutex at end

                            // of block

This is fine, but what should happen if a Lock object is copied?

Lock ml1(&m);                      // lock m



Lock ml2(ml1);                     // copy ml1 to ml2—what should

                                   // happen here?

This is a specific example of a more general question, one that every RAII class author must confront: what should happen when an RAII object is copied? Most of the time, you'll want to choose one of the following possibilities:

• Prohibit copying. In many cases, it makes no sense to allow RAII objects to be copied. This is likely to be true for a class like Lock, because it rarely makes sense to have "copies" of synchronization primitives. When copying makes no sense for an RAII class, you should prohibit it. Item 6 explains how to do that: declare the copying operations private. For Lock, that could look like this:

  
  class Lock: private Uncopyable {            // prohibit copying — see
  
  public:                                     // Item 6
  
  
  
   ...                                        // as before
  
  
  
  };
  
  

  
  

• Reference-count the underlying resource. Sometimes it's desirable to hold on to a resource until the last object using it has been destroyed. When that's the case, copying an RAII object should increment the count of the number of objects referring to the resource. This is the meaning of "copy" used by tr1::shared_ptr.

  Often, RAII classes can implement reference-counting copying behavior by containing a TR1::shared_ptr data member. For example, if Lock wanted to employ reference counting, it could change the type of mutexPtr from Mutex* to TR1::shared_ptr<Mutex>. Unfortunately, tr1::shared_ptr's default behavior is to delete what it points to when the reference count goes to zero, and that's not what we want. When we're done with a Mutex, we want to unlock it, not delete it.

  Fortunately, tr1::shared_ptr allows specification of a "deleter" — a function or function object to be called when the reference count goes to zero. (This functionality does not exist for auto_ptr, which always deletes its pointer.) The deleter is an optional second parameter to the tr1::shared_ptr constructor, so the code would look like this:

  
  class Lock {
  
  public:
  
    explicit Lock(Mutex *pm)       // init shared_ptr with the Mutex
  
    : mutexPtr(pm, unlock)         // to point to and the unlock func
  
    {                              // as the deleter
  
  
  
      lock(mutexPtr.get());   // see Item 15 for info on "get"
  
    }
  
  private:
  
    std::tr1::shared_ptr<Mutex> mutexPtr;    // use shared_ptr
  
  };                                         // instead of raw pointer
  
  

  
  

  In this example, notice how the Lock class no longer declares a destructor. That's because there's no need to. Item 5 explains that a class's destructor (regardless of whether it is compiler-generated or user-defined) automatically invokes the destructors of the class's non-static data members. In this example, that's mutexPtr. But mutexPtr's destructor will automatically call the tr1::shared_ptr's deleter — unlock, in this case — when the mutex's reference count goes to zero. (People looking at the class's source code would probably appreciate a comment indicating that you didn't forget about destruction, you're just relying on the default compiler-generated behavior.)

• Copy the underlying resource. Sometimes you can have as many copies of a resource as you like, and the only reason you need a resource-managing class is to make sure that each copy is released when you're done with it. In that case, copying the resource-managing object should also copy the resource it wraps. That is, copying a resource-managing object performs a "deep copy."

  Some implementations of the standard string type consist of pointers to heap memory, where the characters making up the string are stored. Objects of such strings contain a pointer to the heap memory. When a string object is copied, a copy is made of both the pointer and the memory it points to. Such strings exhibit deep copying.

• Transfer ownership of the underlying resource. On rare occasion, you may wish to make sure that only one RAII object refers to a raw resource and that when the RAII object is copied, ownership of the resource is transferred from the copied object to the copying object. As explained in Item 13, this is the meaning of "copy" used by auto_ptr.

The copying functions (copy constructor and copy assignment operator) may be generated by compilers, so unless the compiler-generated versions will do what you want (Item 5 explains the default behavior), you'll need to write them yourself. In some cases, you'll also want to support generalized versions of these functions. Such versions are described in Item 45.