/*
* 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_