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

		IShThreadUtilities.h

		Copyright: (c) 2001 Eovia Corp. All rights reserved.
		
		Author:	Emil
		Date:	3/2/98

		Revision History

		when		who			what & why
		==========	==========	======================================================

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

#ifndef __IShThreadUtilities__
#define __IShThreadUtilities__

#if CP_PRAGMA_ONCE
#pragma once
#endif

#include "ComTypes.h"

//******************************* Globally Unique Ids ***********************************

MCDEFINE_GUID_H(IID_IShThreadUtilities);
MCDEFINE_GUID_H(IID_IExThread);

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




/// \addtogroup ExternalInterface
/// \{

// ****************************************************************************
//								IExThread
// 
/// Thread Object  (cooperative with the app and other IExThread(S)
/// Note: You should derive your thread object from TBasicThread
/// 
struct IExThread : public IMCUnknown
{
	virtual MCCOMErr MCCOMAPI Work			() = 0;
};

/// \}

/// \addtogroup Utilities
/// \{

struct IExThreadRemoteInstruction : public IMCUnknown
{
	virtual MCCOMErr		MCCOMAPI Execute() = 0;
};

// ****************************************************************************
//					IShThreadUtilities			
// 
// -Description:
//
/// Thread Manager Object. This utilities offer a number of functions to deal with
/// cooperative threads (non-preemtive).
struct IShThreadUtilities : public IMCUnknown
{
	// ****************************************************************************
	//								LaunchThread
	// 
	// -Description:
	//
	// Launch a new thread.
	//
	// -Parameters:
	//
	// inthread			: a pointer to the thread that you want to launch
	// stackSize		: the size of the stack that should be created for this thread
	// -Returns:
	//
	virtual int32	 MCCOMAPI LaunchThread	(IExThread* inthread, uint32 stackSize) = 0;

	// ****************************************************************************
	//								KillThread
	// 
	// -Description:
	//
	// Kills the current thread. This method cause the YieldProcesses to throw an
	// a kAbortThreadException exception.
	//
	// -Parameters:
	//
	// threadID			: the ID of the thread to be killed
	//
	virtual MCCOMErr MCCOMAPI KillThread	(int32 inthreadID) = 0;

	// ****************************************************************************
	//								YieldProcesses
	// 
	// -Description:
	//
	// Yield to another cooperative thread if the current thread has used more than
	// the time specified.
	//
	// Note that this function will throw an exception (kAbortThreadException) if the
	// thread should abort. You should make sure that your call properly handles the
	// exception.
	//
	// -Parameters:
	//
	// -Returns:
	//
	virtual MCCOMErr MCCOMAPI YieldProcesses			(uint32 ticks) = 0;

	virtual boolean	 MCCOMAPI Exists		(int32 inthreadID) = 0;
	virtual boolean	 MCCOMAPI IsMainThread	() = 0;
	virtual int32	 MCCOMAPI CurrentThreadID() = 0;

	virtual MCCOMErr MCCOMAPI RemoteInstruction(IExThreadRemoteInstruction* instruction, boolean returnImmediately=false) = 0;
};

/// \}

#endif