LCleanedupPtr Class Reference

class LCleanedupPtr : protected LCleanedupPtrBase

A class template that provides CleanupStack-based local-scope automatic management of pointers.

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 protect a pointer to type T 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 delete the managed pointer using non-array delete. 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.

The constructors of this class may leave.

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:
	// block scope example
	{
	LCleanedupPtr<CDynamic> autop(new(ELeave) CDynamic);
	autop->DoSomethingL(); // leave-safe
	if (autop->Finished())
		return; //	the pointer is deleted automatically when exiting from scope
	autop->DoSomethingElseL(); // leave-safe
	//	the pointer is deleted automatically when exiting from scope
	}

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).

TPointerDelete which implements the default deleting cleanup strategy TPointerFree which implements the alternative User::Free() cleanup strategy LManagedPtr 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
LCleanedupPtr()
LCleanedupPtr(T *)
T *Get()
voidSwap(LCleanedupPtr &)
T *Unmanage()
operator TUnspecifiedBoolType()
T &operator*()
T *operator->()
LCleanedupPtr &operator=(T *)
LCleanedupPtr &operator=(U *)
Inherited Functions
LAutoPtrBase< TPtrCleanupTraits< T, CleanupStrategyType >::BaseManagedType >::Disable()
LAutoPtrBase< TPtrCleanupTraits< T, CleanupStrategyType >::BaseManagedType >::IsEnabled()const
LAutoPtrBase< TPtrCleanupTraits< T, CleanupStrategyType >::BaseManagedType >::LAutoPtrBase()
LAutoPtrBase< TPtrCleanupTraits< T, CleanupStrategyType >::BaseManagedType >::LAutoPtrBase(TPtrCleanupTraits< T, CleanupStrategyType >::BaseManagedType *)
LAutoPtrBase< TPtrCleanupTraits< T, CleanupStrategyType >::BaseManagedType >::Swap(LAutoPtrBase &)
LAutoPtrBase< TPtrCleanupTraits< T, CleanupStrategyType >::BaseManagedType >::operator=(TPtrCleanupTraits< T, CleanupStrategyType >::BaseManagedType *)
LCleanedupPtrBase::Cleanup(TAny *)
LCleanedupPtrBase::LCleanedupPtrBase()
LCleanedupPtrBase::LCleanedupPtrBase(U *)
LCleanedupPtrBase::ReleaseResource()
LCleanedupPtrBase::Swap(LCleanedupPtrBase &)
LCleanedupPtrBase::~LCleanedupPtrBase()
Public Member Type Definitions
typedefCleanupStrategyType CleanupStrategy
typedef LCleanedupPtrBase::BaseManagedType * LCleanedupPtr< T, CleanupStrategy >TUnspecifiedBoolType
typedefT ManagedType
Private Member Type Definitions
typedef LCleanedupPtrBase< T, CleanupStrategyType > LCleanedupPtrBase
Inherited Attributes
LAutoPtrBase< TPtrCleanupTraits< T, CleanupStrategyType >::BaseManagedType >::iPtr

Constructor & Destructor Documentation

LCleanedupPtr()

LCleanedupPtr()[inline]

Default constructor. Constructs an empty LCleanedupPtr object.

Post-condition
Get() == NULL

LCleanedupPtr(T *)

LCleanedupPtr(T *aPtr)[inline, explicit]

Explicit constructor template. Constructs a LCleanedupPtr object that manages the pointer aPtr of a type convertible to T* that can be cleaned up using the cleanup strategy of the LCleanedupPtr class. The default cleanup strategy is to delete the pointer to a heap-allocated object by using non-array delete. Alternative cleanup strategies can be specified by using the CleanupStrategy template parameter of the LCleanedupPtr class template.

Pre-condition
aPtr is of a type convertible to T* and can be cleaned up using the cleanup strategy.
Post-condition
Get() == aPtr

Parameters

T * aPtrA pointer of a type that is convertible to T* that can be cleaned up using the cleanup strategy.

Member Functions Documentation

Get()

T *Get()const [inline]

Returns a pointer to the managed object of type T.

Swap(LCleanedupPtr &)

voidSwap(LCleanedupPtr &aCleanedupPtr)[inline]

Parameters

LCleanedupPtr & aCleanedupPtr

Unmanage()

T *Unmanage()[inline]

Disables the automatic resource management for this object and returns a pointer to the object of type T.

operator TUnspecifiedBoolType()

operator TUnspecifiedBoolType()[inline]

Conversion operator that enables LCleanedupPtr objects to be used in boolean contexts.

operator*()

T &operator*()const [inline]

Overloaded indirection operator function.

operator->()

T *operator->()const [inline]

Overloaded class member access operator function.

operator=(T *)

LCleanedupPtr &operator=(T *aPtr)[inline]

Assigns a new pointer to be managed. The new pointer must be of a type convertible to T* and it must be possible to use the cleanup strategy of the LCleanedupPtr object for the cleanup of the new managed pointer. If the LCleanedupPtr object already contains a managed pointer, then the cleanup strategy is invoked with the managed pointer before assigning the new managed pointer.

Pre-condition
aPtr is a pointer of a type that is convertible to T* and can be cleaned up using the cleanup strategy.
Post-condition
Get() == aPtr

Parameters

T * aPtrA pointer of a type that is convertible to T* that can be cleaned up using the cleanup strategy.

operator=(U *)

LCleanedupPtr &operator=(U *aPtr)[inline]

Assigns a new pointer to be managed. The new pointer must be of a type convertible to T* and it must be possible to use the cleanup strategy of the LCleanedupPtr object for the cleanup of the new managed pointer. If the LCleanedupPtr object already contains a managed pointer, then the cleanup strategy is invoked with the managed pointer before assigning the new managed pointer.

Pre-condition
aPtr is a pointer of a type that is convertible to T* and can be cleaned up using the cleanup strategy.
Post-condition
Get() == aPtr

Parameters

U * aPtrA pointer of a type that is convertible to T* that can be cleaned up using the cleanup strategy.

Member Type Definitions Documentation

Typedef CleanupStrategy

typedef CleanupStrategyTypeCleanupStrategy

Typedef LCleanedupPtr< T, CleanupStrategy >TUnspecifiedBoolType

typedef LCleanedupPtrBase::BaseManagedType *LCleanedupPtr< T, CleanupStrategy >TUnspecifiedBoolType

Typedef LCleanedupPtrBase

typedef LCleanedupPtrBase< T, CleanupStrategyType >LCleanedupPtrBase[private]

Typedef ManagedType

typedef TManagedType