CGUIThread Class Reference

This is the base class for Guiliani threads. More...

#include <GUIThread.h>

Inheritance diagram for CGUIThread:

Public Member Functions
void *	GetArg () const
ThreadPriority_t	GetPriority ()
void *	GetThreadId () const
void	InitShutdown ()
eC_Bool	IsRunning () const
eC_Bool	IsShutdownCompleted () const
void	SetArg (void *pArg)
void	SetPriority (const ThreadPriority_t &ePriority)
eC_Int	Start (void *pArg)
void	Terminate ()
void	WaitForShutdown ()

Protected Member Functions
	CGUIThread (const eC_UInt &uiStackSize)
virtual	~CGUIThread ()
virtual void	Cleanup ()
virtual void	Execute (void *pArg)=0
ThreadPriority_t	MapPriority (const eC_Int &iPriority)
eC_Int	MapPriority (const ThreadPriority_t &ePriority)
virtual void	Setup ()

Protected Attributes
volatile eC_Bool	m_bRunning
	Whether this thread is currently running.
void *	m_pArg
	Pointer to arguments to be passed to the thread.
void *	m_pThreadId
	This thread's unique ID.
eC_UInt	m_uiStackSize
	Size for this thread's stack.

Detailed Description

This is the base class for Guiliani threads.

Derive from this class if you want to create user threads and implement at least the Execute() method. Additionally, you may implement Setup() and Cleanup() to suit your needs.

Notes for porting Guiliani

The implementation of this base class in the Guiliani core only provides the platform-independent methods. When porting Guiliani to a new platform, the following methods of CGUIThread have to be implemented:

• Start()
• Terminate()
• SetPriority() and GetPriority()
• MapPriority(const ThreadPriority_t&) and MapPriority(const eC_Int&)
• WaitForShutdown()

Thread class example:

class CExampleThread:
    public CGUIThread
{
public:
    CExampleThread():CGUIThread(1000) {}
 
private:
    void Setup() {}
    void Execute(void *pArg)
    {
        GUILOG(GUI_TRACE_DEBUG, "Parameter: "+eC_String(*(static_cast<eC_UInt*>(pArg)))+".\n");
        for (eC_UInt i=0; i < *(static_cast<eC_UInt*>(pArg)); i++)
        {
            GUILOG(GUI_TRACE_DEBUG, "ExampleThread: "+eC_String(i)+".\n");
            eC_Wait(5000);
        }
    }
    void Cleanup() {}
};

Create and execute thread example:

CExampleThread *pThread = new CExampleThread();
eC_UInt uiParam = 10;
pThread->Start((void*)&uiParam);

Constructor & Destructor Documentation

CGUIThread()

CGUIThread::CGUIThread ( const eC_UInt &  uiStackSize )

protected

Protected contructor, because it should only be called by derived classes.

Parameters

uiStackSize

The stack size for the new thread in bytes

~CGUIThread()

virtual CGUIThread::~CGUIThread ( )

protectedvirtual

Virtual protected destructor, because it should only be called by derived classes.

Member Function Documentation

Cleanup()

virtual void CGUIThread::Cleanup ( )

inlineprotectedvirtual

Virtual method Cleanup is called after Execute and can be re-implemented in the user's derived class to clean up any allocated resources.

Execute()

virtual void CGUIThread::Execute ( void *  pArg )

protectedpure virtual

Virtual method Execute must be implemented in the user's derived class. It contains the thread's working code.

Parameters

pArg	Implementation-specific void pointer to the thread's working data

Implemented in CGUIResourceManager::CGUIBackgroundImageLoader::CGUIBackgroundImageLoaderThread, CGUIInputThreadDeviceUnix_TouchScreen, CGUIInputThreadDeviceUnix_Powermate, and CGUIInputThreadDeviceUnix_Mouse.

GetArg()

void * CGUIThread::GetArg ( ) const

inline

GetArg method gets the arguments.

Returns

void pointer to Arguments.

GetPriority()

ThreadPriority_t CGUIThread::GetPriority

(

)

Returns the priority.

Returns

thread priority.

GetThreadId()

void * CGUIThread::GetThreadId ( ) const

inline

Returns

The ID of this thread.

InitShutdown()

void CGUIThread::InitShutdown ( )

inline

Sets the m_bRunning flag to false to initiate the shutdown process.

IsRunning()

eC_Bool CGUIThread::IsRunning ( ) const

inline

Returns

True if this thread is currently running, otherwise False.

IsShutdownCompleted()

eC_Bool CGUIThread::IsShutdownCompleted ( ) const

inline

Returns

True if this thread has been completely shut down, otherwise False.

MapPriority() [1/2]

ThreadPriority_t CGUIThread::MapPriority ( const eC_Int &  iPriority )

protected

Maps platform-specific priorities to Guiliani thread priorities.

Parameters

iPriority

thread priority value from platform specific priority.

Returns

mapped Guiliani priority.

MapPriority() [2/2]

eC_Int CGUIThread::MapPriority ( const ThreadPriority_t &  ePriority )

protected

Maps Guiliani thread priorities to platform-specific priorities.

Parameters

ePriority

Guiliani thread priority.

Returns

mapped platform-specific priority.

SetArg()

void CGUIThread::SetArg ( void *  pArg )

inline

SetArg method sets the arguments.

Parameters

pArg	void pointer to arguments.

SetPriority()

void CGUIThread::SetPriority

(

const ThreadPriority_t &

ePriority

)

Sets the new priority to the thread.

Parameters

ePriority

The new priority

Setup()

virtual void CGUIThread::Setup ( )

inlineprotectedvirtual

Virtual method Setup is called before Execute and can be re-implemented in the user's derived class.

Start()

eC_Int CGUIThread::Start

(

void *

pArg

)

Creates and starts the thread. Platform-specific implementations should make sure to set this thread's ID (m_pThreadId).

Parameters

pArg	void pointer to the arguments.

Returns

Platform-specific return value, usually negative when an error occurred and 0 or larger when OK

Terminate()

void CGUIThread::Terminate

(

)

Terminates the thread.

Note

This method may have platform-dependant side effects and should never be used in order to ensure a reliable platform-agnostic application. For example, destructors of objects created in the thread context will not be called when a thread is terminated.

On Windows (where TerminateThread() is called): Note that the MSDN documentation states "TerminateThread is a dangerous function that should only be used in the most extreme cases". The value 0xdeadbeef will be passed to TerminateThread() as dwExitCode.

On Linux (where pthread_cancel() is called): This will interfere with certain ways of exception handling since a abi::__forced_unwind exception will be thrown and must not be intercepted. If a catch-all is implemented in a user-derived thread class, this exception will need to be rethrown:

try
{
    // code that may throw an exception
}
catch (abi::__forced_unwind&)
{
    throw;
}
catch (...)
{
    // expected exception handling
}

On other platforms this may be empty (as in the dummy thread) or execute arbitrary platform-specific code.

Again, when writing a Guiliani application this method should never be used. Guiliani will only use Terminate() in case a still running thread is destroyed, which will not happen during normal operation.

WaitForShutdown()

void CGUIThread::WaitForShutdown

(

)

This method doesn't return until the thread has cleanly shut down.

---

The documentation for this class was generated from the following files:

• GUIThread.h
• GUIThreadDummy.cpp