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

void	start (std::shared_ptr< Barrier > startupBarrier=nullptr, bool isSynchronous=false)
	Live cycle functions, public implementation. 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.

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.

bool	ignoresExceptions () const

void	setIgnoreExceptions (bool val)

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.

std::shared_ptr< SurgSim::Framework::Logger >	m_logger
	Logger for this thread.

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.

Member Function Documentation

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

§ 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`
	)

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

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

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

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

§ getCpuTime()

§ getName()

§ getThread()

§ getUpdateCount()

§ initialize()

§ isIdle()

§ isInitialized()

§ isRunning()

§ isSynchronous()

§ setIdle()

§ setRate()

§ setSynchronous()

§ start()

§ startUp()

§ stop()