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 
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 
You still have to store the CloseHandle function pointer for later use, hence, it is runtime. (And the function pointer can be even a pointer to a polymorphic object, if you want the close policy to be whatever function or functor)
 
About efficiency, ScopeGuard is surely more efficient then a shared_ptr, where no share is required, and may be even more efficient that the author proposal (that requires to code things around, that take their space and time).
But it is another thing.
 
Note that ScopeGuard is like strcpy: if you don't remember how it is named, it is faster for you to rewrite it than to search for it. That's the reason why there are at least 1000 other implementations around Smile | :)
 
That said, for the cases you are talking about, there is no much difference (you don't have milions of handles, so space is not a problem) and the code is far more clear.

2 bugs found.
> recompile ...
65534 bugs found.
D'Oh! | :doh:


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
Web03 | 2.8.1411028.1 | Last Updated 21 Jul 2010
Article Copyright 2010 by Miki Rozloznik
Everything else Copyright © CodeProject, 1999-2014
Layout: fixed | fluid