// Copyright (c) 1995-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:

// e32\include\nkern\nklib.h

// 

// WARNING: This file contains some APIs which are internal and are subject

//          to change without notice. Such APIs should therefore not be used

//          outside the Kernel and Hardware Services package.

//

#ifndef __NKLIB_H__

#define __NKLIB_H__

#include <e32err.h>

#include <nk_cpu.h>

#ifndef __KERNEL_MODE__

#error Including kernel header in user code

#endif

#if defined(__GCC32__)

/**

@publishedPartner

@released

64-bit signed integer type.

*/

typedef long long Int64;

/**

@publishedPartner

@released

64-bit unsigned integer type.	

*/

typedef unsigned long long Uint64;

#elif defined(__VC32__)

typedef __int64 Int64;

typedef unsigned __int64 Uint64;

#elif defined(__CW32__)

#pragma longlong on

typedef long long Int64;

typedef unsigned long long Uint64;

#endif

/**

@publishedPartner

@released

Defines a 64-bit time value. 

*/

typedef Int64 TTimeK;

#if defined(__VC32__) || defined(__CW32__)

extern "C"

/** @internalComponent */

__NORETURN__ void abort();

#endif

#ifndef __PLACEMENT_NEW_INLINE

#define __PLACEMENT_NEW_INLINE

// Global placement operator new

/** @internalComponent */

inline TAny* operator new(TUint /*aSize*/, TAny* aBase) __NO_THROW

	{return aBase;}

// Global placement operator delete

/** @internalComponent */

inline void operator delete(TAny* /*aPtr*/, TAny* /*aBase*/) __NO_THROW

	{}

#endif //__PLACEMENT_NEW_INLINE

#ifndef __PLACEMENT_VEC_NEW_INLINE

#define __PLACEMENT_VEC_NEW_INLINE

// Global placement operator new[]

/** @internalComponent */

inline TAny* operator new[](TUint /*aSize*/, TAny* aBase) __NO_THROW

	{return aBase;}

// Global placement operator delete[]

/** @internalComponent */

inline void operator delete[](TAny* /*aPtr*/, TAny* /*aBase*/) __NO_THROW

	{}

#endif //__PLACEMENT_VEC_NEW_INLINE

/**

	Macro to offset a SDblQueLink pointer back to the base of a class containing it

	@publishedPartner

	@released

*/

#define _LOFF(p,T,f) ((T*)(((TUint8*)(p))-_FOFF(T,f)))

#ifdef _DEBUG

/** @internalComponent */

#define KILL_LINK_VALUE (SDblQueLink*)0xdfdfdfdf

/** @internalComponent */

#define KILL_LINK(l)	(l)->iNext=(l)->iPrev=KILL_LINK_VALUE

#else

#define KILL_LINK(l)

#endif

#ifdef __ARMCC__

#define FORCE_INLINE __forceinline

#else

#define FORCE_INLINE inline

#endif

/**

@publishedPartner

@released

An object that forms part of a doubly linked list.

SDblQueLink can also be embedded within another object so that that object

can form part of the doubly linked list.

@see SDblQue

*/

struct SDblQueLink

	{

#ifdef _DEBUG

    /**

    Default constructor; only defined for debug builds.

    It initialises the link pointers.

    */

	FORCE_INLINE SDblQueLink() {iNext=iPrev=NULL;}

#endif

    /**

    Removes this link item from the doubly linked list.

    @return A pointer to this link item.

    */

	FORCE_INLINE SDblQueLink* Deque()

		{

		SDblQueLink* next = iNext;

		SDblQueLink* prev = iPrev;

		next->iPrev=prev;

		prev->iNext=next;

		KILL_LINK(this);

		return this;

		}

    /**

    Inserts this link item into the list so that it precedes the specified link item.

    @param aL A pointer to the link item which is to follow this link item.

    */

	FORCE_INLINE void InsertBefore(SDblQueLink* aL)

		{

		SDblQueLink* prev = aL->iPrev;

		iNext=aL;

		iPrev=prev;

		prev->iNext=this;

		aL->iPrev=this;

		}

	/**

	Inserts this link item into the list so that it follows the specified link item.

    @param aL A pointer to the link item which is to precede this link item.

    */

	FORCE_INLINE void InsertAfter(SDblQueLink* aL)

		{

		SDblQueLink* next = aL->iNext;

		iPrev=aL;

		iNext=next;

		next->iPrev=this;

		aL->iNext=this;

		}

	/**

	Tests whether this is the only link item in the list.

	@return True, if this is the only link item in the list; false, otherwise.

    */

	inline TBool Alone() const

		{ return (iNext==iPrev); }

    /**

    Pointer to the next link item in the list.

    */

	SDblQueLink* iNext;

	/**

    Pointer to the previous link item in the list.

    */

	SDblQueLink* iPrev;

	};

/**

@publishedPartner

@released

Anchor for a doubly linked list of SDblQueLink items.

@see SDblQueLink

*/

struct SDblQue

	{

	/**

	Default constructor.

	*/

	FORCE_INLINE SDblQue()

		{ iA.iNext=iA.iPrev=&iA; }

	/**

	Moves link items from the specified list onto this list, and clears the specified list

	@param aQ The source linked list. This list must not be empty.

	*/	

	inline SDblQue(SDblQue* aQ, TInt)		// move entries from aQ onto this queue and clear aQ - aQ must not be empty

		{ new (this) SDblQue(*aQ); iA.iNext->iPrev=&iA; iA.iPrev->iNext=&iA; new (aQ) SDblQue; }

	/**

	Tests whether this doubly linked list is empty.

	@return True, if the list is empty; false, otherwise.

	*/

	FORCE_INLINE TBool IsEmpty() const

		{ return (iA.iNext==&iA); }

    /**

    Gets a pointer to the first item in this doubly linked list.

    @return A pointer to the first item.

    */		

	FORCE_INLINE SDblQueLink* First() const

		{ return iA.iNext; }

    /**

    Gets a pointer to the last item in this doubly linked list.

    @return A pointer to the last item.

    */		

	FORCE_INLINE SDblQueLink* Last() const

		{ return iA.iPrev; }

	/**

	Adds the specified link item onto the end of this doubly linked list.

	@param aL A pointer to the link item to be added.

	*/

	FORCE_INLINE void Add(SDblQueLink* aL)

		{

		SDblQueLink* prev = iA.iPrev;

		aL->iNext=&iA;

		aL->iPrev=prev;

		prev->iNext=aL;

		iA.iPrev=aL;

		}

	/**

	Adds the specified link item onto the front of this doubly linked list.

	@param aL A pointer to the link item to be added.

	*/

	FORCE_INLINE void AddHead(SDblQueLink* aL)

		{

		SDblQueLink* next = iA.iNext;

		aL->iNext=next;

		aL->iPrev=&iA;

		next->iPrev=aL;

		iA.iNext=aL;

		}

	/**

    Removes the last link item from the linked list and adds it to the front

    of the list. 

	*/

	inline void Rotate()

		{ SDblQueLink* pL=iA.iPrev; pL->Deque(); AddHead(pL); }

	/**

	Gets the first link item in the linked list.

	@return The first link item in the list; NULL, if the list is empty.

	*/

	inline SDblQueLink* GetFirst()

		{ if (IsEmpty()) return NULL; else return First()->Deque(); }

	/**

	Gets the last link item in the linked list.

	@return The last link item in the list; NULL, if the list is empty.

	*/

	inline SDblQueLink* GetLast()

		{ if (IsEmpty()) return NULL; else return Last()->Deque(); }

	/**

	Appends entries from the specified linked list onto this list, and clears

	the specified link list anchor.

	@param aQ The source linked list.

	*/

	inline void MoveFrom(SDblQue* aQ)	// append entries from aQ onto this queue and clear aQ

		{ if (!aQ->IsEmpty())

			{iA.iPrev->iNext=aQ->iA.iNext; aQ->iA.iNext->iPrev=iA.iPrev; iA.iPrev=aQ->iA.iPrev; iA.iPrev->iNext=&iA; new (aQ) SDblQue; }

		}

    /**

    The anchor point for the doubly linked list.

    */

	SDblQueLink iA;

	};

/**

@publishedPartner

@released

An object that forms part of a doubly linked list arranged

in descending key order.

@see SOrdQue

*/

struct SOrdQueLink : public SDblQueLink

	{

	/**

	The key value used to order the link item.

	*/

	TInt iKey;

	};

/**

@publishedPartner

@released

Anchor for a doubly linked list of SOrdQueLink items.

The items in this linked list are in descending key order.

@see SOrdQueLink

*/

struct SOrdQue : public SDblQue

	{

	/**

	Adds the specified link item into this doubly linked list so that

	the list remains in descending key order.

	@param aL A pointer to the link item to be added.

	*/

	inline void Add(SOrdQueLink* aL)

		{

		SOrdQueLink* pQ=(SOrdQueLink*)iA.iNext;

		TInt k=aL->iKey;

		while(pQ!=&iA && (pQ->iKey>=k)) pQ=(SOrdQueLink*)pQ->iNext;

		aL->InsertBefore(pQ);

		}

	};

/**

@publishedPartner

@released

An object that forms part of a doubly linked list arranged

in 'delta' order.

The item represents some value that is an increment, or delta,

on the value represented by a preceding element.

@see SDeltaQue

*/

struct SDeltaQueLink : public SDblQueLink

	{

	/**

	The delta value.

	*/

	TInt iDelta;

	};

/**

@publishedPartner

@released

Anchor for a doubly linked list of SDeltaQueLink items.

An item in this linked list represents a value that is an increment,

or a delta, on the value represented by a preceding element.

The list is ordered so that the head of the queue represents a nominal zero point.

@see SDeltaQueLink

*/

struct SDeltaQue : public SDblQue

	{

	/**

	Gets the delta value of the first link item in the list.

    @return The delta value.

	*/

	inline TInt FirstDelta() const

		{return ((SDeltaQueLink*)First())->iDelta;}

    /**

    Decrements the delta value of the first item in the list by the specified value.

    @param aCount The amount by which the delta value is to be reduced.

    @return True, if the resulting delta value is negative or zero;

            false, if the value is positive.

    */		

	inline TBool CountDown(TInt aCount)

		{SDeltaQueLink& l=*(SDeltaQueLink*)First(); return((l.iDelta-=aCount)<=0);}

	/**

	Adds the specified list item, having the specified 'distance' from

	the nominal zero point, into the list.

    The item is added into the list, the adjacent delta values are adjusted,

    and a suitable delta value assigned to the new item so that

    the new item is at the specified 'distance' from the nominal zero point.

    @param aL     The item to be inserted. 

    @param aDelta The 'distance' of the item from the nominal zero point.

	*/

	inline void Add(SDeltaQueLink* aL, TInt aDelta)

		{

		SDeltaQueLink* pQ=(SDeltaQueLink*)iA.iNext;

		while(pQ!=&iA && aDelta>=pQ->iDelta)

			{ aDelta-=pQ->iDelta; pQ=(SDeltaQueLink*)pQ->iNext; }

		aL->iDelta=aDelta;

		aL->InsertBefore(pQ);

		if (pQ!=&iA) pQ->iDelta-=aDelta;

		}

	/**

	Removes the specified link item from the list.

	The delta value of the item following the removed item is adjusted

	so that its 'distance' from the nominal zero point remains the same.

	@param aL The list item to be removed.

	@return A pointer to the item removed from the queue.

	*/

	inline SDeltaQueLink* Remove(SDeltaQueLink* aL)

		{

		if (aL->iNext!=&iA)

			{

			SDeltaQueLink& next=*(SDeltaQueLink*)aL->iNext;

			next.iDelta+=aL->iDelta;

			}

		return (SDeltaQueLink*)aL->Deque();

		}

    /**

    Removes the first item from the linked list if its delta value

    is zero or negative.

    @return A pointer to the item removed from the linked list.

            This is NULL, if the first element has a positive delta value,