Exception safety and RAII

In the previous example, we looked informally at the concept of exception safety. We saw that a potential exception thrown from the img_rotate API could leak resources in the rotateImage function. It turns out that you can reason about the behavior of your code in the face of exceptions in terms of a set of criteria called The Abrahams Exception Safety Guarantees. They are named after Dave Abrahams, the Boost cofounder and an eminent C++ Standards Committee member, who formalized these guarantees in 1996. They have since been refined further by others, including notably Herb Sutter, and are listed below:

An operation that does not satisfy any of these criteria is said to be "not exception-safe" or more colloquially, exception-unsafe. The appropriate level of exception safety for an operation is the programmer's prerogative but exception-unsafe code is rarely acceptable.

The most fundamental and effective C++ technique for making code exception-safe goes by the curious name Resource Acquisition is Initialization (RAII). The RAII idiom proposes the following model for encapsulating resources that require manual management:

If the wrapper object is created on the stack, its destructor is called for normal scope exit as well as exit due to exceptions. Otherwise, the wrapper object itself should be managed by the RAII idiom. Loosely speaking, you either create your objects on the stack or manage them using RAII. At this point, some examples are in order, and we can go straight back to the image rotation example and fix it using RAII:

 1 struct ScopeGuard
 2 {
 3   ScopeGuard(byte *buffer) : data_(buffer) {}
 4   ~ScopeGuard() { delete [] data_; }
 5
 6 byte *get() { return data_; }
 7 private:
 8   byte *data_;
 9 };
10 
11 byte *rotateImage(std::string imgFile, double angle, size_t& sz)
12 {
13   // open the file for reading
14   std::ifstream imgStrm(imgFile.c_str(), std::ios::binary);
15 
16   if (imgStrm) {
17     // determine file size
18     imgStrm.seekg(0, std::ios::end);
19     sz = imgStrm.tellg();
20     imgStrm.seekg(0);
21
22     // allocate buffer and read
23     ScopeGuard img(new byte[sz]);
24     // read the image contents
25     imgStrm.read(reinterpret_cast<char*>(img.get()), sz);
26     // process it
27     return img_rotate(img.get(), sz, angle);
28   } // ScopeGuard destructor
29 
30   sz = 0;
31   return 0;
32 }

The preceding code is a modest attempt that makes the rotateImage function exception-safe, provided the img_rotate function itself is exception-safe. First up we define a struct called ScopeGuard (lines 1-9) for encapsulating character arrays allocated by the array new operator. It takes a pointer to an allocated array as its constructor argument and sets the data member data_ to this pointer (line 3). Its destructor deallocates the array pointed to by its data_ member using the array delete operator (line 4). The get member function (line 6) provides a way to get the underlying pointer from a ScopeGuard object.

Inside the rotateImage function, we instantiate a ScopeGuard object called img, wrapping the byte array allocated using array new operator (line 23). We call read on the open file stream and pass to it the raw byte array obtained by calling the get method on img (line 25). We assume read always succeeds but, in production code, we should always have proper error checks in place. Finally, we call the img_rotate API and return the rotated image it returns (line 27). As we exit the scope, the ScopeGuard destructor is called and automatically deallocates the encapsulated byte array (line 28). Even if img_rotate threw an exception, the ScopeGuard destructor would still be called as part of stack unwinding. Through the use of RAII via the ScopeGuard class, we are able to claim that the rotateImage function can never leak the buffer containing the image data.

On the other hand, the buffer containing the rotated image returned by rotateImage could be leaked, unless the caller takes care to assign it to a pointer and then duly release it in an exception-safe way. The ScopeGuard class in its current form is no good there. It turns out that Boost ships different kinds of smart pointer templates to address various use cases like these, and it is worthwhile to understand these smart pointers and the patterns of resource acquisition, and the exception safety problems they help solve.