Win32::Win32Thread Class Reference

#include <win32thread.h>

Detailed Description

Win32 implementation of thread class.

Copyright

(C) 2006 Radon Labs GmbH (C) 2013-2020 Individual contributors, see AUTHORS file

Inherits Core::RefCounted.

Public Types
enum	Priority { Low , Normal , High }
	thread priorities More...

Public Member Functions
	Win32Thread ()
	constructor
virtual	~Win32Thread ()
	destructor
void	SetPriority (Priority p)
	set the thread priority
Priority	GetPriority () const
	get the thread priority
void	SetStackSize (SizeT s)
	set stack size in bytes (default is 4 KByte)
SizeT	GetStackSize () const
	get stack size
void	SetName (const Util::String &n)
	set thread name
const Util::String &	GetName () const
	get thread name
void	SetThreadAffinity (const uint mask)
	set the thread affinity
uint	GetThreadAffinity ()
	get the thread affinity
void	Start ()
	start executing the thread code, returns when thread has actually started
void	Stop ()
	request threading code to stop, returns when thread has actually finished
bool	IsRunning () const
	return true if thread has been started
Public Member Functions inherited from Core::RefCounted
	RefCounted ()
	constructor
int	GetRefCount () const
	get the current refcount
void	AddRef ()
	increment refcount by one
void	Release ()
	decrement refcount and destroy object if refcount is zero
bool	IsInstanceOf (const Rtti &rtti) const
	return true if this object is instance of given class
bool	IsInstanceOf (const Util::String &className) const
	return true if this object is instance of given class by string
bool	IsInstanceOf (const Util::FourCC &classFourCC) const
	return true if this object is instance of given class by fourcc
bool	IsA (const Rtti &rtti) const
	return true if this object is instance of given class, or a derived class
bool	IsA (const Util::String &rttiName) const
	return true if this object is instance of given class, or a derived class, by string
bool	IsA (const Util::FourCC &rttiFourCC) const
	return true if this object is instance of given class, or a derived class, by fourcc
const Util::String &	GetClassName () const
	get the class name
Util::FourCC	GetClassFourCC () const
	get the class FourCC code

Static Public Member Functions
static void	YieldThread ()
	yield the thread (gives up current time slice)
static void	SetMyThreadName (const char *n)
	set thread name from within thread context
static const char *	GetMyThreadName ()
	obtain name of thread from within thread context
static Threading::ThreadId	GetMyThreadId ()
	get the thread ID of this thread
Static Public Member Functions inherited from Core::RefCounted
static void	DumpRefCountingLeaks ()
	dump refcounting leaks, call at end of application (NEBULA_DEBUG builds only!)

Protected Member Functions
virtual void	EmitWakeupSignal ()
	override this method if your thread loop needs a wakeup call before stopping
virtual void	DoWork ()
	this method runs in the thread context
bool	ThreadStopRequested () const
	check if stop is requested, call from DoWork() to see if the thread proc should quit
Protected Member Functions inherited from Core::RefCounted
virtual	~RefCounted ()
	destructor (called when refcount reaches zero)

Private Member Functions
	__DeclareClass (Win32Thread)

Static Private Member Functions
static DWORD WINAPI	ThreadProc (LPVOID self)
	internal thread proc helper function

Private Attributes
HANDLE	threadHandle
Win32Event	threadStartedEvent
Win32Event	stopRequestEvent
Priority	priority
uint	affinityMask
SizeT	stackSize
Util::String	name

Static Private Attributes
static ThreadLocal const char *	ThreadName = 0

Member Enumeration Documentation

Priority

enum Win32::Win32Thread::Priority

thread priorities

Enumerator
Low
Normal
High

Constructor & Destructor Documentation

Win32Thread()

Win32::Win32Thread::Win32Thread

(

)

constructor

~Win32Thread()

Win32::Win32Thread::~Win32Thread ( )

virtual

destructor

Member Function Documentation

__DeclareClass()

Win32::Win32Thread::__DeclareClass ( Win32Thread )

private

DoWork()

void Win32::Win32Thread::DoWork ( )

protectedvirtual

this method runs in the thread context

This method should be derived in a Thread subclass and contains the actual code which is run in the thread.

The method must not call C-Lib functions under Win32. To terminate the thread, just return from this function. If DoWork() runs in an infinite loop, call ThreadStopRequested() to check whether the Thread object wants the thread code to quit.

EmitWakeupSignal()

void Win32::Win32Thread::EmitWakeupSignal ( )

protectedvirtual

override this method if your thread loop needs a wakeup call before stopping

This method is called by Thread::Stop() after setting the stopRequest event and before waiting for the thread to stop.

If your thread runs a loop and waits for jobs it may need an extra wakeup signal to stop waiting and check for the ThreadStopRequested() event. In this case, override this method and signal your event object.

GetMyThreadId()

Threading::ThreadId Win32::Win32Thread::GetMyThreadId ( )

static

get the thread ID of this thread

Static method which returns the ThreadId of this thread.

GetMyThreadName()

const char * Win32::Win32Thread::GetMyThreadName ( )

static

obtain name of thread from within thread context

Static method to obtain the current thread name from anywhere in the thread's code.

GetName()

const Util::String & Win32::Win32Thread::GetName ( ) const

inline

get thread name

Get the thread's name.

This is the vanilla method which returns the name member. To obtain the current thread's name from anywhere in the thread's execution context, call the static method Thread::GetMyThreadName().

GetPriority()

Win32Thread::Priority Win32::Win32Thread::GetPriority ( ) const

inline

get the thread priority

GetStackSize()

SizeT Win32::Win32Thread::GetStackSize ( ) const

inline

get stack size

GetThreadAffinity()

uint Win32::Win32Thread::GetThreadAffinity ( )

inline

get the thread affinity

IsRunning()

bool Win32::Win32Thread::IsRunning

(

)

const

return true if thread has been started

Returns true if the thread is currently running.

SetMyThreadName()

void Win32::Win32Thread::SetMyThreadName ( const char * n )

static

set thread name from within thread context

Static method which sets the name of this thread.

This is called from within ThreadProc. The string pointed to must remain valid until the thread is terminated!

SetName()

void Win32::Win32Thread::SetName ( const Util::String & n )

inline

set thread name

Set the thread's name.

To obtain the current thread's name from anywhere in the thread's execution context, call the static method Thread::GetMyThreadName().

SetPriority()

void Win32::Win32Thread::SetPriority ( Priority p )

inline

set the thread priority

SetStackSize()

void Win32::Win32Thread::SetStackSize ( SizeT s )

inline

set stack size in bytes (default is 4 KByte)

SetThreadAffinity()

void Win32::Win32Thread::SetThreadAffinity ( const uint mask )

inline

set the thread affinity

Start()

void Win32::Win32Thread::Start

(

)

start executing the thread code, returns when thread has actually started

Start the thread, this creates a Win32 thread and calls the static ThreadProc, which in turn calls the virtual DoWork() class of this object.

The method waits for the thread to start and then returns.

Stop()

void Win32::Win32Thread::Stop

(

)

request threading code to stop, returns when thread has actually finished

This stops the thread by signalling the stopRequestEvent and waits for the thread to actually quit.

If the thread code runs in a loop it should use the IsStopRequested() method to see if the thread object wants it to shutdown. If so DoWork() should simply return.

ThreadProc()

DWORD WINAPI Win32::Win32Thread::ThreadProc ( LPVOID self )

staticprivate

internal thread proc helper function

Internal static helper method.

This is called by CreateThread() and simply calls the virtual DoWork() method on the thread object.

ThreadStopRequested()

bool Win32::Win32Thread::ThreadStopRequested ( ) const

inlineprotected

check if stop is requested, call from DoWork() to see if the thread proc should quit

If the derived DoWork() method is running in a loop it must regularly check if the process wants the thread to terminate by calling ThreadStopRequested() and simply return if the result is true.

This will cause the thread to shut down.

YieldThread()

void Win32::Win32Thread::YieldThread ( )

static

yield the thread (gives up current time slice)

The yield function is empty on Win32 and Xbox360.

Member Data Documentation

affinityMask

uint Win32::Win32Thread::affinityMask

private

name

Util::String Win32::Win32Thread::name

private

priority

Priority Win32::Win32Thread::priority

private

stackSize

SizeT Win32::Win32Thread::stackSize

private

stopRequestEvent

Win32Event Win32::Win32Thread::stopRequestEvent

private

threadHandle

HANDLE Win32::Win32Thread::threadHandle

private

ThreadName

ThreadLocal const char * Win32::Win32Thread::ThreadName = 0

staticprivate

threadStartedEvent

Win32Event Win32::Win32Thread::threadStartedEvent

private

---

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

• /github/workspace/code/foundation/threading/win32/win32thread.h
• /github/workspace/code/foundation/threading/win32/win32thread.cc