Scoped Handle - "Smart pointer" for Windows objects

• Download sample - 3.95 KB

Introduction

One of the common problems with Windows object handles to solve is to prevent resource leaks. In other words, it is necessary not to forget to call the appropriate delete handle method.

To call the appropriate delete handle method explicitly "by hand" is annoying and error prone. Moreover, to call the appropriate delete handle method during an exception is impossible. Therefore, some automatic calling of the delete handle method would be very handy.

This article describes the simple universal solution of this problem using the well-known RAII (Resource Acquisition Is Initialization) technique. It introduces a scoped handle class which calls in its destructor the appropriate delete handle method.

This scoped handle class has a very similar implementation to the smart pointer scoped_ptr from the boost C++ library.

Solution

The easy solution is to introduce the scoped handle class which calls in its destructor the delete handle method.

However, the Windows API world is not so straightforward. There is no common delete methods for all handles. For example, handle returned from the CreateEvent() API method needs to be deleted by the CloseHandle() method. But handle returned from the FindFirstFile() API method needs to be deleted by the FindClose() method.

Moreover, even the invalid handle definition is not always the same. For example, handle returned from the CreateEvent() API method is invalid when it is NULL. But handle returned from the CreateFile() API method is invalid when it is INVALID_HANDLE_VALUE.

To avoid many similar scoped handle implementations, universal template solution is introduced:

template <typename HandleType, class InvalidValue, class CloseMethod>
class ScopedHandle
{
};

This template has three parameters:

• HandleType - The type of the Windows API handle. E.g., HANDLE, SOCKET, HMODULE.
• InvalidValue - The class which implements a static public method Get() which returns the invalid handle value.
• CloseMethod - The class which implements a static public method Close() which deletes the given handle.

The reason why the template does not use non-class parameters is to support old C++ compilers as well.

Usage

The following is the definition of the scoped handle class for handle returned from the CreateFile() method:

class InvalidHandleValue
{
  public:
        static inline HANDLE Get() { return INVALID_HANDLE_VALUE; }
};

class CloseHandleMethod
{
  public:
        static inline void Close(HANDLE Handle) { CloseHandle(Handle); }
};

typedef ScopedHandle<HANDLE, InvalidHandleValue, CloseHandleMethod> FileScopedHandle;

The usage is as follows:

FileScopedHandle File( CreateFile(_T("SomeFile.bin"), GENERIC_READ, 0, 
                 NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL) );
if (!File)
  throw std::runtime_error("File open failure!");
const DWORD FileSize = GetFileSize(File.Get(), NULL);

Conclusion

This article shows the implementation and usage of a scoped handle class which automatically calls the delete handle method during its destruction.

This class is easy to use, and it is flexible enough for almost all possible object handles. To use this class means to avoid any possible resource leaks, and you will not have to pay any attention to this problem anymore.

Links

• C++ boost library - scoped_ptr class template