Condition Variables Manual

Table of Contents

• About
• Condition
• Further Reading

About

A condition variable is used to wake a waiting thread to perform some action. It is typically used together with custom threads, see Threads Manual.

Condition

A condition variable is based on maxon::ConditionVariableInterface:

• maxon::ConditionVariableInterface::Wait(): Waits until the condition variable has been set or a certain amount of time has passed.
• maxon::ConditionVariableInterface::Set(): Sets the condition variable to wake a thread up.
• maxon::ConditionVariableInterface::Clear(): Clears the condition variable.
• maxon::ConditionVariableInterface::ObservableFinished(): This observable triggered after the condition is set.

Warning

Waiting for a condition variable in a job might result in a deadlock. Consider using LazyInit or LazyInitThreaded for initialization instead.

A condition variable can have multiple dependencies. This means that Set() must be called multiple times:

• maxon::ConditionVariableInterface::AddDependency(): Adds another dependency to the condition.

A condition variable is typically used as a member variable of a custom thread:

// This example shows how a thread uses a condition variable to wait for a command.
 
class ExampleThread : public maxon::ThreadInterfaceTemplate<ExampleThread>
{
public:
  ~ExampleThread() { }
 
  maxon::Result<void> Init()
  {
    iferr_scope;
    // create the condition variable
    _condition = maxon::ConditionVariableRef::Create() iferr_return;
    return maxon::OK;
  }
 
  // worker
  maxon::Result<void> operator ()()
  {
    while (!IsCancelled())
    {
      // check if condition is set, if not wait for another second
      const maxon::Seconds timeValue = maxon::Seconds(1);
      if (_condition.Wait(timeValue))
      {
        DiagnosticOutput("Action");
 
        // clear the condition variable to wait again
        _condition.Clear();
      }
    }
 
    return maxon::OK;
  }
 
  // set the condition variable to wake the thread
  void Action()
  {
    _condition.Set();
  }
 
  const maxon::Char* GetName() const { return "ExampleThread"; }
 
private:
  maxon::ConditionVariableRef _condition; 
};

This example thread can be used like this:

  // This example creates, starts and controls a thread with its condition variable.
 
  if (!g_exampleThread)
  {
    // create thread and call Init()
    g_exampleThread = ExampleThread::Create() iferr_return;
    g_exampleThread->Init() iferr_return;
 
    DiagnosticOutput("Start thread...");
    g_exampleThread.Start() iferr_return;
  }
 
  if (g_exampleThread)
  {
    // wake the thread
    g_exampleThread->Action();
  }

Further Reading

• Threading
• MAXON API Threading
• Threads Manual
• Locks & Synchronization Manual