LManagedArray Class Reference

#include <emanaged.h>

class LManagedArray : protected LAutoPtrBase

Inherits from

Detailed Description

A class template that provides automatic management of arrays. Such managed arrays can be data members of composite classes.

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.

Note:

This class can only be used with raw arrays, which are used only rarely on Symbian OS. Instances of Symbian array container classes (e.g. RArray, RPointerArray) should be managed using the automatic management template classes appropriate for the array's type (LManagedHandle template classes for Symbian R arrays or LManagedPtr template classes for Symbian C arrays).

This class template can be used to protect a heap-allocated array of objects of type T such that the managed array is automatically deallocated when the management object is destroyed.

The default cleanup strategy is to deallocate the managed array using arrray delete (delete[]), assuming that the array is heap-allocated. An alternative cleanup strategy can be selected by specifying a cleanup strategy template class as the optional second template argument (corresponding to the CleanupStrategy template parameter).

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 elements of the managed array may be accessed via "[]" notation directly on the management object.

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()
		   : iComponents(new(ELeave) CComponent[KNumComponents])
		   {
		   //...
		   }

	   ~CComposite()
		   {
		   // the array is automatically deleted
		   }

	 private:
	   LManagedArray<CComponent> iComponents;
	   };

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: LCleanedupArray 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 ManagedType

typedef TManagedType

Constructor & Destructor Documentation

LManagedArray ( )

LManagedArray()[inline]

Default constructor. Constructs an empty LManagedArray object.

Post-condition
Get() == NULL

LManagedArray ( T * )

LManagedArray(T *aPtr)[inline, explicit]

Explicit constructor. Constructs a LManagedArray object that manages an array of objects of type T that can be cleaned up using the cleanup strategy of the LManagedArray class. The default cleanup strategy is to deallocate the managed array by using array delete (delete[]), assuming that the array is heap-allocated. Alternative cleanup strategies can be specified by using the CleanupStrategy template parameter of the LManagedArray class template.

Pre-condition
The array can be cleaned up using the cleanup strategy.
Post-condition
Get() == aPtr
Parameters
aPtrA pointer to the first element of an array of objects of type T - array that can be cleaned up using the cleanup strategy of the the LManagedArray class.

~LManagedArray ( )

~LManagedArray()[inline]

Destructor. When automatic resource management is enabled, the destructor invokes the specified cleanup strategy for the managed pointer.

Member Function Documentation

ReleaseResource ( )

voidReleaseResource()[inline]

If automatic resource management is enabled, the specified cleanup strategy is invoked for the managed pointer and the automatic resource management is then disabled. The underlying pointer is reset to NULL.

Post-condition
Get() == NULL

Swap ( LManagedArray & )

voidSwap(LManagedArray &aArray)[inline]

Unmanage ( )

T *Unmanage()[inline]

Reimplemented from LAutoPtrBase::Unmanage()

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

Return Value
A pointer to the first element of the array of objects of type T.

operator= ( T * )

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

Reimplemented from LAutoPtrBase::operator=(T *)

Assigns a new array of objects of type T to be managed. It needs to be possible use the cleanup strategy of the LManagedArray object for the cleanup of the new managed array. The default cleanup strategy is to delete the heap-allocated array by using array delete (delete[]). If the LManagedArray object already manages an array, then the cleanup strategy is invoked with the managed array before assigning the new managed array.

Pre-condition
The new array to be managed can be cleaned up using the cleanup strategy.
Post-condition
Get() == aPtr
Parameters
aPtrA pointer to the first element of the array of objects of type T - array that can be cleaned up using the cleanup strategy.

operator[] ( TInt )

T &operator[](TIntaIndex)const [inline]

Overloaded subscript operator.

Return Value
A reference to the object of type T at the position aIndex.