GThread Class Reference

The GThread class is a utility class containing static methods that allow you to run code on various system threads. More...

#include "gthread.h"

Public Member Functions
int	getResult() const =0
	Returns the value returned by the thread's function. More...
bool	isRunning() const =0
	Returns true if the given thread is currently actively running. More...
void	join()=0
	Waits for this thread to finish. More...
bool	join(unsigned long ms)=0
	Waits for this thread to finish. More...
string	name() const =0
	Returns the thread's name as passed to the constructor, or a default name if none was passed. More...
int	priority() const =0
	Returns the thread's priority. More...
void	setName(string name)=0
	Sets the thread's name to the given value. More...
void	setPriority(int priority)=0
	Sets the thread's priority to the given value. More...
void	sleep(double ms)=0
	Causes the thread to pause itself for the given number of milliseconds. More...
void	start()=0
	Tells the thread to start running. More...
void	stop()=0
	Forcibly terminates the thread. More...
void	yield()=0
	Indicates that the current thread is willing to yield execution to any other threads that want to run. More...

Static Public Member Functions
static void	ensureThatThisIsTheQtGuiThread(string message="")
	Generates an error if the caller is not running on the Qt GUI thread. More...
static GThread *	getCurrentThread()
	Returns the caller's Qt thread object. More...
static GThread *	getQtGuiThread()
	Returns the Qt thread object representing the Qt Gui thread for the application. More...
static GThread *	getStudentThread()
	Returns the Qt thread object representing the thread on which the student's main() function runs. More...
static bool	iAmRunningOnTheQtGuiThread()
	Returns true if the caller is running on the Qt GUI thread. More...
static bool	iAmRunningOnTheStudentThread()
	Returns true if the caller is running on the student thread. More...
static bool	qtGuiThreadExists()
	Returns true if the Qt GUI thread has been created. More...
static void	runInNewThread(GThunk func, string threadName="")
	Runs the given void function in its own new thread, blocking the current thread to wait until it is done. More...
static GThread *	runInNewThreadAsync(GThunk func, string threadName="")
	Runs the given void function in its own new thread in the background; the current thread does not block and keeps going. More...
static void	runOnQtGuiThread(GThunk func)
	Runs the given void function on the Qt GUI thread, blocking the current thread to wait until it is done. More...
static void	runOnQtGuiThreadAsync(GThunk func)
	Runs the given void function on the Qt GUI thread in the background; the current thread does not block and keeps going. More...
static void	startStudentThread(GThunkInt mainFunc)
	Starts the student's thread, telling it to run the given function, which accepts no arguments and returns an int. More...
static bool	studentThreadExists()
	Returns true if the student's thread has already been created. More...
static bool	wait(GThread *thread, long ms)
	Waits the given number of milliseconds for the given thread to finish. More...

Protected Member Functions
	GThread()
	~GThread()=default
void	run()=0

Protected Attributes
GThunk	_func
GThunkInt	_funcInt
bool	_hasReturn
int	_returnValue

Static Protected Attributes
static std::map< QThread *, GThread * >	_allGThreadsQt
static std::map< std::thread *, GThread * >	_allGThreadsStd
static GThread *	_qtGuiThread = nullptr
static GThread *	_studentThread = nullptr

Detailed Description

The GThread class is a utility class containing static methods that allow you to run code on various system threads.

The library has the following two standard threads running at all times:

1. The Qt GUI thread, which runs Qt's master exec() loop, handles all GUI object creation and events (this is technically the program's main thread)

2. The student thread, which runs the student's main() function and any sub-functions called by main

Students and clients normally do not need to worry about threading issues. These methods are called internally by many of the graphical interactors to make sure that all internal Qt GUI widgets are initialized on the Qt GUI thread. This is required for them to function properly.

If you want to run a piece of code in its own thread, use static methods GThread::runInNewThread and GThread::runInNewThreadAsync.

Constructor & Destructor Documentation

GThread()

GThread ( )

protected

~GThread()

virtual ~GThread ( )

protectedvirtualdefault

Member Function Documentation

ensureThatThisIsTheQtGuiThread()

void ensureThatThisIsTheQtGuiThread ( string   message = "" )

static

Generates an error if the caller is not running on the Qt GUI thread.

An optional error detail message can be passed.

getCurrentThread()

GThread * getCurrentThread ( )

static

Returns the caller's Qt thread object.

getQtGuiThread()

GThread * getQtGuiThread ( )

static

Returns the Qt thread object representing the Qt Gui thread for the application.

getResult()

virtual int getResult ( ) const

pure virtual

Returns the value returned by the thread's function.

This will be 0 until the function is done running. This method only has meaning if your thread executes a function that returns an int.

getStudentThread()

GThread * getStudentThread ( )

static

Returns the Qt thread object representing the thread on which the student's main() function runs.

iAmRunningOnTheQtGuiThread()

bool iAmRunningOnTheQtGuiThread ( )

static

Returns true if the caller is running on the Qt GUI thread.

iAmRunningOnTheStudentThread()

bool iAmRunningOnTheStudentThread ( )

static

Returns true if the caller is running on the student thread.

isRunning()

virtual bool isRunning ( ) const

pure virtual

Returns true if the given thread is currently actively running.

join() [1/2]

virtual void join ( )

pure virtual

Waits for this thread to finish.

Will wait indefinitely as needed.

join() [2/2]

virtual bool join ( unsigned long  ms )

pure virtual

Waits for this thread to finish.

Will wait up to the given number of milliseconds. Returns true if the thread has finished or false if it is still running.

name()

virtual string name ( ) const

pure virtual

Returns the thread's name as passed to the constructor, or a default name if none was passed.

Not all thread implementations support names.

priority()

virtual int priority ( ) const

pure virtual

Returns the thread's priority.

Threads with higher priorities tend to run more than ones that are lower. Not all thread implementations support priorities.

qtGuiThreadExists()

bool qtGuiThreadExists ( )

static

Returns true if the Qt GUI thread has been created.

This will happen right before the student's main() function runs.

run()

virtual void run ( )

protectedpure virtual

runInNewThread()

void runInNewThread ( GThunk  func, string   threadName = ""  )

static

Runs the given void function in its own new thread, blocking the current thread to wait until it is done.

You can pass an optional name for the thread which can help when looking through the list of threads in a debugger.

Any uncaught exceptions or errors in the new thread will crash the program and cannot be caught by the calling thread.

If you want the new thread to run in the background, use the runInNewThreadAsync function instead.

runInNewThreadAsync()

GThread * runInNewThreadAsync ( GThunk  func, string   threadName = ""  )

static

Runs the given void function in its own new thread in the background; the current thread does not block and keeps going.

You can pass an optional name for the thread which can help when looking through the list of threads in a debugger. Returns a pointer to the given thread in case you want to wait a given amount of time for the thread to do its work.

Any uncaught exceptions or errors in the new thread will crash the program and cannot be caught by the calling thread.

If you want the caller to wait for the new thread to finish running, use the runInNewThread function instead.

runOnQtGuiThread()

void runOnQtGuiThread ( GThunk  func )

static

Runs the given void function on the Qt GUI thread, blocking the current thread to wait until it is done.

This function is called heavily by the internal GUI widgets and interactors of the library, because all Qt GUI operations are required to be done on the application's main thread.

Any uncaught exceptions or errors in the Qt GUI thread will crash the program and cannot be caught by the calling thread.

If you want the new thread to run in the background, use the runOnQtGuiThreadAsync function instead.

runOnQtGuiThreadAsync()

void runOnQtGuiThreadAsync ( GThunk  func )

static

Runs the given void function on the Qt GUI thread in the background; the current thread does not block and keeps going.

Any uncaught exceptions or errors in the Qt GUI thread will crash the program and cannot be caught by the calling thread.

If you want the caller to wait for the Qt GUI thread code to finish running, use the runOnQtGuiThread function instead.

setName()

virtual void setName ( string   name )

pure virtual

Sets the thread's name to the given value.

Not all thread implementations support names.

setPriority()

virtual void setPriority ( int  priority )

pure virtual

Sets the thread's priority to the given value.

Not all thread implementations support priorities.

sleep()

virtual void sleep ( double  ms )

pure virtual

Causes the thread to pause itself for the given number of milliseconds.

Exceptions

ErrorException

if ms is negative

start()

virtual void start ( )

pure virtual

Tells the thread to start running.

startStudentThread()

void startStudentThread ( GThunkInt  mainFunc )

static

Starts the student's thread, telling it to run the given function, which accepts no arguments and returns an int.

stop()

virtual void stop ( )

pure virtual

Forcibly terminates the thread.

You probably should not call this unless absolutely necessary, since it can lead to messed up state in the program.

studentThreadExists()

bool studentThreadExists ( )

static

Returns true if the student's thread has already been created.

wait()

bool wait ( GThread *  thread, long  ms  )

static

Waits the given number of milliseconds for the given thread to finish.

Returns

true if the entire amount of ms was elapsed without the thread finishing

yield()

void yield ( )

pure virtual

Indicates that the current thread is willing to yield execution to any other threads that want to run.

This differs slightly from sleep() in that sleep() mandates to pause the current thread for a given amount of time, while yield() is more of an offer to other threads that they may run now if they so choose.

Friends And Related Function Documentation

QtGui

friend class QtGui

friend

Member Data Documentation

_allGThreadsQt

std::map< QThread *, GThread * > _allGThreadsQt

staticprotected

_allGThreadsStd

std::map< std::thread *, GThread * > _allGThreadsStd

staticprotected

_func

GThunk _func

protected

_funcInt

GThunkInt _funcInt

protected

_hasReturn

bool _hasReturn

protected

_qtGuiThread

GThread * _qtGuiThread = nullptr

staticprotected

_returnValue

int _returnValue

protected

_studentThread

GThread * _studentThread = nullptr

staticprotected