StanfordCPPLib
Static Public Member Functions | Protected Member Functions | Static Protected Attributes | List of all members
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"

Inheritance diagram for GThread:

Static Public Member Functions

static void ensureThatThisIsTheQtGuiThread(string message="")
 Generates an error if the caller is not running on the Qt GUI main thread. More...
 
static QThread * getCurrentThread()
 Returns the caller's Qt thread object. More...
 
static QThread * getQtMainThread()
 Returns the Qt thread object representing the main thread for the application, also referred to as the Qt GUI thread. More...
 
static QThread * 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 QThread * 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 sleep(double ms)
 Causes the current thread to pause itself for the given number of milliseconds. More...
 
static bool wait(QThread *thread, long ms)
 Waits the given number of milliseconds for the given thread to finish. More...
 
static void yield()
 Indicates that the current thread is willing to yield execution to any other threads that want to run. More...
 

Protected Member Functions

 GThread()
 

Static Protected Attributes

static QThread * _qtMainThread = nullptr
 
static QThread * _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

Member Function Documentation

◆ ensureThatThisIsTheQtGuiThread()

void ensureThatThisIsTheQtGuiThread ( string   message = "")
static

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

An optional error detail message can be passed.

◆ getCurrentThread()

QThread * getCurrentThread ( )
static

Returns the caller's Qt thread object.

◆ getQtMainThread()

QThread * getQtMainThread ( )
static

Returns the Qt thread object representing the main thread for the application, also referred to as the Qt GUI thread.

◆ getStudentThread()

QThread * 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.

◆ 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.

◆ 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()

QThread * 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.

◆ sleep()

void sleep ( double  ms)
static

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

Exceptions
ErrorExceptionif ms is negative

◆ wait()

bool wait ( QThread *  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 ( )
static

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

◆ stanfordcpplib::initializeLibrary

void stanfordcpplib::initializeLibrary ( int  argc,
char **  argv 
)
friend

Member Data Documentation

◆ _qtMainThread

QThread * _qtMainThread = nullptr
staticprotected

◆ _studentThread

QThread * _studentThread = nullptr
staticprotected