ThreadDriver Class Reference

Raw platform threading primitives. More...

#include <ThreadDriver.h>

Inheritance diagram for ThreadDriver:

Public Member Functions
virtual void	init ()=0
	Initializes the threading backend.
virtual void	shutdown ()=0
	Shuts the threading backend down. Every thread must already have been joined.
virtual bool	createThread (ThreadEntry entry, void *arg, uint32_t stackSize, ThreadPriority priority, void **outHandle)=0
	Creates and starts a thread running entry(arg).
virtual void	joinThread (void *thread)=0
	Blocks until the thread exits, then releases the handle.
virtual void	cancelThread (void *thread)=0
	Requests the thread stop running and releases the handle without blocking on it.
virtual void	suspendThread (void *thread)=0
	Suspends a running thread until resumeThread() is called.
virtual void	resumeThread (void *thread)=0
	Resumes a thread suspended with suspendThread().
virtual bool	isThreadSuspended (void *thread)=0
virtual void *	createMutex ()=0
	Creates an unlocked mutex.
virtual void	destroyMutex (void *mutex)=0
	Destroys a mutex created by createMutex(). It must not be locked.
virtual void	lockMutex (void *mutex)=0
	Blocks until the mutex is acquired.
virtual void	unlockMutex (void *mutex)=0
	Releases a mutex held by the calling thread.
virtual void *	createCond ()=0
	Creates a condition variable.
virtual void	destroyCond (void *cond)=0
	Destroys a condition variable created by createCond(). No thread may be waiting on it.
virtual void	waitCond (void *cond, void *mutex)=0
	Atomically unlocks mutex and blocks the calling thread until signalCond() is called, then reacquires mutex before returning.
virtual void	signalCond (void *cond)=0
	Wakes every thread currently blocked in waitCond() on this condition variable.
virtual void	sleepMilliseconds (uint32_t ms)=0
	Sleeps the calling thread for at least the given duration.
virtual uintptr_t	getCurrentThreadId ()=0
	Returns an opaque, comparable identifier for the calling thread.

Detailed Description

Raw platform threading primitives.

Application/core code should not implement against this directly - use the Thread/Mutex/Cond RAII wrappers instead, which forward here via platform->getThread().

Definition at line 26 of file ThreadDriver.h.

Member Function Documentation

cancelThread()

virtual void ThreadDriver::cancelThread ( void * thread )

pure virtual

Requests the thread stop running and releases the handle without blocking on it.

This is a best-effort operation - not every backend can truly terminate a thread mid-flight (e.g. libogc/LWP has no cancel primitive, so that backend can only suspend it and leak its stack). Prefer having the thread watch its own exit condition and calling joinThread() to stop it cleanly wherever possible; reach for cancelThread() only as a last resort.

Implemented in OgcThreadDriver, and WutThreadDriver.

createCond()

virtual void * ThreadDriver::createCond ( )

pure virtual

Creates a condition variable.

Returns an opaque backend-defined handle, or nullptr on failure.

Implemented in OgcThreadDriver, and WutThreadDriver.

createMutex()

virtual void * ThreadDriver::createMutex ( )

pure virtual

Creates an unlocked mutex.

Returns an opaque backend-defined handle, or nullptr on failure.

Implemented in OgcThreadDriver, and WutThreadDriver.

createThread()

virtual bool ThreadDriver::createThread ( ThreadEntry entry, void * arg, uint32_t stackSize, ThreadPriority priority, void ** outHandle )

pure virtual

Creates and starts a thread running entry(arg).

Writes the new handle to *outHandle and returns true on success, or leaves *outHandle untouched and returns false on failure.

*outHandle is written before the new thread is scheduled to run, not after this call returns to the caller - entry() is allowed to reference *outHandle itself (e.g. to suspend/query its own thread) without racing the assignment.

Implemented in OgcThreadDriver, and WutThreadDriver.

destroyCond()

virtual void ThreadDriver::destroyCond ( void * cond )

pure virtual

Destroys a condition variable created by createCond(). No thread may be waiting on it.

Implemented in OgcThreadDriver, and WutThreadDriver.

destroyMutex()

virtual void ThreadDriver::destroyMutex ( void * mutex )

pure virtual

Destroys a mutex created by createMutex(). It must not be locked.

Implemented in OgcThreadDriver, and WutThreadDriver.

getCurrentThreadId()

virtual uintptr_t ThreadDriver::getCurrentThreadId ( )

pure virtual

Returns an opaque, comparable identifier for the calling thread.

Unlike the thread handles above, this does NOT require the thread to have been created via createThread() - it also identifies the app's original/main thread, which is never itself a Thread object. Two calls from the same thread must compare equal; that's the only guarantee callers may rely on.

Implemented in OgcThreadDriver, and WutThreadDriver.

init()

virtual void ThreadDriver::init ( )

pure virtual

Initializes the threading backend.

Implemented in OgcThreadDriver, and WutThreadDriver.

isThreadSuspended()

virtual bool ThreadDriver::isThreadSuspended ( void * thread )

pure virtual

Returns

true if the thread is currently suspended

Implemented in OgcThreadDriver, and WutThreadDriver.

joinThread()

virtual void ThreadDriver::joinThread ( void * thread )

pure virtual

Blocks until the thread exits, then releases the handle.

Implemented in OgcThreadDriver, and WutThreadDriver.

lockMutex()

virtual void ThreadDriver::lockMutex ( void * mutex )

pure virtual

Blocks until the mutex is acquired.

Implemented in OgcThreadDriver, and WutThreadDriver.

resumeThread()

virtual void ThreadDriver::resumeThread ( void * thread )

pure virtual

Resumes a thread suspended with suspendThread().

Implemented in OgcThreadDriver, and WutThreadDriver.

shutdown()

virtual void ThreadDriver::shutdown ( )

pure virtual

Shuts the threading backend down. Every thread must already have been joined.

Implemented in OgcThreadDriver, and WutThreadDriver.

signalCond()

virtual void ThreadDriver::signalCond ( void * cond )

pure virtual

Wakes every thread currently blocked in waitCond() on this condition variable.

This is a broadcast-only operation.

Implemented in OgcThreadDriver, and WutThreadDriver.

sleepMilliseconds()

virtual void ThreadDriver::sleepMilliseconds ( uint32_t ms )

pure virtual

Sleeps the calling thread for at least the given duration.

Implemented in OgcThreadDriver, and WutThreadDriver.

suspendThread()

virtual void ThreadDriver::suspendThread ( void * thread )

pure virtual

Suspends a running thread until resumeThread() is called.

Implemented in OgcThreadDriver, and WutThreadDriver.

unlockMutex()

virtual void ThreadDriver::unlockMutex ( void * mutex )

pure virtual

Releases a mutex held by the calling thread.

Implemented in OgcThreadDriver, and WutThreadDriver.

waitCond()

virtual void ThreadDriver::waitCond ( void * cond, void * mutex )

pure virtual

Atomically unlocks mutex and blocks the calling thread until signalCond() is called, then reacquires mutex before returning.

mutex must be locked by the calling thread on entry.

Implemented in OgcThreadDriver, and WutThreadDriver.

---

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

• source/drivers/ThreadDriver.h