LCleanedupHandle Class Reference

class LCleanedupHandle : 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 CleanupStack-based local-scope automatic management of resource handles (typically instances of R-classes).

Note:

This class can only be used to define locals, never data members. See below for an explanation and links to management classes suitable for use in different contexts. It should never be used in the same function as code that uses the CleanupStack API directly.

This class template can be used to create and protect a resource handle of type T (typically a R-class) such that the instance of T referred to is automatically cleaned up when either of the following occur:
  • The referring local variable goes out of scope normally

  • The referring local variable goes out of scope due to an untrapped leave causing the scope to be exited non-locally

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 may leave.

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 handle 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:
	// block scope example
	{
	LCleanedupHandle<RClosable> obj;
	obj->DoSomethingL(); // leave-safe
	if (obj->Finished())
		return; // RClosable::Close is invoked automatically
	obj->DoSomethingElseL(); // leave-safe
	// RClosable::Close is invoked automatically
	}

Behind the scenes, this class template is implemented in terms of the thread-local CleanupStack, restricting its use to locals on the stack. This use of the CleanupStack ensures a consistent cleanup order between functions that call one another, even if they use different cleanup idioms.

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

LManagedHandle which has the same interface, but does not use the cleanup stack and is suitable for protecting the data members of classes

Public Member Functions
LCleanedupHandle()
LCleanedupHandle(const Param1 &)
LCleanedupHandle(Param1 &)
LCleanedupHandle(const Param1 &, const Param2 &)
LCleanedupHandle(const Param1 &, Param2 &)
LCleanedupHandle(Param1 &, const Param2 &)
LCleanedupHandle(Param1 &, Param2 &)
~LCleanedupHandle()
voidCleanup(TAny *)
voidReleaseResource()
voidSwap(LCleanedupHandle &)
LCleanedupHandle &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
typedefCleanupStrategyType CleanupStrategy
typedefT 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

LCleanedupHandle()

LCleanedupHandle()[inline]

Default constructor.

LCleanedupHandle(const Param1 &)

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

Parameters

const Param1 & aParam1

LCleanedupHandle(Param1 &)

LCleanedupHandle(Param1 &aParam1)[inline, explicit]

Parameters

Param1 & aParam1

LCleanedupHandle(const Param1 &, const Param2 &)

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

Parameters

const Param1 & aParam1
const Param2 & aParam2

LCleanedupHandle(const Param1 &, Param2 &)

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

Parameters

const Param1 & aParam1
Param2 & aParam2

LCleanedupHandle(Param1 &, const Param2 &)

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

Parameters

Param1 & aParam1
const Param2 & aParam2

LCleanedupHandle(Param1 &, Param2 &)

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

Parameters

Param1 & aParam1
Param2 & aParam2

~LCleanedupHandle()

~LCleanedupHandle()[inline]

Member Functions Documentation

Cleanup(TAny *)

voidCleanup(TAny *aPtr)[static, inline]

Parameters

TAny * aPtr

ReleaseResource()

voidReleaseResource()[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(LCleanedupHandle &)

voidSwap(LCleanedupHandle &aCleanedupHandle)[inline]

Parameters

LCleanedupHandle & aCleanedupHandle

operator=(const U &)

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

Assigns a new resource to be managed. If the LCleanedupHandle 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

Member Type Definitions Documentation

Typedef CleanupStrategy

typedef CleanupStrategyTypeCleanupStrategy

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 TManagedType