Burger::Thread Class Reference

Class for creating a thread. More...

Public Types
enum	eState { kStateInvalid , kStateRunning , kStateEnded , kStateDetached }
	Current state of the Thread class. More...
typedef uintptr_t(*	FunctionPtr) (void *pThis)
	Thread entry prototype.

Public Member Functions
	Thread () noexcept
	Initialize a thread to power up defaults.
	~Thread ()
	Destructor.
eError	start (FunctionPtr pFunction, void *pData, const char *pName=nullptr, uintptr_t uStackSize=0) noexcept
	Startup a thread.
eError	wait (void) noexcept
	Wait for a thread to exit.
eError	detach (void) noexcept
	Detach a thread.
const char *	get_name (void) const noexcept
	Return the name of the thread.
uintptr_t	get_result (void) const noexcept
	Return the exit code of the user supplied thread.
uintptr_t	get_stack_size (void) const noexcept
	Return the size of the stack allocated for this thread.
uint_t	is_initialized (void) const noexcept
	Return TRUE if a thread is running.

Static Public Member Functions
static void	run (void *pThis) noexcept
	Internal function to dispatch to the thread.

Protected Member Functions
eError	platform_start (void) noexcept
	Internal function to start a thread.
eError	platform_after_start (void) noexcept
	Internal function to set up data specific to a thread.
eError	platform_detach (void) noexcept
	Internal function to detach a thread.

Protected Attributes
FunctionPtr	m_pFunction
	Pointer to the thread.
void *	m_pData
	Data pointer for the thread.
const char *	m_pName
	Name of the thread.
uintptr_t	m_uStackSize
	Size of the stack allocated for the thread.
uintptr_t	m_uResult
	Result code of the thread on exit.
ThreadID	m_uThreadID
	ThreadID assigned to this thread.
uint32_t	m_uState
	State of the thread, see /ref eState.
void *	m_pThreadHandle
	HANDLE to the thread (Windows/Xbox only)
uint8_t *	m_pStack
	Memory for the thread's stack.
void *	m_pOSThread
	Pointer to OSThread record.

Private Member Functions
	Thread (const Thread &)=delete
Thread &	operator= (const Thread &)=delete
	Thread (Thread &&)=delete
Thread &	operator= (Thread &&)=delete

Detailed Description

Class for creating a thread.

---

In a multiprocessor system, it's sometimes necessary to have another CPU run a concurrent thread. This class will handle the dispatching a thread.

Further reading http://en.wikipedia.org/wiki/Thread_(computing)

Note

Most platforms support native preemptive multi-threading, but the Nintendo 64, Wii and WiiU use cooperative multithreading, so great care is required when using threads.

See also

Mutex, Semaphore and ConditionVariable

Member Typedef Documentation

FunctionPtr

typedef uintptr_t( * Burger::Thread::FunctionPtr) (void *pThis)

Thread entry prototype.

Member Enumeration Documentation

eState

enum Burger::Thread::eState

Current state of the Thread class.

---

Once a Thread class is instanciated, it's set to the kStateInvalid state. Once a thread has begun, the state value will be updated to reflect the state of the thread as it executes and possibly terminates.

See also

Thread

Enumerator
kStateInvalid	Thread has not been set up.
kStateRunning	Thread is in progress.
kStateEnded	Thread has concluded.
kStateDetached	Thread was detached.

Constructor & Destructor Documentation

Thread() [1/3]

Burger::Thread::Thread ( const Thread & )

privatedelete

Thread() [2/3]

Burger::Thread::Thread ( Thread && )

privatedelete

Thread() [3/3]

Burger::Thread::Thread ( )

noexcept

Initialize a thread to power up defaults.

---

No thread is launched, the class is set up.

See also

start(), or ~Thread()

~Thread()

Burger::Thread::~Thread

(

)

Destructor.

---

Wait until the thread completes and then release resources

See also

wait(), start(FunctionPtr, void*, const char*, uintptr_t) or Thread()

Member Function Documentation

detach()

Burger::eError BURGER_API Burger::Thread::detach ( void )

noexcept

Detach a thread.

---

If a thread isn't already running, return immediately. If a thread is already running, alert the operating system that this thread should be aborted and shut down.

Note

This is a function of last resort. Some operating systems can leak resources if a thread is shut down in this manner. The proper way to shut down a thread is to sent the thread a signal to alert it to exit it's loop and call wait().

Returns

Zero if no error, non-zero if there was an error

See also

wait() or start()

get_name()

const char *BURGER_API Burger::Thread::get_name ( void ) const

noexcept

Return the name of the thread.

---

Returns either an empty string or the assigned name of the thread. This function will not return nullptr

Returns

A "C" string pointer to either the name of the thread or ""

See also

start() or is_initialized()

get_result()

Burger::Thread::get_result ( void ) const

inlinenoexcept

Return the exit code of the user supplied thread.

---

When a thread launched by this class executes, it can return a result code which is captured by the dispatcher. The code can retrieved by this call.

Note

The code is only valid once the thread exits cleanly. Check the state for kStateEnded to ensure the value is valid.

Returns

Result code from the thread code

See also

start() or is_initialized()

get_stack_size()

Burger::Thread::get_stack_size ( void ) const

inlinenoexcept

Return the size of the stack allocated for this thread.

---

When a thread launched by this class, a stack is assigned. If the default value of 0 is used, the platform will determine the default stack size. The value assigned can be obtained by this call after the thread began execution.

Returns

Size of the thread's stack in bytes.

See also

start() or is_initialized()

is_initialized()

Burger::Thread::is_initialized ( void ) const

inlinenoexcept

Return TRUE if a thread is running.

---

Once a thread is started, this function will return TRUE. Once either wait() is called or the thread terminates, this function will return FALSE.

Returns

TRUE if a thread is in progress, or FALSE if not.

See also

start() or get_result()

operator=() [1/2]

Thread & Burger::Thread::operator= ( const Thread & )

privatedelete

operator=() [2/2]

Thread & Burger::Thread::operator= ( Thread && )

privatedelete

platform_after_start()

Burger::eError BURGER_API Burger::Thread::platform_after_start ( void )

protectednoexcept

Internal function to set up data specific to a thread.

---

This function executes platform specific code to execute before actually dispatching to the thread. This function is called in the same process as the thread, not the parent process.

Note

This function should not be called by applications.

See also

platform_start()

platform_detach()

Burger::eError BURGER_API Burger::Thread::platform_detach ( void )

protectednoexcept

Internal function to detach a thread.

---

This function executes platform specific code detach a thread.

Note

This function should not be called by applications.

See also

detach()

platform_start()

Burger::eError BURGER_API Burger::Thread::platform_start ( void )

protectednoexcept

Internal function to start a thread.

---

This function executes platform specific code to start a thread.

Note

This function should not be called by applications.

See also

platform_after_start()

run()

void BURGER_API Burger::Thread::run ( void * pThis )

staticnoexcept

Internal function to dispatch to the thread.

---

This internal routine is used to synchronize with the main thread to ensure that the class variables are stable before execution begins. It will also capture the result code before exiting back to the operating system.

Note

This function should not be called by applications.

Parameters

pThis

Pointer to an instance of Thread

See also

start(), or get_result()

start()

Burger::eError BURGER_API Burger::Thread::start ( FunctionPtr pFunction, void * pData, const char * pName = nullptr, uintptr_t uStackSize = 0 )

noexcept

Startup a thread.

---

If a thread isn't already running, launch this thread of execution. If a thread is already running, return kErrorThreadAlreadyStarted.

If a name is passed for the name of the thread, it is copied so it's not necessary to keep the name around once this function returns.

Parameters

pFunction	Pointer to the entry point to the thread
pData	Pointer to data to pass to the thread
pName	Pointer to a "C" string for the name of the thread
uStackSize	Size of the stack for the thread

Returns

Zero if no error, non-zero if there was an error

See also

kill() or wait()

wait()

Burger::eError BURGER_API Burger::Thread::wait ( void )

noexcept

Wait for a thread to exit.

---

If a thread isn't already running, return immediately. If a thread is already running, sleep until the thread has completed execution.

Returns

Zero if no error, non-zero if there was an error

See also

detach() or start()

Member Data Documentation

m_pData

void* Burger::Thread::m_pData

protected

Data pointer for the thread.

m_pFunction

FunctionPtr Burger::Thread::m_pFunction

protected

Pointer to the thread.

m_pName

const char* Burger::Thread::m_pName

protected

Name of the thread.

m_pOSThread

void* Burger::Thread::m_pOSThread

protected

Pointer to OSThread record.

m_pStack

uint8_t* Burger::Thread::m_pStack

protected

Memory for the thread's stack.

m_pThreadHandle

void* Burger::Thread::m_pThreadHandle

protected

HANDLE to the thread (Windows/Xbox only)

m_uResult

uintptr_t Burger::Thread::m_uResult

protected

Result code of the thread on exit.

m_uStackSize

uintptr_t Burger::Thread::m_uStackSize

protected

Size of the stack allocated for the thread.

m_uState

uint32_t Burger::Thread::m_uState

protected

State of the thread, see /ref eState.

m_uThreadID

ThreadID Burger::Thread::m_uThreadID

protected

ThreadID assigned to this thread.