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;
};
Definition: apibasemath.h:54
Definition: lib_math.h:19
FLOAT Get01()
Returns the next random value in the range of [0..1].
Definition: thread.h:180
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:190
char Char
signed 8 bit character
Definition: apibase.h:186
Float64 Float
Definition: apibase.h:199
return OK
Definition: apibase.h:2620
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
#define MAXON_UNLIKELY(X)
Definition: compilerdetection.h:489
const Char * GetName() const
Definition: job.h:179
Bool IsCancelled() const
Definition: job.h:292
void Cancel()
Definition: job.h:282
A vector consisting of two components X and Y.
Definition: vec2.h:16
T y
Definition: vec2.h:32
T x
Definition: vec2.h:31
constexpr T GetSquaredLength() const
Returns the squared length of the vector.
Definition: vec2.h:418

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.
Definition: thread.h:204

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;
}
void CancelAndWait(WAITMODE mode=WAITMODE::DEFAULT)
Definition: thread.h:316
static auto Create(ARGS &&... args)
Definition: apibase.h:2730
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:176
#define iferr_return
Definition: resultbase.h:1465

Further static utility functions are:

Further Reading