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

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of the License "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 MADDRCONT_H

#define MADDRCONT_H

/**

A container for storing objects keyed on a virtual address.

*/

class RAddressedContainer

	{

public:

	/**

	@param aReadLock	Fast mutex used to synchronise read operations,

					 	i.e. the Find functions. This may be the null pointer to

						indicate that extra locking is required.

	@param aWriteLock	Reference to the mutex used to synchronise write operations,

					 	i.e. #Add and Remove functions. This mutex if not used by

						the RAddressedContainer class but it is used for asserting

						correct preconditions in debug builds

	*/

	RAddressedContainer(NFastMutex* aReadLock, DMutex*& aWriteLock);

	~RAddressedContainer();

	/**

	Add an object to the container.

	@param aAddress The address key for the object.

	@param aObject  Pointer to the object to add. This may not be the null pointer.

	@pre The write lock must be held.

	*/

	TInt Add(TLinAddr aAddress, TAny* aObject);

	/**

	Remove an object from the container.

	@param aAddress The address key for the object.

	@return The pointer of the object removed, or the null pointer if there

			was none with the specified address key.

	@pre The write lock must be held.

	*/

	TAny* Remove(TLinAddr aAddress);

	/**

	Find an object in the container.

	@param aAddress The address key for the object.

	@return The pointer of the object found, or the null pointer if there

			was none with the specified address key.

	@pre The read lock must be held, or if there is no read lock, the write lock must be held.

	*/

	TAny* Find(TLinAddr aAddress);

	/**

	Find the object in the container which has the highest value

	address key less-than-or-equal to the specified address.

	@param aAddress The address key to search on.

	@param[out] aOffset Reference to an value which will be set to the difference

						between \a aAddress and the address key of the found object.

	@return The pointer of the object found, or the null pointer if there

			was none matching the search criteria.

	@pre The read lock must be held, or if there is no read lock, the write lock must be held.

	*/

	TAny* Find(TLinAddr aAddress, TUint& aOffset);

	/** Acquire the read lock. */

	FORCE_INLINE void ReadLock()

		{

		if(iReadLock)

			NKern::FMWait(iReadLock);

		}

	/** Release the read lock. */

	FORCE_INLINE void ReadUnlock()

		{

		if(iReadLock)

			NKern::FMSignal(iReadLock);

		}

	/** Flash (release and re-acquire) the read lock. */

	FORCE_INLINE void ReadFlash()

		{

		if(iReadLock)

			NKern::FMFlash(iReadLock);

		}

	/** The number of objects in the container. */

	FORCE_INLINE TUint Count()

		{

		return iCount;

		}

private:

	TUint FindIndex(TLinAddr aAddress);

	TUint CalculateGrow();

	TUint CalculateShrink(TUint aCount);

	TBool CheckWriteLock();

	class TEntry

		{

	public:

		TLinAddr	iAddress;

		TAny*		iObject;

		};

private:

	TUint iMaxCount;

	TUint iCount;

	TEntry* iList;

	NFastMutex* iReadLock;

	DMutex*& iWriteLock;

	};

#endif // MADDRCONT_H