CXThread

The CXThread class enables the creation of additional native preemptively-scheduled threads of execution. Each process starts with a singular "main thread" (which is NOT backed by a CXThread object) and may start additional threads by creating CXThread objects and starting them executing. The CXThread object must persist until after the thread in question has terminated; an attempt to destroy the CXThread object will block against completion of the thread. Each CXThread object controls a maximum of one native thread.

 

// Construct a CXThread object, providing a (non-unique) label for debugging purposes.
CXThread(const CXString& debugName);

// Start the thread executing.
virtual void Start(void);

// Request that the thread exit, and block until it does.
virtual void Stop(void);

// Request that the thread exit, but does not block.
void Stopping(void);

// Returns whether the thread was executing at the time of the call. Beware of race conditions.
bool IsRunning(void) const;

// Determines whether anybody has requested this thread to stop.
bool WantToExit(void) const;

 

Usage

Deriving from CXThread

A common usage is for an object to derive from CXThread in order to gain its own threaded functionality. The thread may be started at the end of the constructor, from some post-initialisation method, or even on demand in response to other methods being called.

// When creating a CXThread-derived object, override this function to implement the actual threaded functionality.
virtual void Proc(void) = 0;

In this scenario, it is important for the derived object's destructor to Stop() the thread before destroying any other state, to avoid having the thread function attempt to use destroyed state.

Calling a Lambda Function

Alternatively, for cases where a single function should be run in a thread and there is no need for additional state, a CXThread object can be created for a given lambda function. By default, this thread starts execution immediately, however this can be postponed or prevented entirely.

 

static CXThread* CallFunctionInNewThread(cx_function<void (void)> function, const CXString& debugName, bool bShouldStartThread = true);

In this scenario, the caller is responsible for managing the lifetime of the CXThread object, including delete it when done.

Restrictions

It is considered an error to delete or Stop() a CXThread object from within its thread.