LManagedPtr Class Reference

#include <emanaged.h>

class LManagedPtr : protected LManagedPtrBase

Detailed Description

A class template that provides automatic management of pointers 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 pointer to type T such that the instance of T referred to 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 delete the managed pointer using a (non-array) delete operation. An alternative cleanup strategy can be specified using the optional CleanupStrategy class template parameter of the LManagedPtr class template. The most common alternative cleanup strategies are predefined (e.g. TPointerFree).

The constructors of this class never leave, so data members defined with this type may be initialized safely during any phase of construction of the owning class.

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()
		   : iComponent(CComponent::NewL())
		   {
		   //...
		   }

	   ~CComposite()
		   {
		   // the pointer to the CComponent object is automatically
		   // deleted
		   }

	 private:
	   LManagedPtr<CComponent> iComponent;
	   };

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

See also: TPointerDelete which implements the default deleting cleanup strategy TPointerFree which implements the alternative User::Free() cleanup strategy LCleanedupPtr which has the same interface, but uses the cleanup stack and is suitable for protecting locals CONSTRUCTORS_MAY_LEAVE

Member Type Definition Documentation

Typedef CleanupStrategy

typedef CleanupStrategyTypeCleanupStrategy

Typedef LManagedPtr< T, CleanupStrategy >TUnspecifiedBoolType

typedef LManagedPtrBase::BaseManagedType *LManagedPtr< T, CleanupStrategy >TUnspecifiedBoolType

Typedef ManagedType

typedef TManagedType

Constructor & Destructor Documentation

LManagedPtr ( )

LManagedPtr()[inline]

Default constructor. Constructs an empty LManagedPtr object.

Post-condition
Get() == NULL

LManagedPtr ( T * )

LManagedPtr(T *aPtr)[inline, explicit]

Explicit constructor template. Constructs a LManagedPtr object that manages the pointer aPtr of a type convertible to T* that can be cleaned up using the cleanup strategy of the LManagedPtr 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 LManagedPtr 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
ParameterDescription
aPtrA pointer of a type that is convertible to T* that can be cleaned up using the cleanup strategy.

Member Function Documentation

Get ( )

T *Get()const [inline]

Returns a pointer to the managed object of type T.

Returns: A pointer to the managed object of type T.

Swap ( LManagedPtr & )

voidSwap(LManagedPtr &aManagedPtr)[inline]

Unmanage ( )

T *Unmanage()[inline]

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

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.

Returns: An unspecified value of an unspecified type convertible to boolean, which has a boolean value equal to Get() != NULL

operator* ( )

T &operator*()const [inline]

Overloaded indirection operator function.

Returns: A reference to the managed object of type T.

operator-> ( )

T *operator->()const [inline]

Overloaded class member access operator function.

Returns: A pointer to the managed object of type T.

operator= ( T * )

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

Destructor. When automatic resource management is enabled, the destructor invokes the specified cleanup strategy for the managed pointer. 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 LManagedPtr object for the cleanup of the new managed pointer. If the LManagedPtr 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
ParameterDescription
aPtrA pointer of a type that is convertible to T* that can be cleaned up using the cleanup strategy.

operator= ( U * )

LManagedPtr &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 LManagedPtr object for the cleanup of the new managed pointer. If the LManagedPtr 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
ParameterDescription
aPtrA pointer of a type that is convertible to T* that can be cleaned up using the cleanup strategy.