Click here to Skip to main content
Click here to Skip to main content

Scoped Handle - "Smart pointer" for Windows objects

, 21 Jul 2010 CPOL
Rate this:
Please Sign up or sign in to vote.
Introduces a scoped handle template class to call delete handle methods automatically.

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

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Miki Rozloznik
Software Developer (Senior) Eccam s.r.o.
Czech Republic Czech Republic
Senior Sofware Developer focused on embedded systems.
Company website: http://www.eccam.com

Comments and Discussions

 
GeneralMy vote of 4 PinmemberJoxemi28-Jul-10 3:13 
GeneralMy vote of 5 PinmemberS.H.Bouwhuis26-Jul-10 23:55 
GeneralAnother article with a similar topic PinmemberNemanja Trifunovic23-Jul-10 0:18 
GeneralMy vote of 4 PinmemberAescleal22-Jul-10 23:44 
GeneralMy vote of 2 PinmemberAescleal22-Jul-10 3:41 
GeneralRe: My vote of 2 PinmemberAndre xxxxxxx22-Jul-10 5:57 
GeneralRe: My vote of 2 PinmemberAescleal22-Jul-10 6:33 
Au contraire my little downvoter, I'm well aware of how I can use unique_ptr, shared_ptr and ScopeGuard to handle windows handles. Unfortunately I don't do kernel mode programming but the examples used in the article were all user mode so I don't think I'm going to loose much sleep over this.
 
Consider the following (I'm using VC++2008 without SP1 installed as that's the IDE I've got open...)
 
typedef std::tr1::shared_ptr<void> managed_handle;
 
That definition will give you everything the article describes. So I can write things like:
 
managed_handle h( CreateMutex( 0, FALSE, 0 ), CloseHandle );
 
and I get a handle to the user mode image of a kernel object that will be cleaned up when the object is deleted. I can also use it as:
 
WIN32_FIND_DATA fd;
managed_handle h( FindFirstFile( L"c:\\test.bat", &fd ), FindClose );
 
to get round one of the problems that have been posted to the message boards several times in the last three months.
 
So the question remains, what can this class do that others can't? What's it's unique selling point? Why should I be using it instead of ScopeGuard which is 10 years old?
 
Edited as I forgot the whole webby HTML escapy thing for angle brackets
GeneralRe: My vote of 2 Pinmemberemilio_grv22-Jul-10 12:46 
GeneralRe: My vote of 2 [modified] PinmemberAescleal22-Jul-10 21:11 
GeneralRe: My vote of 2 PinmemberMiki Rozloznik22-Jul-10 22:47 
GeneralRe: My vote of 2 Pinmemberemilio_grv22-Jul-10 22:48 
GeneralRe: My vote of 2 PinmemberMiki Rozloznik22-Jul-10 21:25 
GeneralRe: My vote of 2 PinmemberAescleal22-Jul-10 23:40 
GeneralGood idea, just some small thing: Pinmemberimagiro21-Jul-10 22:43 
GeneralRe: Good idea, just some small thing: PinmemberMiki Rozloznik22-Jul-10 3:32 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Terms of Use | Mobile
Web01 | 2.8.1411019.1 | Last Updated 21 Jul 2010
Article Copyright 2010 by Miki Rozloznik
Everything else Copyright © CodeProject, 1999-2014
Layout: fixed | fluid