LManagedHandle Class Reference

class LManagedHandle : protected LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>

A class template for the creation and automatic management of resource handles (typically R-class instances) held in the data members of objects.

Note:

This class should not used to define locals. See below for an explanation and links to management classes suitable for use in that context.

This class template can be used to protect a resource handle of type T (typically an R-class instance) such that the instance of T protected is automatically cleaned up when the management object is destroyed; typically when the object containing it is deleted.

By default, the cleanup action is to call the Close() member function of the managed handle. An alternative cleanup strategy may be selected by specifying a cleanup strategy template class in the optional second template parameter position. The most common alternative cleanup strategies are predefined. It is also possible to specialize the default cleanup action for a given class using the DEFINE_CLEANUP_FUNCTION macro.

The constructors of this class never leave (unless construction of the underlying T instance can leave, which is rare), so data members defined with this type may be initialized safely during any phase of construction of the owning class.

Any arguments supplied when initializing an instance of this class are automatically passed through to T's constructors.

As a convenience, the methods of the managed pointer may be accessed via "->" notation directly on the management object, while "." notation is used to access the interface of the management object itself. Using "*" to dereference the management object yields a T&, and is often useful when passing the managed object as an argument.

Automatic cleanup may be disabled at any time by calling Unmanage() , while cleanup may be forced at any time by calling ReleaseResource() .

Example:
        class CComposite : public CBase
	   {
	 public:
	   CONSTRUCTORS_MAY_LEAVE

	   CComposite()
		   {
		   iFileServ->Connect() OR_LEAVE;
		   iFile->Open(*iFileServ, ...);
		   }

	   ~CComposite()
		   {
		   // the handles are automatically closed
		   }

	 private:

	   LManagedHandle<RFs> iFileServ;
	   LManagedHandle<RFile> iFile;
	   };
       

Behind the scenes, this class template simply relies on reliable execution of its destructor. If used for a local variable rather than a data member, cleanup will occur but out-of-order compared to objects protected using the LCleanupXxx variants or the CleanupStack directly. Therefore it is not recommended for use in that context.

These management classes may be used as the basis for implementing leave-safe single-phase construction, since fully initialized data members protected in this way will get destroyed (so reliably triggering cleanup) if their containing classes leave during execution of their constructors. Note, however, that single-phase construction must be explicitly enabled in the containing class using the CONSTRUCTORS_MAY_LEAVE macro.

This class template together with the cleanup strategy class templates provide a template-based implementation of the Strategy design pattern (See also: Policy-based design).

TClose which implements the default Close() calling cleanup strategy TResetAndDestroy which implements an alternative ResetAndDestroy() calling cleanup strategy TFree which implements an alternative Free() calling cleanup strategy TDestroy which implements an alternative Destroy() calling cleanup strategy TRelease which implements an alternative Release() calling cleanup strategy LCleanedupHandle which has the same interface, but uses the cleanup stack and is suitable for protecting locals CONSTRUCTORS_MAY_LEAVE

Public Member Functions
LManagedHandle ()
LManagedHandle (const Param1 &)
LManagedHandle (Param1 &)
LManagedHandle (const Param1 &, const Param2 &)
LManagedHandle (const Param1 &, Param2 &)
LManagedHandle (Param1 &, const Param2 &)
LManagedHandle (Param1 &, Param2 &)
~LManagedHandle ()
void ReleaseResource ()
void Swap ( LManagedHandle &)
LManagedHandle & operator= (const U &)
Inherited Functions
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::Disable()
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::Get()
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::Get()const
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::IsEnabled()const
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::LAutoHandleBase()
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::LAutoHandleBase(Param1 &)
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::LAutoHandleBase(Param1 &,Param2 &)
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::LAutoHandleBase(Param1 &,const Param2 &)
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::LAutoHandleBase(const Param1 &)
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::LAutoHandleBase(const Param1 &,Param2 &)
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::LAutoHandleBase(const Param1 &,const Param2 &)
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::Swap(LAutoHandleBase &)
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::Unmanage()
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::operator*()
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::operator*()const
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::operator->()
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::operator->()const
Public Member Type Definitions
typedef CleanupStrategyType CleanupStrategy
typedef T ManagedType
Private Member Type Definitions
typedef LAutoHandleBase < T, TIsBaseOf < RHandleBase , T >::EValue?EAutoRHandleBaseDerived:(( TIsSame < RBuf8 , T >::EValue|| TIsSame < RBuf16 , T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)> LAutoHandleBase
Inherited Attributes
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::iEnabled
LAutoHandleBase< T, TIsBaseOf< RHandleBase, T >::EValue?EAutoRHandleBaseDerived:((TIsSame< RBuf8, T >::EValue||TIsSame< RBuf16, T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)>::iHandle

Constructor & Destructor Documentation

LManagedHandle()

LManagedHandle ( ) [inline]

Default constructor.

LManagedHandle(const Param1 &)

LManagedHandle ( const Param1 & aParam1 ) [inline, explicit]

Parameters

const Param1 & aParam1

LManagedHandle(Param1 &)

LManagedHandle ( Param1 & aParam1 ) [inline, explicit]

Parameters

Param1 & aParam1

LManagedHandle(const Param1 &, const Param2 &)

LManagedHandle ( const Param1 & aParam1,
const Param2 & aParam2
) [inline]

Parameters

const Param1 & aParam1
const Param2 & aParam2

LManagedHandle(const Param1 &, Param2 &)

LManagedHandle ( const Param1 & aParam1,
Param2 & aParam2
) [inline]

Parameters

const Param1 & aParam1
Param2 & aParam2

LManagedHandle(Param1 &, const Param2 &)

LManagedHandle ( Param1 & aParam1,
const Param2 & aParam2
) [inline]

Parameters

Param1 & aParam1
const Param2 & aParam2

LManagedHandle(Param1 &, Param2 &)

LManagedHandle ( Param1 & aParam1,
Param2 & aParam2
) [inline]

Parameters

Param1 & aParam1
Param2 & aParam2

~LManagedHandle()

~LManagedHandle ( ) [inline]

Destructor. When automatic resource management is enabled, the destructor calls the cleanup function defined by the cleanup strategy with the contained resource handle object.

Member Functions Documentation

ReleaseResource()

void ReleaseResource ( ) [inline]

If automatic resource management is enabled, calls the cleanup function defined by the cleanup strategy with the managed resource handle object and then disables the automatic resource management for this object. The cleanup strategy is specified by the CleanupStrategy template template parameter. The default cleanup strategy is to call the cleanup member function on the contained resource handle object. which is a member function named Close(), unless explicitly defined otherwise for the class of the object, for example by using the provided DEFINE_CLEANUP_FUNCTION macro.

Swap(LManagedHandle &)

void Swap ( LManagedHandle & aManagedHandle ) [inline]

Parameters

LManagedHandle & aManagedHandle

operator=(const U &)

LManagedHandle & operator= ( const U & aHandle ) [inline]

Assigns a new resource to be managed. If the LManagedHandle object already contains a managed resource handle, then the managed resource is released using the specified cleanup strategy before assigning the new managed resource.

Parameters

const U & aHandle a reference to a handle object of a type that can be assigned to a handle object of type T

Member Type Definitions Documentation

Typedef CleanupStrategy

typedef CleanupStrategyType CleanupStrategy

Typedef LAutoHandleBase

typedef LAutoHandleBase < T, TIsBaseOf < RHandleBase , T >::EValue?EAutoRHandleBaseDerived:(( TIsSame < RBuf8 , T >::EValue|| TIsSame < RBuf16 , T >::EValue)?EAutoHandleRBuf:EAutoHandleNonSpecial)> LAutoHandleBase [private]

Typedef ManagedType

typedef T ManagedType