SurgSim::Framework::BasicThread Class Referenceabstract

Basic thread implementation, tries to maintain a constant rate, supplies startup an initialization, can be synchronized with other threads at startup after calling doRun() a thread be be set off and doInit() and doStartup() will be called in succession. More...

`#include <SurgSim/Framework/BasicThread.h>`

Inheritance diagram for SurgSim::Framework::BasicThread:

## Public Member Functions

| BasicThread (const std::string &name="Unknown Thread")
virtual | ~BasicThread () noexcept(false)
| C++11 introduced noexcept. More...
void | start (std::shared_ptr< Barrier > startupBarrier=nullptr, bool isSynchronous=false)
| C++11 introduced noexcept. More...
void | stop ()
| Stopping the execution, blocks until the running thread has actually stopped,. More...
void | setIdle (bool isIdle)
| Set/Unset the thread in an idle state (doUpdate() called or not in the update() method) More...
bool | isIdle ()
| Query if this thread is in idle state or not. More...
bool | isInitialized ()
| Query if this object is initialized. More...
bool | isRunning () const
| Query if this object is running. More...
void | operator() ()
| This is what boost::thread executes on thread creation. More...
boost::thread & | getThread ()
std::string | getName () const
void | setRate (double val)
| Set the update rate of the thread. More...
bool | setSynchronous (bool val)
| Sets the thread to synchronized execution in concert with the startup barrier, the startup barrier has to exist for this call to succeed. More...
bool | isSynchronous ()
| Query if this object is synchronized. More...
double | getCpuTime () const
size_t | getUpdateCount () const
void | resetCpuTimeAndUpdateCount ()
| Reset the cpu time and the update count to 0. More...

## Protected Member Functions

bool | initialize ()
| Trigger the initialization of this object, this will be called before all other threads doStartup() are called. More...
bool | startUp ()
| Trigger the startup of this object, this will be called after all other threads doInit() was called the thread will only enter the run loop triggering upated() if all threads doInit() and doStartup() returned true. More...
bool | waitForBarrier (bool success)
virtual bool | executeInitialization ()

## Protected Attributes

Timer | m_timer
| Timer to measure the actual time taken to doUpdate. More...
std::shared_ptr< SurgSim::Framework::Logger > | m_logger
| Logger for this thread. More...

## Private Member Functions

virtual bool | doInitialize ()=0
virtual bool | doStartUp ()=0
virtual bool | doUpdate (double dt)
| Implementation of actual work function for this thread, this has a default implementation to handle destruction better, as it could be called while the thread is under destruction, if left unimplemented this would trigger a call to a pure virtual function. More...
virtual void | doBeforeStop ()
| Prepares the thread for its execution to be stopped. More...

## Private Attributes

std::string | m_name
boost::thread | m_thisThread
boost::chrono::duration< double > | m_period
std::shared_ptr< Barrier > | m_startupBarrier
boost::mutex | m_mutexStartStop
bool | m_isIdle
bool | m_isInitialized
bool | m_isRunning
bool | m_stopExecution
bool | m_isSynchronous

## Detailed Description

Basic thread implementation, tries to maintain a constant rate, supplies startup an initialization, can be synchronized with other threads at startup after calling doRun() a thread be be set off and doInit() and doStartup() will be called in succession.

If given a startup barrier the sequence will pause at both steps until all other threads are done with these steps. Initialization can be further customized by implementing a executeInitialization() function. When a barrier was used to start up the thread it can also be used to run the thread in a synchronous fashion. Use setIsSynchrous(true) to switch the thread over, after that the thread will wait for the barrier to trigger before it executes another update. When running asynchronously the thread cannot be stopped with the stop() call, a barrier wait with an argument of false has to be used to stop the thread. The thread can be set back to asynchronous execution, one last barrier wait after the switch has to be executed for the thread to come out of the wait.

## Constructor & Destructor Documentation

## BasicThread()

SurgSim::Framework::BasicThread::BasicThread | ( | const std::string & | name = `"Unknown Thread"` | ) |

explicit

## ~BasicThread()

SurgSim::Framework::BasicThread::~BasicThread | ( |  | ) |

virtual noexcept

C++11 introduced noexcept.

## Member Function Documentation

## doBeforeStop()

void SurgSim::Framework::BasicThread::doBeforeStop | ( |  | ) |

private virtual

Prepares the thread for its execution to be stopped.

Note
  Called from this thread before joined

Reimplemented in SurgSim::Framework::ComponentManager, SurgSim::Graphics::Manager, SurgSim::Physics::PhysicsManager, SurgSim::Graphics::OsgManager, SurgSim::Input::InputManager, SurgSim::Devices::NimbleScaffold, and SurgSim::Devices::RawMultiAxisThread.

## doInitialize()

virtual bool SurgSim::Framework::BasicThread::doInitialize | ( |  | ) |

private pure virtual

Implemented in SurgSim::Graphics::Manager, SurgSim::Physics::PhysicsManager, SurgSim::Graphics::OsgManager, SurgSim::Input::InputManager, SurgSim::Devices::ReplayPoseScaffold, SurgSim::Devices::OculusScaffold, SurgSim::Devices::NimbleScaffold, SurgSim::Devices::OpenNIScaffold, SurgSim::Devices::SixenseThread, SurgSim::Devices::TrackIRThread, SurgSim::Framework::BehaviorManager, SurgSim::Devices::RawMultiAxisThread, SurgSim::Testing::MockPhysicsManager, and SurgSim::Devices::LabJackThread.

## doStartUp()

virtual bool SurgSim::Framework::BasicThread::doStartUp | ( |  | ) |

private pure virtual

Implemented in SurgSim::Graphics::Manager, SurgSim::Physics::PhysicsManager, SurgSim::Graphics::OsgManager, SurgSim::Input::InputManager, SurgSim::Devices::ReplayPoseScaffold, SurgSim::Devices::OculusScaffold, SurgSim::Devices::NimbleScaffold, SurgSim::Devices::OpenNIScaffold, SurgSim::Devices::TrackIRThread, SurgSim::Devices::SixenseThread, SurgSim::Framework::BehaviorManager, SurgSim::Testing::MockPhysicsManager, SurgSim::Devices::RawMultiAxisThread, and SurgSim::Devices::LabJackThread.

## doUpdate()

bool SurgSim::Framework::BasicThread::doUpdate | ( | double | dt | ) |

private virtual

Implementation of actual work function for this thread, this has a default implementation to handle destruction better, as it could be called while the thread is under destruction, if left unimplemented this would trigger a call to a pure virtual function.

Returns
  false when the thread is done, this will stop execution

Reimplemented in SurgSim::Graphics::Manager, SurgSim::Physics::PhysicsManager, SurgSim::Graphics::OsgManager, SurgSim::Input::InputManager, SurgSim::Devices::ReplayPoseScaffold, SurgSim::Devices::TrackIRThread, SurgSim::Devices::OculusScaffold, SurgSim::Devices::OpenNIScaffold, SurgSim::Devices::NimbleScaffold, SurgSim::Testing::MockPhysicsManager, SurgSim::Devices::SixenseThread, SurgSim::Framework::BehaviorManager, SurgSim::Devices::RawMultiAxisThread, and SurgSim::Devices::LabJackThread.

## executeInitialization()

bool SurgSim::Framework::BasicThread::executeInitialization | ( |  | ) |

protected virtual

Reimplemented in SurgSim::Framework::ComponentManager.

## getCpuTime()

double SurgSim::Framework::BasicThread::getCpuTime | ( |  | ) | const

Returns
  the cumulated cpu time taken to run all update since last reset or thread creation

Note
  Only the latest 1,000,000 frames since last reset are cumulated, so if the timer is never reset,
  the Cpu time will not increase past that limit.

## getName()

std::string SurgSim::Framework::BasicThread::getName | ( |  | ) | const

Returns
  the name of the thread

## getThread()

boost::thread & SurgSim::Framework::BasicThread::getThread | ( |  | ) |

Returns
  the boost threading object

## getUpdateCount()

size_t SurgSim::Framework::BasicThread::getUpdateCount | ( |  | ) | const

Returns
  the number of updates done since last reset or thread creation

Note
  The update count since last reset has a limit of 1,000,000.

## initialize()

bool SurgSim::Framework::BasicThread::initialize | ( |  | ) |

protected

Trigger the initialization of this object, this will be called before all other threads doStartup() are called.

Returns
  true on success

## isIdle()

bool SurgSim::Framework::BasicThread::isIdle | ( |  | ) |

Query if this thread is in idle state or not.

Returns
  true if the thread is in idle state, false otherwise.

## isInitialized()

bool SurgSim::Framework::BasicThread::isInitialized | ( |  | ) |

Query if this object is initialized.

Returns
  true if initialized, false if not.

## isRunning()

bool SurgSim::Framework::BasicThread::isRunning | ( |  | ) | const

Query if this object is running.

Returns
  true if the threads update() function is being called

## isSynchronous()

bool SurgSim::Framework::BasicThread::isSynchronous | ( |  | ) |

Query if this object is synchronized.

Returns
  true if synchronized, false if not.

## operator()()

void SurgSim::Framework::BasicThread::operator() | ( |  | ) |

This is what boost::thread executes on thread creation.

## resetCpuTimeAndUpdateCount()

void SurgSim::Framework::BasicThread::resetCpuTimeAndUpdateCount | ( |  | ) |

Reset the cpu time and the update count to 0.

## setIdle()

void SurgSim::Framework::BasicThread::setIdle | ( | bool | isIdle | ) |

Set/Unset the thread in an idle state (doUpdate() called or not in the update() method)

Parameters

  isIdle | True to set the thread in an idle state, false otherwise

## setRate()

void SurgSim::Framework::BasicThread::setRate | ( | double | val | ) |

inline

Set the update rate of the thread.

Parameters

  val | rate in hertz (updates per second) of the thread

## setSynchronous()

bool SurgSim::Framework::BasicThread::setSynchronous | ( | bool | val | ) |

Sets the thread to synchronized execution in concert with the startup barrier, the startup barrier has to exist for this call to succeed.

When the thread is set to run synchronized it will only execute one update at a time and then wait for the startup barrier to wake it up again.

Parameters

  val | if true the thread will need to be controlled via the barrier.

Returns
  the actual value of isSynchronous()

Note
  HS-2013-nov-01 Currently mostly for use in unit tests and debugging, when multiple thread with differing rates are being synchronized the call rates will not correspond to the expected rates.

## start()

void SurgSim::Framework::BasicThread::start | ( | std::shared_ptr< Barrier > | startupBarrier = `nullptr`,
|  | bool | isSynchronous = `false`
| ) |  |

C++11 introduced noexcept.

Live cycle functions, public implementation. All of these have virtual partners as private functions Start the thread from the outside, this will call the private run() function that can be overridden for each implementor of this interface.

Parameters

  startupBarrier | is a barrier it synchronizes a group of thread that should go through their startup sequence in step.
  isSynchronous | when true the thread will wait on the barrier after each call to update(dt), this means that only one step will be performed at a time

## startUp()

bool SurgSim::Framework::BasicThread::startUp | ( |  | ) |

protected

Trigger the startup of this object, this will be called after all other threads doInit() was called the thread will only enter the run loop triggering upated() if all threads doInit() and doStartup() returned true.

Returns
  true on success

## stop()

void SurgSim::Framework::BasicThread::stop | ( |  | ) |

Stopping the execution, blocks until the running thread has actually stopped,.

Note
  When the thread is in synchronous mode, it needs to be stopped with a call to the barrier wait function with an argument of false, of course it can always be stopped by going back to asynchronous mode and then calling stop

## waitForBarrier()

bool SurgSim::Framework::BasicThread::waitForBarrier | ( | bool | success | ) |

protected

## Member Data Documentation

## m_isIdle

bool SurgSim::Framework::BasicThread::m_isIdle

private

## m_isInitialized

bool SurgSim::Framework::BasicThread::m_isInitialized

private

## m_isRunning

bool SurgSim::Framework::BasicThread::m_isRunning

private

## m_isSynchronous

bool SurgSim::Framework::BasicThread::m_isSynchronous

private

## m_logger

std::shared_ptr<SurgSim::Framework::Logger> SurgSim::Framework::BasicThread::m_logger

protected

Logger for this thread.

## m_mutexStartStop

boost::mutex SurgSim::Framework::BasicThread::m_mutexStartStop

private

## m_name

std::string SurgSim::Framework::BasicThread::m_name

private

## m_period

boost::chrono::duration<double> SurgSim::Framework::BasicThread::m_period

private

## m_startupBarrier

std::shared_ptr<Barrier> SurgSim::Framework::BasicThread::m_startupBarrier

private

## m_stopExecution

bool SurgSim::Framework::BasicThread::m_stopExecution

private

## m_thisThread

boost::thread SurgSim::Framework::BasicThread::m_thisThread

private

## m_timer

Timer SurgSim::Framework::BasicThread::m_timer

protected

Timer to measure the actual time taken to doUpdate.

The documentation for this class was generated from the following files:

- SurgSim/Framework/BasicThread.h
- SurgSim/Framework/BasicThread.cpp