Threads Manual

Table of Contents

• About
• Custom Threads
• Usage
• Further Reading

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
    maxon::LinearCongruentialRandom<maxon::Float32> random;
    random.Init(0);
 
    // calculate pi until the thread is stopped
    while (!IsCancelled())
    {
      // check if random point is inside the unit-circle
      maxon::Vector2d64 point;
      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
      if (MAXON_UNLIKELY(_totalPointCount == maxon::LIMIT<maxon::Int>::MAX))
        Cancel();
    }
    return maxon::OK;
  }
 
  // Returns the calculated value of pi or an error if no calculation has happened yet.
  maxon::Result<maxon::Float> GetPI()
  {
    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.
 
static maxon::ThreadRefTemplate<CalculatePiThread> g_calculatePiThread;

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

• maxon::ThreadInterface::Start(): Starts the thread.
• maxon::ThreadInterface::IsRunning(): Returns true if the thread is running.
• maxon::ThreadInterface::Wait(): Waits until the thread has been executed.
• maxon::ThreadInterface::ToString(): Returns a readable string of the content.

  // 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:

• maxon::ThreadInterface::GetCurrentThread(): Returns a pointer to the currently running thread.
• maxon::ThreadInterface::IsMainThread(): Returns true if the thread is the main application thread
• maxon::ThreadInterface::GetCurrentThreadType(): Returns the type of the current thread.
• maxon::ThreadInterface::AssimilateAlienThread(): Allocates internal resources for an alien thread.

Further Reading

• Threading
• MAXON API Threading
• Jobs Manual
• Locks & Synchronization Manual
• Condition Variables Manual