// 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;

/**

@internalComponent

*/

union TUint64HL

	{

	TUint64		i64;

	TUint32		i32[2];

	};

#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

/******************************************************************************

 *

 * SIMPLE DOUBLY-LINKED CIRCULAR LIST

 *

 ******************************************************************************/

/**

	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.

    */

	FORCE_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;

	};

/******************************************************************************

 *

 * ITERABLE DOUBLY-LINKED CIRCULAR LIST

 *

 ******************************************************************************/

/**

@internalComponent

An object that forms part of an iterable doubly linked list.

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

can form part of the doubly linked list.

@see SIterDQ

*/

struct SIterDQ;

struct SIterDQIterator;

struct SIterDQLink

	{

    /**

    Default constructor; only defined for debug builds.

    It initialises the link pointers.

    */

	FORCE_INLINE SIterDQLink() {iNext=iPrev=0;}

	enum

		{

		ENonAddressMask=3u,

		EIterator=1u,

		EAnchor=2u,

		};

	FORCE_INLINE SIterDQLink* Next() const

		{ return (SIterDQLink*)(iNext & ~ENonAddressMask); }

	FORCE_INLINE SIterDQLink* Prev() const

		{ return (SIterDQLink*)(iPrev & ~ENonAddressMask); }

	FORCE_INLINE TBool IsObject() const

		{ return !(iNext & ENonAddressMask); }

	FORCE_INLINE TBool IsIterator() const

		{ return iNext & EIterator; }

	FORCE_INLINE TBool IsAnchor() const

		{ return iNext & EAnchor; }

	FORCE_INLINE void SetNext(SIterDQLink* aNext)

		{ iNext = (iNext & ENonAddressMask) | (TUintPtr(aNext) & ~ENonAddressMask); }

	FORCE_INLINE void SetPrev(SIterDQLink* aPrev)

		{ iPrev = (iPrev & ENonAddressMask) | (TUintPtr(aPrev) & ~ENonAddressMask); }

    /**

    Removes this link item from the doubly linked list.

    @return A pointer to this link item.

    */

	FORCE_INLINE SIterDQLink* Deque()

		{

		SIterDQLink* next = Next();

		SIterDQLink* prev = Prev();

		next->SetPrev(prev);

		prev->SetNext(next);

#ifdef _DEBUG

		SetNext((SIterDQLink*)4);

		SetPrev((SIterDQLink*)4);

#endif

		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(SIterDQLink* aL)

		{

		SIterDQLink* prev = aL->Prev();

		SetNext(aL);

		SetPrev(prev);

		prev->SetNext(this);

		aL->SetPrev(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(SIterDQLink* aL)

		{

		SIterDQLink* next = aL->Next();

		SetPrev(aL);

		SetNext(next);

		next->SetPrev(this);

		aL->SetNext(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.

    */

	FORCE_INLINE TBool Alone() const

		{ return (iNext==iPrev); }

private:

	/**

	Bits 2-31 = Address of the next link item in the list.

	Bit 0 = 1 for iterator, 0 for object

	*/

	TUintPtr iNext;

	/**

	Bits 2-31 = Address of the previous link item in the list.

	Bit 0 = 1 for iterator, 0 for object

	*/

	TUintPtr iPrev;

	friend struct SIterDQ;

	friend struct SIterDQIterator;

	};

/**

@internalComponent

Anchor for an iterable circular doubly linked list of SIterDQLink items.