DispatcherThread Class Reference

Class that can be used whenever you want to have ONE thread where several handlers are assigned to. More...

#include <fw/DispatcherThread.h>

Classes
struct	QueueItem
	XXX. More...
class	Timer
	Class representing timers and tasks that can be registered and executed by the dispatcher thread. More...
class	XUnrecoverableFailure
	Exception that can be thrown in every handler to indicate an unrecoverable failure. More...

Public Types
typedef boost::function< void(const Timer &)>	TimerCallback
	Signature of a timer/task callback function. More...
typedef boost::shared_ptr< Timer >	TimerPtr

Public Member Functions
	DispatcherThread (const std::string &name="")
	Construct a dispatcher thread with an optional name. More...
virtual	~DispatcherThread ()
void	setName (const std::string &name)
bool	insertRunnable (IRunnablePtr runnable, bool singleton=false, Time time=Time::now())
void	removeRunnable (IRunnablePtr runnable)
void	addImmediateHandler (IRunnablePtr runnable)
	Adds a runnable that is executed once as soon as possible within the DispatcherThreads main thread. More...
template<typename F >
void	addImmediateHandlerFunction (F &&fn, DiagnosticsModulePtr errorModule=nullptr)
	Adds a function that is executed once as soon as possible within the DispatcherThreads main thread. More...
void	addFinalizeHandler (IRunnablePtr runnable)
	Adds a runnable that is executed once just before the thread terminates. More...
template<typename F >
void	addFinalizeHandlerFunction (F &&fn, DiagnosticsModulePtr errorModule=nullptr)
	Adds a function that is executed once just before the thread terminates. More...
TimerPtr	createTimer (Duration period, Duration periodTolerance, TimerCallback callback, bool oneshot=false)
	Creates and adds a timer that gets called cyclic in a given period and has a tolerance for exceeding the given period. More...
TimerPtr	createTimer (Duration period, TimerCallback callback, bool oneshot=false)
	Creates and adds a timer that gets called cyclic in a given period (if oneshot is false) and calls the given callback on every invocation. More...
TimerPtr	createTimer (Time time, TimerCallback callback)
	Creates a timer that calls callback exactly once at the given time. More...
void	removeTimer (TimerPtr timer)
	Removes the given timer (timer callback will not be called again and timer will not be rescheduled). More...
bool	hasTimer (TimerPtr timer)
	Returns true, if the given timer. More...
void	start (bool startThread=true)
	Starts the dispatcher. More...
void	stop ()
	Stops the dispatcher, if it is running. More...
bool	hasUnrecoverableFailure () const
	Returns true, if there was a failure while processing the immediate handlers. More...
bool	isRunning () const
	Returns true, if the dispatcher currently is running. More...
bool	spin (Duration maxWait=Duration::infinity())
	Invoke the dispatcher manually (instead of starting a separate thread via the start() method). More...
boost::thread::id	getThreadID () const
	Returns the thread id of the thread that is used to process the dispatcher. More...
bool	hasWork (Time horizon=Time::now()) const
	Checks if there is a work item (either an immediate handler or an item in the execution queue with an execution time before horizon). More...

Protected Types
typedef IteratablePriorityQueue< QueueItem, std::deque< QueueItem > >	Queue

Protected Member Functions
void	run ()
	Runs this thread dispatchers main loop. More...
void	postProcessTimer (TimerPtr timer)

Protected Attributes
Queue	mQueue
std::set< IRunnablePtr >	mPendingRunnables
boost::mutex	mConditionMutex
boost::condition_variable	mCondition
std::string	mName
std::list< IRunnablePtr >	mImmediateHandlers
boost::mutex	mImmediateHandlerMutex
std::list< IRunnablePtr >	mFinalizeHandlers
boost::mutex	mFinalizeHandlerMutex
std::set< TimerPtr >	mTimers
boost::mutex	mTimerMutex
bool	mUnrecoverableFailure
bool	mIsRunning
bool	mInterruptionRequested
boost::thread	mThread
boost::thread::id	mThreadId
bool	mPendingSignal

Detailed Description

Class that can be used whenever you want to have ONE thread where several handlers are assigned to.

The dispatcher waits for a certain signal and processes all handlers afterwards. Moreover you can assign timers that are called periodically or tasks that are called upon their invocation time, all from within the same thread.

This class can be used together with boost::thread by binding the run() method to a boost thread: /code DispatcherThread dispatcher; ... boost::thread t(boost::bind(&Dispatcher::run(), &dispatcher)) can be used. /endcode

Member Typedef Documentation

TimerCallback

typedef boost::function<void(const Timer&)> TimerCallback

Signature of a timer/task callback function.

TimerPtr

typedef boost::shared_ptr<Timer> TimerPtr

Queue

typedef IteratablePriorityQueue<QueueItem, std::deque<QueueItem> > Queue

protected

Constructor & Destructor Documentation

DispatcherThread()

DispatcherThread

(

const std::string &

name = ""

)

Construct a dispatcher thread with an optional name.

Name will be used when registering the dispatcher at the thread monitor.

~DispatcherThread()

virtual ~DispatcherThread ( )

virtual

Member Function Documentation

setName()

void setName

(

const std::string &

name

)

insertRunnable()

bool insertRunnable	(	IRunnablePtr	runnable,
		bool	singleton = false,
		Time	time = Time::now()
	)

removeRunnable()

void removeRunnable

(

IRunnablePtr

runnable

)

addImmediateHandler()

void addImmediateHandler

(

IRunnablePtr

runnable

)

Adds a runnable that is executed once as soon as possible within the DispatcherThreads main thread.

If the immediate handler throws an exception, the DispatcherThread enters an unrecoverable error state. Additionally, a diagnostics module can be specified where the error is reported.

addImmediateHandlerFunction()

void addImmediateHandlerFunction ( F &&  fn, DiagnosticsModulePtr  errorModule = nullptr  )

inline

Adds a function that is executed once as soon as possible within the DispatcherThreads main thread.

If the immediate handler throws an exception, the DispatcherThread enters an unrecoverable error state. Additionally, a diagnostics module can be specified where the error is reported.

addFinalizeHandler()

void addFinalizeHandler

(

IRunnablePtr

runnable

)

Adds a runnable that is executed once just before the thread terminates.

addFinalizeHandlerFunction()

void addFinalizeHandlerFunction ( F &&  fn, DiagnosticsModulePtr  errorModule = nullptr  )

inline

Adds a function that is executed once just before the thread terminates.

Additionally, a diagnostics module can be specified where the error is reported if there is any.

createTimer() [1/3]

TimerPtr createTimer	(	Duration	period,
		Duration	periodTolerance,
		TimerCallback	callback,
		bool	oneshot = false
	)

Creates and adds a timer that gets called cyclic in a given period and has a tolerance for exceeding the given period.

(if oneshot is false) and calls the given callback on every invocation.

Returns

pointer to created timer. Can be used for removeTimer().

createTimer() [2/3]

TimerPtr createTimer	(	Duration	period,
		TimerCallback	callback,
		bool	oneshot = false
	)

Creates and adds a timer that gets called cyclic in a given period (if oneshot is false) and calls the given callback on every invocation.

Returns

pointer to created timer. Can be used for removeTimer().

createTimer() [3/3]

TimerPtr createTimer	(	Time	time,
		TimerCallback	callback
	)

Creates a timer that calls callback exactly once at the given time.

Returns

pointer to created timer. Can be used for removeTimer().

removeTimer()

void removeTimer

(

TimerPtr

timer

)

Removes the given timer (timer callback will not be called again and timer will not be rescheduled).

Calling start on a removed timer will not start it again.

hasTimer()

bool hasTimer

(

TimerPtr

timer

)

Returns true, if the given timer.

start()

void start

(

bool

startThread = true

)

Starts the dispatcher.

If the dispatcher is running already this method does nothing. The dispatcher will call all init handlers first and removes them afterwards. This ensures, that when stopping and starting the dispatcher again, the init handlers are not called again. If one of the init handlers fails, the dispatcher enters an unrecoverable error state and cannot be started again, since the state of the entity that failed to initialize is undefined.

Usually the dispatcher starts its own process thread, however, if you set the optional parameter to false, no thread will be started. Instead, you need to call the spin() method on your own.

Exceptions

XLogical

If a previous initialization has failed, and the dispatcher cannot be started again.

stop()

void stop

(

)

Stops the dispatcher, if it is running.

This method blocks, until the dispatcher thread (if there is any) has terminated and was joined.

hasUnrecoverableFailure()

bool hasUnrecoverableFailure

(

)

const

Returns true, if there was a failure while processing the immediate handlers.

This is an unrecoverable failure that will disallow the further execution of the dispatcher.

isRunning()

bool isRunning

(

)

const

Returns true, if the dispatcher currently is running.

spin()

bool spin

(

Duration

maxWait = Duration::infinity()

)

Invoke the dispatcher manually (instead of starting a separate thread via the start() method).

spin() must be called periodically, to allow the dispatcher to work properly. The caller should stop calling spin(), when false is returned.

Usually the spin() method waits for events and signals of the dispatcher, you can specify the max. time that is spent in the call using the maxWait parameter. If this parameter is set to 0, spin() will not block at all. If it is set to another duration, it will wait until the next signal or event or stop request or the specified wait duration is reached.

Parameters

[in]

maxWait

maximum wait time for new events

getThreadID()

boost::thread::id getThreadID ( ) const

inline

Returns the thread id of the thread that is used to process the dispatcher.

This usually will be the dispatcher thread that is started in the start() method. However, if no thread was launched in the start() method, this method returns the id of the thread that is calling the spin() method.

hasWork()

bool hasWork

(

Time

horizon = Time::now()

)

const

Checks if there is a work item (either an immediate handler or an item in the execution queue with an execution time before horizon).

One application of this member function is to call spin() in a test setting till every job is done.

Parameters

horizon

specifies the interval [-inf, horizon] to check for work. If horizon is invalid, this method only checks the immediate handler.

Returns

True if there are immediate handlers. If horizon is valid, true if there are any queue items with time <= horizon. False otherwise.

run()

void run ( )

protected

Runs this thread dispatchers main loop.

This will invoke all init handlers immediately after the thread is launched. Afterwards the thread will wait for a signal. If the signal arrives the signal handlers are called. Additionally, the timers after their invocation time is reached.

postProcessTimer()

void postProcessTimer ( TimerPtr  timer )

protected

Member Data Documentation

mQueue

Queue mQueue

protected

mPendingRunnables

std::set<IRunnablePtr> mPendingRunnables

protected

mConditionMutex

boost::mutex mConditionMutex

mutableprotected

mCondition

boost::condition_variable mCondition

protected

mName

std::string mName

protected

mImmediateHandlers

std::list<IRunnablePtr> mImmediateHandlers

protected

mImmediateHandlerMutex

boost::mutex mImmediateHandlerMutex

mutableprotected

mFinalizeHandlers

std::list<IRunnablePtr> mFinalizeHandlers

protected

mFinalizeHandlerMutex

boost::mutex mFinalizeHandlerMutex

protected

mTimers

std::set<TimerPtr> mTimers

protected

mTimerMutex

boost::mutex mTimerMutex

protected

mUnrecoverableFailure

bool mUnrecoverableFailure

protected

mIsRunning

bool mIsRunning

protected

mInterruptionRequested

bool mInterruptionRequested

protected

mThread

boost::thread mThread

protected

mThreadId

boost::thread::id mThreadId

protected

mPendingSignal

bool mPendingSignal

protected

---

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

• framework/include/fw/DispatcherThread.h