MIRA
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes | Public Types | Public Member Functions | Protected Types | Protected Member Functions | Protected Attributes | List of all members
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< TimerTimerPtr
 

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=NULL)
 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=NULL)
 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 (const 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...
 

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, Time now)
 

Protected Attributes

Queue mQueue
 
std::set< IRunnablePtrmPendingRunnables
 
boost::mutex mConditionMutex
 
boost::condition_variable mCondition
 
std::string mName
 
std::list< IRunnablePtrmImmediateHandlers
 
boost::mutex mImmediateHandlerMutex
 
std::list< IRunnablePtrmFinalizeHandlers
 
boost::mutex mFinalizeHandlerMutex
 
std::set< TimerPtrmTimers
 
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

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

Signature of a timer/task callback function.

typedef boost::shared_ptr<Timer> TimerPtr
typedef IteratablePriorityQueue<QueueItem, std::deque<QueueItem> > Queue
protected

Constructor & Destructor Documentation

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.

virtual ~DispatcherThread ( )
virtual

Member Function Documentation

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.

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.

void addImmediateHandlerFunction ( F &&  fn,
DiagnosticsModulePtr  errorModule = NULL 
)
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.

void addFinalizeHandler ( IRunnablePtr  runnable)

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

void addFinalizeHandlerFunction ( F &&  fn,
DiagnosticsModulePtr  errorModule = NULL 
)
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.

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

bool hasTimer ( TimerPtr  timer)

Returns true, if the given timer.

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
XLogicalIf a previous initialization has failed, and the dispatcher cannot be started again.
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.

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.

bool isRunning ( ) const

Returns true, if the dispatcher currently is running.

bool spin ( const 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]maxWaitmaximum wait time for new events
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.

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.

void postProcessTimer ( TimerPtr  timer,
Time  now 
)
protected

Member Data Documentation

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

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