mbo::MboThread Class Reference

A basic thread implementation. More...

#include <MboThread.h>

Inheritance diagram for mbo::MboThread:

[legend]

Collaboration diagram for mbo::MboThread:

[legend]

List of all members.

Public Types
enum	EThreadPriority {   PRIORITY_IDLE = THREAD_PRIORITY_IDLE,   PRIORITY_LOWEST = THREAD_PRIORITY_LOWEST,   PRIORITY_LOW = THREAD_PRIORITY_ABOVE_NORMAL,   PRIORITY_NORMAL = THREAD_PRIORITY_NORMAL,   PRIORITY_HIGH = THREAD_PRIORITY_ABOVE_NORMAL,   PRIORITY_HIGHEST = THREAD_PRIORITY_HIGHEST,   PRIORITY_CRITICAL = THREAD_PRIORITY_TIME_CRITICAL }
Public Member Functions
	MboThread ()
	MboThread (const char *szThreadName)
virtual	~MboThread ()
bool	IsRunning () const
bool	IsStopping () const
bool	WaitFor (DWORD nMilliseconds=INFINITE) const
bool	KillThread (DWORD nMilliseconds=0, DWORD dwExitCode=-1)
DWORD	GetThreadId () const
void	SetThreadPriority (EThreadPriority ePriority)
const char *	GetThreadName ()
virtual void	Action ()=0
virtual void	OnActionException ()
virtual void	Start ()
virtual void	Stop ()
virtual void	OnThreadStart ()
virtual void	OnThreadStop ()
Static Public Member Functions
static void	SetThreadName (const char *szThreadName, DWORD dwThreadID=-1)
Protected Member Functions
virtual void	ThreadProc ()
Protected Attributes
HANDLE	m_hThread
HANDLE	m_hIsStopping
DWORD	m_dwThreadId
CCriticalSectionImpl	m_mxStartStop
Friends
DWORD WINAPI	MboThreadProc (LPVOID lpParameter)

---

Detailed Description

A basic thread implementation.

You simply have to write down your action as an implementation of abstract method Action() your class derived from MboThread. This Action method must exit when property IsStopping() is set true. When the destructor is called the thread will be notified to terminate by property mentioned above. The destructor does not exit before the thread has terminated.

Additionally you can override OnThreadStart() and OnThreadStop() callbacks that allow to execute some code from within the started/stopping thread. When OnThreadStop() is called within destructor the overrided method will be ignored and instead the NO OPERATION callback gets executed. This results from C++ language design but can be solved by overriding the destructor with a custom one that calls Stop() And WaitFor() itself.

The threads can be assigned a name. This can be used for debugging purpose starting from MSVC.NET (unofficially since MSVC.6-SP2, but there only the beginning of the name is visible). If you not explicitly specify a name then the class name will be taken as thread name.

Note:

You should use the default constructor together with descriptive class names of your derived classes. The only need to explicitly set a name by parameter is if you create a derived class that handles calls to different handlers from within Action and you want to know the handler name.

When extending the class it is important to guard all property access code by entering the mutex m_mxStartStop.

This class is distributed under the following license GNU Lesser General Public License, version 2.1.

Definition at line 105 of file MboThread.h.

---

Member Enumeration Documentation

enum mbo::MboThread::EThreadPriority

Thread priority classes. These directly map to the native priority classes.

Enumerator:

PRIORITY_IDLE
PRIORITY_LOWEST
PRIORITY_LOW
PRIORITY_NORMAL
PRIORITY_HIGH
PRIORITY_HIGHEST
PRIORITY_CRITICAL

Definition at line 180 of file MboThread.h.

    {
        PRIORITY_IDLE     = THREAD_PRIORITY_IDLE,
        PRIORITY_LOWEST   = THREAD_PRIORITY_LOWEST,
        PRIORITY_LOW      = THREAD_PRIORITY_ABOVE_NORMAL,
        PRIORITY_NORMAL   = THREAD_PRIORITY_NORMAL,
        PRIORITY_HIGH     = THREAD_PRIORITY_ABOVE_NORMAL,
        PRIORITY_HIGHEST  = THREAD_PRIORITY_HIGHEST,
        PRIORITY_CRITICAL = THREAD_PRIORITY_TIME_CRITICAL
    };

---

Constructor & Destructor Documentation

mbo::MboThread::MboThread

(

)

default constructor

mbo::MboThread::MboThread

(

const char *

szThreadName

)

[explicit]

constructor

Parameters:

szThreadName

The name of the thread. The new class instance will copy the value and free its copy automatically upon destruction. You may want to use NULL to use the class name of as the thread name. If you do so the name is computed in thread startup - this only works if this is not done in constructor. If done so the name you will see is the name of that parent class whose constructor started the thread.

Note:

You can see thread names only in MSVC.NET and above or MSVC.6-SP2.

virtual mbo::MboThread::~MboThread

(

)

[virtual]

Invokes Stop() and WaitFor().

Therefor the destructor ensures the thread is terminated if running.

---

Member Function Documentation

bool mbo::MboThread::IsRunning

(

)

const

Check if a thread is running

Returns:

whether the thread is running

bool mbo::MboThread::IsStopping

(

)

const

Check if a thread is told to stop

Returns:

whether the thread is stopping

bool mbo::MboThread::WaitFor

(

DWORD

nMilliseconds = INFINITE

)

const

Wait for thread to terminate

WaitFor() does not call Stop() and can itself be called from more than one thread.

Parameters:

nMilliseconds

Time to wait for thread to terminate.

Returns:

Whether or not the thread ended.

bool mbo::MboThread::KillThread	(	DWORD	nMilliseconds = 0,
		DWORD	dwExitCode = -1
	)

Stop the thread, wait a given time for the thread to terminate and kill it afterwards if necessary.

Parameters:

	nMilliseconds	Time in milliseconds to wait for the thread to terminate normally.
	dwExitCode	Exitcode for the thread if killed.

Returns:

Whether or not the thread was terminated. This may become necessary for derived threads. However this function is invariant against inheritance.

DWORD mbo::MboThread::GetThreadId

(

)

const

Retrieve Id of thread

This value is NULL if no thread is running

Returns:

internal thread id

void mbo::MboThread::SetThreadPriority

(

EThreadPriority

ePriority

)

Set the threads priority class.

Parameters:

ePriority

new priority for the thread.

Note:

This works only if the thread was running once already.

const char* mbo::MboThread::GetThreadName

(

)

Get thread name.

When the name was set NULL in constructor then this function triggers the name generation. However this has the same affects when called from inside a constructor.

Returns:

the name of the thread

Note:

This is a non const function.

virtual void mbo::MboThread::Action

(

)

[pure virtual]

Action method to be implemented by derived classes.

This Method is called once after Start() is successfull and may contain an infinite loop. But the method has to check whether or not it must exit (IsStopping())

Implemented in mbo::MboWinMsgHandler.

virtual void mbo::MboThread::OnActionException

(

)

[virtual]

Callback executed when the action method cathes an exception.

This default implementation logs the errors via windows' debug output.

virtual void mbo::MboThread::Start

(

)

[virtual]

Start the thread.

to check whether or not the thread was really started implement an OnThreadStart() handler in the derived class.

virtual void mbo::MboThread::Stop

(

)

[virtual]

Stop the thread.

This only sets the variable m_bIsStoping

Reimplemented in mbo::MboEventThread, mbo::MboDelayedEventThread, and mbo::MboWinMsgHandler.

virtual void mbo::MboThread::OnThreadStart

(

)

[virtual]

Method called emidiatley after thread has started and before Action() is called.

virtual void mbo::MboThread::OnThreadStop

(

)

[virtual]

Method that is called when action is left e.g. thread is stoping.

static void mbo::MboThread::SetThreadName	(	const char *	szThreadName,
		DWORD	dwThreadID = -1
	)			[static]

Set the thread name for the debugging interface.

Parameters:

	szThreadName	The new name of the thread
	dwThreadID	The thread id or -1 to select current thread.

This function is typically called at Thread startup.

virtual void mbo::MboThread::ThreadProc

(

)

[protected, virtual]

Call OnThreadStart()/Action()/OnThreadStop()

---

Friends And Related Function Documentation

DWORD WINAPI MboThreadProc

(

LPVOID

lpParameter

)

[friend]

Grant global function MboThreadProc access to all members

---

Member Data Documentation

HANDLE mbo::MboThread::m_hThread [protected]

HANDLE to thread or NULL (guarded by m_mxStartStop)

Definition at line 262 of file MboThread.h.

HANDLE mbo::MboThread::m_hIsStopping [protected]

Stop flag (Event)

Definition at line 263 of file MboThread.h.

DWORD mbo::MboThread::m_dwThreadId [protected]

Thread Id or 0 (guarded by m_mxStartStop)

Definition at line 264 of file MboThread.h.

CCriticalSectionImpl mbo::MboThread::m_mxStartStop [protected]

Mutex used for start/stop access

Definition at line 265 of file MboThread.h.

---

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

• MboThread.h

---