All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Public Member Functions | Protected Member Functions | Private Member Functions | Private Attributes | List of all members
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:
Inheritance graph
[legend]
Collaboration diagram for SurgSim::Framework::BasicThread:
Collaboration graph
[legend]

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...
 

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 ()
 

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< Barrierm_startupBarrier
 
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

SurgSim::Framework::BasicThread::BasicThread ( const std::string &  name = "Unknown Thread")
explicit
SurgSim::Framework::BasicThread::~BasicThread ( )
virtualnoexcept

C++11 introduced noexcept.

Member Function Documentation

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

Prepares the thread for its execution to be stopped.

Note
Called from this thread before joined

Reimplemented in SurgSim::Graphics::OsgManager, and SurgSim::Device::RawMultiAxisThread.

virtual bool SurgSim::Framework::BasicThread::doInitialize ( )
privatepure virtual
virtual bool SurgSim::Framework::BasicThread::doStartUp ( )
privatepure virtual
bool SurgSim::Framework::BasicThread::doUpdate ( double  dt)
privatevirtual

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::Device::TrackIRThread, SurgSim::Testing::MockPhysicsManager, SurgSim::Device::SixenseThread, SurgSim::Framework::BehaviorManager, SurgSim::Device::RawMultiAxisThread, and SurgSim::Device::LabJackThread.

bool SurgSim::Framework::BasicThread::executeInitialization ( )
protectedvirtual
std::string SurgSim::Framework::BasicThread::getName ( ) const
Returns
the name of the thread
boost::thread & SurgSim::Framework::BasicThread::getThread ( )
Returns
the boost threading object
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
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.
bool SurgSim::Framework::BasicThread::isInitialized ( )

Query if this object is initialized.

Returns
true if initialized, false if not.
bool SurgSim::Framework::BasicThread::isRunning ( ) const

Query if this object is running.

Returns
true if the threads update() function is being called
bool SurgSim::Framework::BasicThread::isSynchronous ( )

Query if this object is synchronized.

Returns
true if synchronized, false if not.
void SurgSim::Framework::BasicThread::operator() ( )

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

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

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

Parameters
isIdleTrue to set the thread in an idle state, false otherwise
void SurgSim::Framework::BasicThread::setRate ( double  val)
inline

Set the update rate of the thread.

Parameters
valrate in hertz (updates per second) of the thread
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
valif 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.
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
startupBarrieris a barrier it synchronizes a group of thread that should go through their startup sequence in step.
isSynchronouswhen 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
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
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
bool SurgSim::Framework::BasicThread::waitForBarrier ( bool  success)
protected

Member Data Documentation

bool SurgSim::Framework::BasicThread::m_isIdle
private
bool SurgSim::Framework::BasicThread::m_isInitialized
private
bool SurgSim::Framework::BasicThread::m_isRunning
private
bool SurgSim::Framework::BasicThread::m_isSynchronous
private
std::string SurgSim::Framework::BasicThread::m_name
private
boost::chrono::duration<double> SurgSim::Framework::BasicThread::m_period
private
std::shared_ptr<Barrier> SurgSim::Framework::BasicThread::m_startupBarrier
private
bool SurgSim::Framework::BasicThread::m_stopExecution
private
boost::thread SurgSim::Framework::BasicThread::m_thisThread
private

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