// Copyright (c) 1998-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\dfcs.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 __DFCS_H__

 #define __DFCS_H__

 #include <nklib.h>

 class NThreadBase;

 class NThread;

 class NFastSemaphore;

 class NFastMutex;

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

  * Delayed function call queue

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

 /**

 @publishedPartner

 @released

 The number of DFC priorities the system has, which range from 0

 to KNumDfcPriorities - 1.

 */

 const TInt KNumDfcPriorities=8;

 /**

 @publishedPartner

 @released

 The highest priority level for a DFC, which is equal to KNumDfcPriorities + 1.

 */

 const TInt KMaxDfcPriority=KNumDfcPriorities-1;

 class TDfc;

 /**

 @publishedPartner

 @released

 Defines a DFC queue.

 Each DFC queue is associated with a thread.

 @see TDfc

 */

 class TDfcQue : public TPriList<TDfc,KNumDfcPriorities>

 	{

 public:

 	IMPORT_C TDfcQue();

 	inline TBool IsEmpty();		/**< @internalComponent */

 	static void ThreadFunction(TAny* aDfcQ);

 public:

 	NThreadBase* iThread;		/**< @internalComponent */

 	};

 /**

 @internalComponent

 */

 inline TBool TDfcQue::IsEmpty()

 	{ return (iPresent[0]==0); }

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

  * Delayed function call

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

 /**

 @publishedPartner

 @released

 The function type that can be set to run as a DFC or IDFC.

 @see TDfc

 */

 typedef void (*TDfcFn)(TAny*);

 /**

 @publishedPartner

 @released

 Defines a Deferred Function Call (DFC) or Immediate Deferred Function Call (IDFC).

 A DFC is a kernel object that specifies a function to be run in a thread,

 which is processing a DFC queue. A DFC is added to a DFC queue that is 

 associated with a given thread, where it is cooperatively scheduled with other

 DFCs on that queue.  Queued DFCs are run in order of their priority, followed

 by the order they where queued.  When the DFC gets to run, the function is run

 kernel side, and no other DFC in this queue will get to run until it 

 completes. A DFC can be queued from any context.

 An IDFC is run as soon as the scheduler is next run, which is during the IRQ

 postamble if queued from an ISR; when the currently-running IDFC completes if

 queued from an IDFC; or when the kernel is next unlocked if queued from thread

 context.  Unlike a DFC, the IDFC is not run from a thread context, and its

 execution time must be much smaller.  For these reasons, IDFCs are rarely used

 directly, but are used for implementation of the kernel and RTOS personality

 layers.  An important use of IDFCs is in the implementation of queuing DFCs from

 an ISR context.  IDFCs are run with interrupts enabled but the kernel locked.

 */

 class TDfc : public TPriListLink

 	{

 	// iPriority<KNumDfcPriorities => DFC, otherwise IDFC

 	// iSpare2!=0 if on final queue, 0 if not queued or on pending queue

 	// iSpare3!=0 if on pending or final queue, 0 if not queued

 public:

 	IMPORT_C TDfc(TDfcFn aFunction, TAny* aPtr);									// create IDFC

 	IMPORT_C TDfc(TDfcFn aFunction, TAny* aPtr, TInt aPriority);					// create DFC, queue to be set later

 	IMPORT_C TDfc(TDfcFn aFunction, TAny* aPtr, TDfcQue* aDfcQ, TInt aPriority);	// create DFC

 	IMPORT_C TBool Add();						// call from ISR or IDFC or thread with kernel locked

 	IMPORT_C TBool Cancel();					// call from anywhere except ISR

 	IMPORT_C TBool Enque();						// call from thread

 	IMPORT_C TBool Enque(NFastMutex* aMutex);	// call from thread, signal fast mutex (anti-thrash)

 	IMPORT_C TBool DoEnque();					// call from IDFC or thread with kernel locked

 	IMPORT_C TBool RawAdd();					// same as Add() but without checks for 'correct' usage or other instrumentation

 	IMPORT_C TBool QueueOnIdle();				// queue the DFC to be run when the system goes idle

 	IMPORT_C NThreadBase* Thread();				// thread on which DFC runs, NULL for IDFC

 	void DoEnqueFinal();

 	inline TBool Queued();

 	inline TBool IsIDFC();

 	inline TBool TestAndSetQueued();			/**< @internalComponent */

 	inline void SetDfcQ(TDfcQue* aDfcQ);

 	inline void SetFunction(TDfcFn aDfcFn);

 	inline void SetPriority(TInt aPriority);	/**< @internalComponent */

 public:

 	TAny* iPtr;			/**< @internalComponent */

 	TDfcFn iFunction;	/**< @internalComponent */

 	TDfcQue *iDfcQ;		/**< @internalComponent */

 	};

 /**

 @publishedPartner

 @released

 Used to find out if the DFC/IDFC is queued on either the pending or final DFC queue.

 @return TRUE if the DFC/IDFC is queued, otherwise FALSE.

 */

 inline TBool TDfc::Queued()

 	{ return iSpare3; }

 /**

 @publishedPartner

 @released

 Determines if the object represents a DFC or an IDFC.

 @return TRUE if this represents an IDFC, otherwise FALSE meaning it is a DFC.

 */

 inline TBool TDfc::IsIDFC()

 	{ return iPriority>=KNumDfcPriorities; }

 /**

 @publishedPartner

 @released

 Sets the DFC queue that the DFC is to added to and executed by.

 Note that this function should only be used in the initialisation of the DFC, 

 when it is not on any queue.  This function does not move the DFC from one 

 queue to another.

 @param aDfcQ

 	The DFC queue that the DFC is to be added to and executed by.

 */

 inline void TDfc::SetDfcQ(TDfcQue* aDfcQ)

 	{ iDfcQ=aDfcQ; }

 /**

 @publishedPartner

 @released

 Sets the function that is run when the DFC/IDFC is scheduled.

 @param aDfcFn

 	The function that the DFC/IDFC runs when it is scheduled.

 */

 inline void TDfc::SetFunction(TDfcFn aDfcFn)

 	{ iFunction=aDfcFn; }

 /**

 @internalComponent

 */

 inline void TDfc::SetPriority(TInt aPriority)

 	{ iPriority = (TUint8)aPriority; }

 #ifdef __INCLUDE_TDFC_DEFINES__

 #define	iOnFinalQ		iSpare2

 #define	iQueued			iSpare3

 #endif

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

  * Kernel-side asynchronous request,

  * based on DFC queueing

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

 class TAsyncRequest : protected TDfc

 	{

 public:

 	IMPORT_C void Send(TDfc* aCompletionDfc);

 	IMPORT_C void Send(NFastSemaphore* aCompletionSemaphore);

 	IMPORT_C TInt SendReceive();

 	IMPORT_C void Cancel();

 	IMPORT_C void Complete(TInt aResult);

 	inline TBool PollForCancel()

 		{ return iCancel; }

 protected:

 	IMPORT_C TAsyncRequest(TDfcFn aFunction, TDfcQue* aDfcQ, TInt aPriority);

 protected:

 	TAny*	iCompletionObject;

 	volatile TBool	iCancel;

 	TInt	iResult;

 	};

 #endif