/*

 * Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies).

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of "Eclipse Public License v1.0"

 * which accompanies this distribution, and is available

 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description: 

 *

 */

 #ifndef UNIQUEINSTANCE_H_

 #define UNIQUEINSTANCE_H_

 #include "UniqueInstanceBase.h"

 // A user may only create and destroy the repository. All access is through the

 // RUniqueInstance class.

 //

 // Please note : Deleting the repository is unsafe unless all of its owned

 // objects have been destroyed or relinquished. If objects exist in the repository

 // (and provided that no RUniqueInstance objects have leaked) it follows that

 // there must be RUniqueInstance objects around that still reference these objects.

 // These RUniqueInstances will at some point try to access the repository to

 // relinquish or destroy these objects, but it will have been deleted! Therefore

 // the destructor panics if there are any objects in the repository.

 //

 // The compare function and copy function must co-operate like this:

 // A) aCompare is a total order. That is, for all valid objects of type T t, u and v:

 //	i)	aCompare(t, t) == 0									(idempotency)

 //	ii)	if aCompare(t, u) < 0 then aCompare(u, t) > 0		(associativity)

 //	iii)if aCompare(t, u) < 0 and aCompare(u, v) < 0 then aCompare(t, v) < 0

 //															(transitivity)

 // B) aCopyL always produces objects that compare equal to the arguments that

 //		produced them, that is for all valid objects of type T t:

 //	aCompare(t, aCopyL(t, sizeof(T))) == 0			(ignoring the memory leak!)

 // If these conditions are not met, the behaviour of the repository is undefined.

 // If the type does not own anything and does not have variable length, the

 // copy and delete functions can be omitted.

 //

 // The operation of the repository and its clients is not thread safe.

 //

 // For aMaxLinks give half the log(base 2) of the expected maximum size of the

 // repository. So for a repository of size 256, use 4. For size 65535 use 8. For

 // 16777216 use 12.

 /**

 Store of objects that coalesces repeated instances.

 @since App-frameworks6.1

 @internalComponent

 */

 template <typename T> class CUniqueInstanceRepository

 	: public UniqueInstance::CUniqueInstanceRepositoryBase

 	{

 public:

 	// typical implementation might be:

 	//	void CompareT(const T* aL, const T* aR)

 	//		{

 	//		if (*aL == *aR)

 	//			return 0;

 	//		if (*aL < *aR)

 	//			return -1;

 	//		return 1;

 	//		}

 	typedef TInt TCompareFnType(const T*, const T*);

 	// typical implementation might be:

 	//	void DeleteT(T* aDestroy)

 	//		{

 	//		delete aDestroy;

 	//		}

 	typedef void TDeleteFnType(T* aObjectToBeDestroyed);

 	// typical implementation might be:

 	//	T* CopyT(const T* aSrc, TInt aOffset, TInt)

 	//		{

 	//		return new(ELeave) T(*aSrc);

 	//		}

 	typedef T* TCopyFnTypeL(const T* aTToBeCopied, TInt aSizeOfT);

 	/**

 	 * Creates a new empty repository. aCompare must define a total order on

 	 * objects that may be added to the repository. In other words

 	 * aCompare(a,b) == 0 iff a and b are equivalent, aCompare(a,b) < 0

 	 * iff aCompare(a,b) > 0, aCompare(a,b) < 0 iff aCompare(b,a) < 0 and

 	 * aCompare(a,b) < 0 && aCompare(b,c) < 0 implies that aCompare(a,c) < 0.

 	 * aDelete(a) deletes a and aCopyL(a) generates a new object such that

 	 * aCompare(aCopyL(a),a) == 0.

 	 * aMaxLinks concerns the space against speed tradeoff of the

 	 * implementation. It should be a number greater than half log2 of the

 	 * expected maximum size of the repository.

 	 */

 	static inline CUniqueInstanceRepository<T>* NewL(TCompareFnType* aCompare,

 		TDeleteFnType* aDelete, TCopyFnTypeL* aCopyL, TInt aMaxLinks = 10);

 	static inline CUniqueInstanceRepository<T>* NewLC(TCompareFnType* aCompare,

 		TDeleteFnType* aDelete, TCopyFnTypeL* aCopyL, TInt aMaxLinks = 10);

 	/**

 	 * Creates a new empty repository with aDelete(a) simply freeing memory

 	 * at a and aCopyL(a) simply bitwise copying the memory occupied by a.

 	 * This is suitable only if T has no destructor and only the automatic

 	 * copy constructor.

 	 */

 	static inline CUniqueInstanceRepository<T>* NewL(TCompareFnType* aCompare,

 		TInt aMaxLinks = 10);

 	static inline CUniqueInstanceRepository<T>* NewLC(TCompareFnType* aCompare,

 		TInt aMaxLinks = 10);

 private:

 	CUniqueInstanceRepository() {}

 	};

 /**

 Specialization for the odd semantics of TDes. Copy/Delete/Compare functions

 are provided free.

 @since App-frameworks6.1

 @internalComponent

 */

 template <> class CUniqueInstanceRepository<TDes>

 	: public UniqueInstance::CUniqueInstanceRepositoryBase

 	{

 	CUniqueInstanceRepository() {}

 	static void* DesCopyL(void*, TInt);

 	static TInt DesCompare(void*, void*);

 	static void DesDelete(void*);

 public:

 	static inline CUniqueInstanceRepository<TDes>* NewL(TInt aMaxLinks = 10);

 	static inline CUniqueInstanceRepository<TDes>* NewLC(TInt aMaxLinks = 10);

 	};

 /**

 Client of a CUniqueInstanceRepository.

 Holds a single object, which may be shared.

 @since App-frameworks6.1

 @internalComponent

 */

 template <typename T> class RUniqueInstance

 	{

 public:

 	inline explicit RUniqueInstance(CUniqueInstanceRepository<T>& aRepository)

 		: iImpl(aRepository) {}

 	/**

 	 * Destructor. In debug builds this asserts that no object is owned.

 	 */

 	inline ~RUniqueInstance() {}

 	/**

 	 * Registers the argument as a unique instance, to be referenced by this

 	 * RUniqueInstance. Any previously owned object is destroyed.

 	 */

 	inline void TakeL(T* aToAdd);

 	/**

 	 * Makes a copy of the argument, as a unique instance. The argument is

 	 * still owned by the caller

 	 */

 	inline void TakeCopyL(const T* aToCopy);

 	/**

 	 * Returns a pointer to the referenced object without passing ownership

 	 */

 	inline const T* Peek() const;

 	/**

 	 * Makes another instance of the same object: both have ownership

 	 */

 	inline void CopyTo(RUniqueInstance<T>& aOther) const;

 	/**

 	 * Pass ownership of the owned object to another RUniqueInstance.

 	 * This object may not be referenced through this RUniqueInstance any

 	 * more, only through aOther.

 	 */

 	inline void MoveTo(RUniqueInstance<T>& aOther);

 	/**

 	 * Relinquishes ownership of the object to the caller. The object is

 	 * not destroyed. It may not be referenced through this RUniqueInstance

 	 * any more. The pointer returned may be different from that passed

 	 * to TakeL() or returned from Peek()

 	 */

 	inline T* DropL();

 	/**

 	 * Releases the owned object.

 	 */

 	inline void Close();

 private:

 	UniqueInstance::RInstanceImpl iImpl;

 	};

 /**

 Specialization of RUniqueInstance for the odd semantics of TDes.

 Any descriptor that needs ownership to be passed around is an HBufC.

 Any time a copy or view over a descriptor is required, a const TDesC

 is used. Please note the different signature of NewL and NewLC. This is

 because copy, delete and compare functions are provided for free.

 @since App-frameworks6.1

 @internalComponent

 */

 TEMPLATE_SPECIALIZATION class RUniqueInstance<TDes>

 	{

 public:

 	inline explicit RUniqueInstance(CUniqueInstanceRepository<TDes>& aRepository)

 		: iImpl(aRepository) {}

 	inline ~RUniqueInstance() {}

 	inline void TakeL(HBufC* aToAdd);

 	inline void TakeCopyL(const TDesC* aToCopy);

 	inline const TDesC* Peek() const;

 	inline void CopyTo(RUniqueInstance<TDes>& aOther) const;

 	inline void MoveTo(RUniqueInstance<TDes>& aOther);

 	inline HBufC* DropL();

 	inline void Close();

 private:

 	UniqueInstance::RInstanceImpl iImpl;

 	};

 template <typename T>

 inline CUniqueInstanceRepository<T>* CUniqueInstanceRepository<T>::NewLC(

 	typename CUniqueInstanceRepository<T>::TCompareFnType* aCompare,

 	typename CUniqueInstanceRepository<T>::TDeleteFnType* aDelete,

 	typename CUniqueInstanceRepository<T>::TCopyFnTypeL* aCopyL, TInt aMaxLinks)

 	{

 	CUniqueInstanceRepository<T>* that = new(ELeave) CUniqueInstanceRepository<T>;

 	CleanupStack::PushL(that);

 	that->ConstructL(reinterpret_cast<UniqueInstance::TCompareFn*>(aCompare),

 		reinterpret_cast<UniqueInstance::TDeleteFn*>(aDelete),

 		reinterpret_cast<UniqueInstance::TCopyFnL*>(aCopyL), aMaxLinks,

 		sizeof(T));

 	return that;

 	}

 template <typename T>

 inline CUniqueInstanceRepository<T>* CUniqueInstanceRepository<T>::NewL(

 	typename CUniqueInstanceRepository<T>::TCompareFnType* aComp,

 	typename CUniqueInstanceRepository<T>::TDeleteFnType* aDel,

 	typename CUniqueInstanceRepository<T>::TCopyFnTypeL* aCopyL, TInt aMaxLinks)

 	{

 	CUniqueInstanceRepository<T>* that = NewLC(aComp, aDel, aCopyL, aMaxLinks);

 	CleanupStack::Pop(that);

 	return that;

 	}

 template <typename T>

 inline CUniqueInstanceRepository<T>* CUniqueInstanceRepository<T>::NewLC(

 	typename CUniqueInstanceRepository<T>::TCompareFnType* aCompare, TInt aMaxLinks)

 	{

 	CUniqueInstanceRepository<T>* that = new(ELeave) CUniqueInstanceRepository<T>;

 	CleanupStack::PushL(that);

 	that->ConstructL(reinterpret_cast<UniqueInstance::TCompareFn*>(aCompare),

 		DumbDelete, DumbCopyL, aMaxLinks,

 		sizeof(T));

 	return that;

 	}

 template <typename T>

 inline CUniqueInstanceRepository<T>* CUniqueInstanceRepository<T>::NewL(

 	typename CUniqueInstanceRepository<T>::TCompareFnType* aComp, TInt aMaxLinks)

 	{

 	CUniqueInstanceRepository<T>* that = NewLC(aComp, aMaxLinks);

 	CleanupStack::Pop(that);

 	return that;

 	}

 inline CUniqueInstanceRepository<TDes>* CUniqueInstanceRepository<TDes>::NewLC(

 	TInt aMaxLinks)

 	{

 	CUniqueInstanceRepository<TDes>* that = new(ELeave) CUniqueInstanceRepository<TDes>;

 	CleanupStack::PushL(that);

 	that->ConstructL(DesCompare, DesDelete, DesCopyL, aMaxLinks, 1);

 	return that;

 	}

 inline CUniqueInstanceRepository<TDes>* CUniqueInstanceRepository<TDes>::NewL(

 	TInt aMaxLinks)

 	{

 	CUniqueInstanceRepository<TDes>* that = NewLC(aMaxLinks);

 	CleanupStack::Pop(that);

 	return that;

 	}

 ///////////////////////////////

 //							 //

 //	RUniqueInstance inlines  //

 //							 //

 ///////////////////////////////

 template <typename T> inline

 void RUniqueInstance<T>::TakeL(T* aToAdd)

 	{ iImpl.TakeL(aToAdd); }

 template <typename T> inline

 void RUniqueInstance<T>::TakeCopyL(const T* aToCopy)

 	{ iImpl.TakeCopyL(const_cast<T*>(aToCopy)); }

 template <typename T> inline

 const T* RUniqueInstance<T>::Peek() const

 	{ return reinterpret_cast<const T*>(iImpl.Peek()); }

 template <typename T> inline

 void RUniqueInstance<T>::CopyTo(RUniqueInstance<T>& aOther) const

 	{ iImpl.CopyTo(aOther.iImpl); }

 template <typename T> inline

 void RUniqueInstance<T>::MoveTo(RUniqueInstance<T>& aOther)

 	{ iImpl.MoveTo(aOther.iImpl); }

 template <typename T> inline

 T* RUniqueInstance<T>::DropL()

 	{ return reinterpret_cast<T*>(iImpl.DropL()); }

 template <typename T> inline

 void RUniqueInstance<T>::Close()

 	{ iImpl.Close(); }

 inline void RUniqueInstance<TDes>::TakeL(HBufC* aToAdd)

 	{ iImpl.TakeL(aToAdd); }

 inline void RUniqueInstance<TDes>::TakeCopyL(const TDesC* aToCopy)

 	{ iImpl.TakeCopyL(const_cast<TDesC*>(aToCopy)); }

 inline const TDesC* RUniqueInstance<TDes>::Peek() const

 	{ return reinterpret_cast<HBufC*>(iImpl.Peek()); }

 inline void RUniqueInstance<TDes>::CopyTo(RUniqueInstance<TDes>& aOther) const

 	{ iImpl.CopyTo(aOther.iImpl); }

 inline void RUniqueInstance<TDes>::MoveTo(RUniqueInstance<TDes>& aOther)

 	{ iImpl.MoveTo(aOther.iImpl); }

 inline HBufC* RUniqueInstance<TDes>::DropL()

 	{ return reinterpret_cast<HBufC*>(iImpl.DropL()); }

 inline void RUniqueInstance<TDes>::Close()

 	{ iImpl.Close(); }

 #endif	// UNIQUEINSTANCE_H_