Smart Pointers | Inside ATL (Programming Languages/C)

[Previous] [Next]

One of the most confusing concepts for the developer just getting started with COM is the notion of per-interface reference counting. The idea is really quite simple and can be summed up in two statements:

A COM object manages its own lifetime by keeping track of the number of clients that reference it.

A COM object must be notified whenever a client reference (that is, an interface pointer) comes into or goes out of existence.

Reference counting is a powerful, elegant concept, but it does add a certain degree of complexity to C++ client code that uses COM objects. The use of CoCreateInstance (or other COM object_creation mechanisms), AddRef, and Release represents a syntactic paradigm shift from the commonly used new and delete keywords that are familiar to C++ developers. In other words, a C++ developer must treat interface pointers differently than other pointers. To illustrate, let's consider the following pseudocode:

 CMyClient::CMyClient() {     m_pBuffer = new CBuffer();     m_pArray = new CArray();     m_pInterface = SomeCreationMechanism(); } CMyClient::~CMyClient() {     delete m_pBuffer;     delete m_pArray;     delete m_pInterface;    // Oops! }

Obviously, if m_pInterface represents a COM interface pointer, this code will fail miserably. Why? Because the destructor should call m_pInterface->Release instead of trying to free the pointer using the C++ delete keyword. The fact that interface pointers must be handled with different cleanup syntax than other pointers makes it easy for programmers unaccustomed to COM to introduce bugs into their code. This potential hot spot is similar to another common C++ cleanup error. The following code contains a subtle bug:

 CMyCode::CMyCode() {     m_pArray = new CString[256];     m_pBuffer = new TCHAR[256]; } CMyCode::~CMyCode() {     delete m_pArray;    // Oops!     delete m_pBuffer;   // Oops! }

What's the problem with this code? C++ coding rules specify that when deleting an array of objects, the delete keyword must be followed by a bracket pair to tell the compiler to perform the necessary heap cleanup on each object in the array, like so:

 CMyCode::~CMyCode() {     delete [] m_pArray;    // That's better!     delete [] m_pBuffer;   // This bracket pair is technically                            //  required too! }

Even though the improper use of the delete keyword (without the necessary brackets) in the cleanup of the m_pBuffer variable doesn't cause a memory leak under Visual C++, it's still technically a bug, albeit a benevolent one. The Visual C++ compiler will clean up the mistake where m_pBuffer is not destroyed using delete []. The improper deletion of m_pArray, an array of CStrings, does result in a memory leak. Cleaning up COM interface pointers is similar to deleting arrays because it also represents a special case, one that you must keep in mind—consciously at first, subconsciously after a bit of practice—when writing code.

Having to remember to call AddRef and Release instead of delete shouldn't be a big deal once you learn the rules, right? Well, theoretically that's true, but C++ exception handling adds a significant degree of complexity to the picture. Recall that when you use exceptions in your code, the C++ compiler will automatically generate the necessary code to unwind the stack back to the catch block. For example, study the following pseudocode:

 try {          IFortuneCookie* pCookie;     CoCreateInstance(clsid, NULL, CLSCTX_ALL,         IID_IFortuneCookie, (void**)&pCookie;     HRESULT hr = pCookie->SetSeed(FALSE);     if(hr != S_OK)         throw hr; } catch(HRESULT hr) {     TCHAR szErrorDesc[256];     ::FormatMessage(FORMAT_MESSAGE_FROM_SYSTEM, NULL, hr,          MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL),         szErrorDesc, sizeof(szErrorDesc), NULL);     ::MessageBox(NULL, szErrorDesc, "HRESULT Failure", MB_OK);     // Oops! I just leaked pCookie! }

In this code, the client creates an instance of a COM object and calls one of its methods. Following the rules of proper COM development, the object doesn't throw an exception from within the called method when an error occurs. Rather, it returns an error in HRESULT that the client code throws. The code above attempts to recover elegantly from the error by displaying the text-based description of the error to the user before continuing program execution. The problem with this code is that because pCookie is a dynamically allocated interface pointer rather than a stack variable, the compiler won't release pCookie when the thrown exception causes it to go out of scope. Because pCookie isn't defined in the context of the catch block, the code can't call pCookie->Release. As a result, if the COM object is implemented as an out-of-process server, the server won't shut down when the client code terminates because of the outstanding reference to the object.

In the preceding example, we could easily restructure the code so that the scope of pCookie encompasses the catch block—calling pCookie->Release would then be possible. For typical applications, though, writing code to handle a situation like this one would be challenging if not impossible. To solve this problem, some programming languages—specifically Visual Basic and Java—perform automatic garbage collection and IUnknown encapsulation so that the developer doesn't have to manually code calls to the AddRef, Release, and QueryInterface interface methods. Consider the following Visual Basic code:

 Private Sub Form_Load()     Dim cookie As IFortuneCookie     Dim cookie2 As IFortuneCookie2     Set cookie = New FortuneCookie     Set cookie2 = cookie     cookie2.SetSeed(77) End Sub

This code creates an instance of a FortuneCookie COM class, calls QueryInterface at least twice—once each for the IFortuneCookie and IFortuneCookie2 interfaces—and automatically handles the reference counting of each interface. Because of the inherent COM run-time support found in Visual Basic and Microsoft Visual J++, developers using those languages are somewhat more able than C++ developers to focus on the problems their software must solve rather than on syntax.

The CComPtr and CComQIPtr Classes

To provide a level of syntactic convenience that more closely approaches the code shown in Listing 5-1, but without the associated overhead expense Visual Basic imposes, ATL provides two smart pointer classes—CComPtr and CComQIPtr—that implement automatic reference counting. (See Chapter 2 for more details about smart pointers.) The term smart pointer—a common but rather controversial notion in the COM community—refers to a lightweight templatized C++ wrapper class that manages the lifetime of an interface pointer. The basic idea behind smart pointers is to encapsulate the calls to AddRef and Release such that the constructor and destructor call them automatically, as shown in this pseudocode:

 template <class P> class CSmartPtr {     P* p; public:     CSmartPtr(P* ptr) { p = ptr; if(p) p->AddRef(); }     ~CSmartPtr() { if(p) p->Release(); } };

As you'll see later in this chapter, this technique introduces its own set of complications, but it has two benefits. First, the client code no longer needs to call AddRef and Release when using an instance of the pointer. Second, the client code can represent the interface using a CSmartPtr stack variable instead of a dynamically allocated pointer, which means that Release will automatically be called from within the CSmartPtr destructor when the variable goes out of scope.

The ATL smart pointer classes are much more sophisticated than the implementation shown in the preceding pseudocode example. Using the ATL CComPtr and CComQIPtr classes, the C++ version of the Visual Basic code at the top of the previous page would look like this:

 void OnLoad() {     CComPtr<IFortuneCookie> cookie;     cookie.CoCreateInstance(OLESTR("FortuneLib.Cookie"));     CComQIPtr<IFortuneCookie2> cookie2(cookie);     cookie2->SetSeed(77); }

Although the C++ version of the OnLoad code is still syntactically more complex than the Visual Basic code it mimics, it can be expressed in fewer lines. Even more important, because cookie and cookie2 are implemented as stack variables rather than pointers, the interfaces they encapsulate are automatically released when OnLoad terminates, whether as a result of normal execution or a thrown exception.

Previous Versions of ATL: CComPtr and CComQIPtr
The CComPtr and CComQIPtr classes were significantly improved from ATL 2.1 to ATL 3.0. As we describe later in this chapter, one of the chief disadvantages of smart pointer encapsulation is that inadvertent calls made directly to the IUnknown::AddRef and IUnknown::Release methods can cause unexpected and disastrous results. To prevent this problem, the ATL 3.0 versions of the CComPtr and CComQIPtr classes include special provisions that prevent users of those classes from calling AddRef and Release using the overloaded indirection operator (->). ATL 3.0 also introduces several new methods to the smart pointer classes, as you'll see in Table 5-1.

Let's take a look at how the ATL smart pointers work. The source for the CComQIPtr class is defined in atlbase.h and is shown in Listing 5-3. The CComPtr and CComQIPtr classes differ only slightly, so the code in Listing 53 essentially represents the functionality of both classes. Because of this similarity, we'll refer to the ATL smart pointer classes as CComPtr unless we're specifically describing the extra methods implemented by CComQIPtr. As shown in boldface in the listing, CComQIPtr has an optional templatized parameter and two methods not found in CComPtr.

NOTE
In day-to-day development, we use CComQIPtr almost exclusively because it contains a superset of the functionality exposed by CComPtr.

The template parameter T—used to specify the type of the interface pointer being encapsulated—is required to allow the CComPtr class to be strongly typed. This strong typing means that rather than using a generic void* type, the class has a member variable of type T* that holds the interface pointer. This technique offers more than just type safety. It allows the wrapper class to act as if it were a pointer to the interface T when dereferenced using the indirection operator (->), like so:

In this code snippet, pDogPtr is a pointer to an IBuckDog interface, so using the indirection operator to call its Bark method is obvious and fully expected. What isn't immediately clear to the novice is how calling smartPtr->Bark ends up calling the Bark method in light of the fact that smartPtr doesn't inherit from IBuckDog, nor is it a pointer! The answer to this puzzle is that the CComPtr class overloads the indirection operator, as shown in the following pseudocode:

The elegance of C++—combined with the use of templates—allows the CComPtr class to leverage operator overloading to make seamless, type-safe calls to the interface pointer, at the expense of a negligible layer of method invocation.

Using the CComPtr class has several benefits. The CComPtr class allows you to manage the lifetime of an interface pointer as if it were a class pointer by encapsulating the calls to AddRef and Release in its constructors and destructor, respectively. Because smart pointers are typically automatic variables rather than dynamically allocated variables, they are automatically cleaned up when they go out of scope. The use of CComPtr and CComQIPtr simplifies the syntax of the application by reducing the calls to AddRef, Release, and QueryInterface sprinkled throughout the code.

Aside from the benefits mentioned above, the CComPtr class provides helper methods that make it even more convenient to use. Several of these methods, introduced in ATL 3.0, are shown in Table 5-1.

CComPtr Method	Description
IsEqualObject	Compares two interface pointers to see whether they represent the same object. According to the rules of COM, whether two interface pointers represent the same object can be determined only by comparing IUnknown pointers. This function isn't the same as the == operator, which simply performs a mathematical comparison of the value of two pointers.
Attach	Attaches a pointer to the class without incrementing its reference count. Presumably, if the pointer is valid, its reference count is already nonzero via a previous call (whether directly or indirectly) to AddRef. If the class already encapsulates a valid pointer, that pointer will be released before being overwritten.
Detach	Returns the encapsulated pointer and sets the internal copy to NULL without calling Release.
CoCreateInstance	Creates an instance of a coclass specified by its CLSID or its progID, requesting the interface of type T. This method simply calls the global ::CoCreateInstance function, but it does so in a type-safe manner. This method provides default arguments for the outer aggregate and class context.
QueryInterface	Allows the client to make QueryInterface calls on the encapsulated pointer in a type-safe manner.

Although there is no inheritance relationship between CComPtr and CComQIPtr, the CComQIPtr class is essentially a superset of the functionality provided by CComPtr. The chief difference between the two classes is that CComQIPtr provides additional constructor and assignment operators that automatically call QueryInterface when passed an interface pointer. As mentioned earlier, these methods are displayed in boldface in Listing 5-3. CComQIPtr allows you to assign one pointer to another—even if the two pointers represent different interfaces—by making a call to QueryInterface under the hood during the assignment.

In this code, CComQIPtr makes a call to QueryInterface in the dispTest constructor and also in the ptrApp assignment. To allow you to determine whether a smart pointer represents a valid interface pointer, the smart pointer overloads the logical NOT operator, returning true if the pointer is NULL:

The Mr. Hyde of Smart Pointers

So far, we've described the advantages of using the CComPtr and CComQIPtr classes. Obviously, they offer a level of convenience and information hiding that makes their use attractive. Smart pointers are not without a dark side, however. They can potentially introduce several problems into your application.

The smart pointer classes provide a CoCreateInstance method that encapsulates a call to the COM API of the same name. This method is helpful in many situations, especially because it has two overloaded implementations: one that takes a progID parameter and another that accepts a CLSID. The ATL smart pointer classes also encapsulate the casting of the interface pointer to a void** (as required by the global ::CoCreateInstance API), thus reducing the errors generally associated with that cast's lack of type safety. The drawback is that the CoCreateInstance method calls ::CoCreateInstance rather than ::CoCreateInstanceEx, so you can't use it when you need to explicitly specify the name and activation security context of the remote machine on which the object will be created. Furthermore, you can't always use the CoCreateInstance method when instantiating Automation servers. Some servers require you to call the ::OleRun API to transition the object into a running state before calling QueryInterface for the desired interface.