Threads Manual

About

Additionally to creating jobs (Jobs Manual) it is possible to create custom threads. Such custom threads can run in parallel to the main thread to perform various operations.

Custom Threads

A custom thread is defined by implementing a custom class based on maxon::ThreadInterfaceTemplate:

// This example shows a simple thread implementation. The thread calculates pi;
// the longer the thread runs, the more accurate the result will be.
// This thread calculates pi until it is cancelled.
// The longer the thread runs, the more precise the result will be.
class CalculatePiThread : public maxon::ThreadInterfaceTemplate<CalculatePiThread>
{
public:
~CalculatePiThread()
{
_totalPointCount = 0;
_insidePointCount = 0;
}
// worker
maxon::Result<void> operator ()()
{
// init random number generator
random.Init(0);
// calculate pi until the thread is stopped
while (!IsCancelled())
{
// check if random point is inside the unit-circle
point.x = random.Get01();
point.y = random.Get01();
if (point.GetSquaredLength() < 1.0)
++_insidePointCount;
++_totalPointCount;
// maximum number of points that can be handled with Int reached
// stop thread
Cancel();
}
return maxon::OK;
}
// Returns the calculated value of pi or an error if no calculation has happened yet.
{
if (_totalPointCount == 0)
return maxon::IllegalStateError(MAXON_SOURCE_LOCATION, "Thread has not calculated anything yet."_s);
const maxon::Float pi = 4.0 * maxon::Float(_insidePointCount) / maxon::Float(_totalPointCount);
return pi;
}
const maxon::Char* GetName() const { return "CalculatPiThread"; }
private:
maxon::Int _totalPointCount;
maxon::Int _insidePointCount;
};

Usage

An instance of a custom thread is typically stored as a global static variable:

// This example defines a global static variable to store the custom thread.

Custom threads are based on maxon::ThreadInterface and maxon::JobInterface. maxon::ThreadInterface functions are:

// This example shows how the custom thread is created, started and closed.
if (!g_calculatePiThread)
{
// create and start thread
g_calculatePiThread = CalculatePiThread::Create() iferr_return;
g_calculatePiThread.Start() iferr_return;
}
else
{
// cancel thread if it is still running
g_calculatePiThread->CancelAndWait();
// get result
const maxon::Float pi = g_calculatePiThread->GetPI() iferr_return;
// print result with 20 digits after the comma
DiagnosticOutput("PI: @", maxon::String::FloatToString(pi, 1, 20));
// clear thread
g_calculatePiThread = nullptr;
}

Further static utility functions are:

Further Reading