scoped_handle Class Template Reference
[Smart Pointers library]

#include <stlsoft/smartptr/scoped_handle.hpp>

List of all members.


Detailed Description

template<typename H>
class stlsoft::scoped_handle< H >

Provides automated scope-based cleanup of arbitrary resource types without any memory allocation required to implement the generic support.

The template is parameterised on the resource type (e.g. FILE*, int, void*) and instances are initialised from a resource handle and the address of a (single-parameter) cleanup function, as in:

 ::stlsoft::scoped_handle<void*>  h3(::malloc(100), ::free);

or:

 ::stlsoft::scoped_handle<int>    h1(::open("file.ext"), ::close);

or:

 FILE*                            file = ::fopen("file.ext", "r");
 ::stlsoft::scoped_handle<FILE*>  h2(file, ::fclose);

Note:
This class provides externally-initialised immutable-RAII (see section 3.5 of Imperfect C++; http://imperfectcplusplus.com/). The managed resource must be provided in the constructor, and the managing instance cannot be set to manage another resource. However, there is a nod to convenience in so far as there is a detach() method, which can be used to clear the resource from the managing instance and return it to the calling context.
Examples:

by_library/com_utility/rot_functions/rot_functions.cpp, and by_library/windows_shell/shell_functions/shell_functions.cpp.


Types

typedef H resource_type
 The resource type.
typedef H handle_type
 The handle type.
typedef scoped_handle< H > class_type
 The instantiation of the type.

Public Types

enum  {
  cdecl_function_type_v_size = sizeof(scoped_handle_borland_impl_::cdecl_function_type_v<H>),
  cdecl_function_type_size = sizeof(scoped_handle_borland_impl_::cdecl_function_type<H, int>)
}
typedef H resource_type
typedef H handle_type
typedef scoped_handle< H > class_type

Public Member Functions

template<typename R>
 scoped_handle (resource_type h, R(__fastcall *fn)(resource_type), resource_type hNull=0)
template<typename R>
 scoped_handle (resource_type *ph, R(__fastcall *fn)(resource_type *), resource_type hNull=0)
template<typename R>
 scoped_handle (resource_type h, R(__stdcall *fn)(resource_type), resource_type hNull=0)
template<typename R>
 scoped_handle (resource_type *ph, R(__stdcall *fn)(resource_type *), resource_type hNull=0)
bool empty () const
void close ()
resource_type detach ()
resource_type handle () const
resource_type get () const
Construction
template<typename R>
 scoped_handle (resource_type h, R(__fastcall *f)(resource_type), resource_type hNull=0)
 Construct from a resource handle and a clean-up "fastcall" function with non-void return type.
template<typename R>
 scoped_handle (resource_type *ph, R(__fastcall *f)(resource_type *), resource_type hNull=0)
 Construct from a resource handle and an indirect clean-up "fastcall" function with non-void return type.
template<typename R>
 scoped_handle (resource_type h, R(__stdcall *f)(resource_type), resource_type hNull=0)
 Construct from a resource handle and a clean-up "stdcall" function with non-void return type.
template<typename R>
 scoped_handle (resource_type *ph, R(__stdcall *f)(resource_type *), resource_type hNull=0)
 Construct from a resource handle and an indirect clean-up "stdcall" function with non-void return type.
 ~scoped_handle ()
 "Releases" the managed resource.
Attributes
bool empty () const
 Indicates whether the instance holds a non-"null" resource.
Operations
void close ()
 Closes the handle immediately.
resource_type detach ()
 Detaches the resource, and returns it to the caller.
Accessors
resource_type handle () const
 Provides the bare resource handle to the caller.
resource_type get () const
 Provides the bare resource handle to the caller.

Member Typedef Documentation

typedef H resource_type

The resource type.

typedef H handle_type

The handle type.

The instantiation of the type.


Constructor & Destructor Documentation

scoped_handle ( resource_type  h,
R(__fastcall *f)(resource_type ,
resource_type  hNull = 0 
) [inline]

Construct from a resource handle and a clean-up "fastcall" function with non-void return type.

scoped_handle ( resource_type ph,
R(__fastcall *f)(resource_type *)  ,
resource_type  hNull = 0 
) [inline]

Construct from a resource handle and an indirect clean-up "fastcall" function with non-void return type.

scoped_handle ( resource_type  h,
R(__stdcall *f)(resource_type ,
resource_type  hNull = 0 
) [inline]

Construct from a resource handle and a clean-up "stdcall" function with non-void return type.

scoped_handle ( resource_type ph,
R(__stdcall *f)(resource_type *)  ,
resource_type  hNull = 0 
) [inline]

Construct from a resource handle and an indirect clean-up "stdcall" function with non-void return type.

~scoped_handle (  )  [inline]

"Releases" the managed resource.

Invokes the cleanup function, unless close() or detach() have already been called


Member Function Documentation

bool empty (  )  const [inline]

Indicates whether the instance holds a non-"null" resource.

Referenced by scoped_handle< void >::close(), and scoped_handle< void >::~scoped_handle().

void close (  )  [inline]

Closes the handle immediately.

Note:
Calling this method more than once has no effect.

resource_type detach (  )  [inline]

Detaches the resource, and returns it to the caller.

Remarks:
Calling this method removes the resource from the managing instance, so it will not be automatically closed.

resource_type handle (  )  const [inline]

Provides the bare resource handle to the caller.

Does not detach the handle from the managing instance.

Deprecated:
Deprecated in favour of get()

resource_type get (  )  const [inline]

Provides the bare resource handle to the caller.

Does not detach the handle from the managing instance.


The documentation for this class was generated from the following files:

Generated on Thu Jun 10 08:58:56 2010 for STLSoft by  doxygen 1.5.6