OpenWalnut  1.4.0
WThreadedRunner.h
1 //---------------------------------------------------------------------------
2 //
3 // Project: OpenWalnut ( http://www.openwalnut.org )
4 //
5 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
6 // For more information see http://www.openwalnut.org/copying
7 //
8 // This file is part of OpenWalnut.
9 //
10 // OpenWalnut is free software: you can redistribute it and/or modify
11 // it under the terms of the GNU Lesser General Public License as published by
12 // the Free Software Foundation, either version 3 of the License, or
13 // (at your option) any later version.
14 //
15 // OpenWalnut is distributed in the hope that it will be useful,
16 // but WITHOUT ANY WARRANTY; without even the implied warranty of
17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 // GNU Lesser General Public License for more details.
19 //
20 // You should have received a copy of the GNU Lesser General Public License
21 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
22 //
23 //---------------------------------------------------------------------------
24 
25 #ifndef WTHREADEDRUNNER_H
26 #define WTHREADEDRUNNER_H
27 
28 #include <stdint.h>
29 
30 #include <string>
31 
32 #ifndef Q_MOC_RUN
33 #include <boost/function.hpp>
34 #endif
35 #ifndef Q_MOC_RUN
36 #include <boost/signals2.hpp>
37 #endif
38 
39 #ifndef Q_MOC_RUN
40 #include <boost/thread.hpp>
41 #endif
42 #ifndef Q_MOC_RUN
43 #include <boost/thread/thread.hpp>
44 #endif
45 
46 #include "WFlag.h"
47 #include "WThreadedRunnerSignals.h"
48 
49 /**
50  * Base class for all classes needing to be executed in a separate thread.
51  */
52 class WThreadedRunner // NOLINT
53 {
54 public:
55  /**
56  * Type used for simple thread functions.
57  */
58  typedef boost::function< void ( void ) > THREADFUNCTION;
59 
60  /**
61  * Default constructor.
62  */
64 
65  /**
66  * Destructor.
67  */
68  virtual ~WThreadedRunner();
69 
70  /**
71  * Run thread.
72  */
73  virtual void run();
74 
75  /**
76  * Run thread. This does not start threadMain(() but runs a specified function instead.
77  *
78  * \param f the function to run instead of the threadMain method.
79  */
80  void run( THREADFUNCTION f );
81 
82  /**
83  * Wait for the thread to be finished.
84  *
85  * \param requestFinish true if the thread should be notified.
86  */
87  void wait( bool requestFinish = false );
88 
89  /**
90  * This method's purpose is to request a stop without waiting for it.
91  */
92  virtual void requestStop();
93 
94  /**
95  * Connects a specified notify function with a signal this thread instance is offering.
96  *
97  * \exception WSignalSubscriptionFailed thrown if the signal can't be connected.
98  *
99  * \param signal the signal to connect to.
100  * \param notifier the notifier function to bind.
101  *
102  * \return connection descriptor.
103  */
104  virtual boost::signals2::connection subscribeSignal( THREAD_SIGNAL signal, t_ThreadErrorSignalHandlerType notifier );
105 
106  /**
107  * Checks whether this thread has been crashed. This will be true whenever the code in the thread throws an unhandled
108  * exception.
109  *
110  * \return true if there has been an exception during threadMain().
111  */
112  const WBoolFlag& isCrashed() const;
113 
114  /**
115  * Get the message of the exception finally causing the crash.
116  *
117  * \return the message
118  */
119  const std::string& getCrashMessage() const;
120 
121  /**
122  * Set the name of the thread. This can be handy for debugging as it gets set on Linux as the pthread name. You MUST set this before starting
123  * the thread.
124  *
125  * \param name the name
126  */
127  void setThreadName( std::string name );
128 
129  /**
130  * Returns the current thread name
131  *
132  * \return the name, empty if no name was specified.
133  */
134  std::string getThreadName() const;
135 
136  /**
137  * Static function to set the name of the calling thread.
138  *
139  * \param name the name.
140  */
141  static void setThisThreadName( std::string name );
142 protected:
143  /**
144  * Function that has to be overwritten for execution. It gets executed in a separate thread after run()
145  * has been called.
146  */
147  virtual void threadMain();
148 
149  /**
150  * Gets called when the thread should be stopped. The purpose of this method is to allow derived classes to handle this kind of event.
151  */
152  virtual void notifyStop();
153 
154  /**
155  * Thread instance.
156  */
157  boost::thread m_thread;
158 
159  /**
160  * Give remaining execution timeslice to another thread.
161  */
162  void yield() const;
163 
164  /**
165  * Sets thread asleep.
166  *
167  * \param t time to sleep in seconds.
168  */
169  void sleep( const int32_t t ) const;
170 
171  /**
172  * Sets thread asleep.
173  *
174  * \param t time to sleep in microseconds.
175  */
176  void msleep( const int32_t t ) const;
177 
178  /**
179  * Let the thread sleep until a stop request was given.
180  */
181  void waitForStop();
182 
183  /**
184  * Condition getting fired whenever the thread should quit. This is useful for waiting for stop requests.
185  */
187 
188  /**
189  * This method is called if an exception was caught, which came from the custom thread code. This method is virtual and allows you to
190  * overwrite the default behaviour. If you overwrite this method, you should call \ref handleDeadlyException or
191  * WThreadedRunner::onThreadException if you are finished with your customized code.
192  *
193  * \param e the exception that was caught.
194  */
195  virtual void onThreadException( const WException& e );
196 
197  /**
198  * Handle the specified exception which was not caught in the thread, which basically means the thread has crashed. This triggers the error
199  * notification and marks the thread as crashed. If you write your own exception/error mechanism (like \ref WModule), you should take care
200  * that these method gets called.
201  *
202  * \note this method does not re-throw the exception
203  * \note you should specify a custom sender string if you overwrite \ref onThreadException.
204  *
205  * \param e the exception
206  * \param sender allows to customize the sender information in the log entry created by this method.
207  */
208  void handleDeadlyException( const WException& e, std::string sender = "WThreadedRunner" );
209 
210  /**
211  * True whenever an exception is thrown during threadMain.
212  */
214 
215  /**
216  * The crash message. Only filled if m_isCrashed is true.
217  */
218  std::string m_crashMessage;
219 
220 private:
221  /**
222  * Disallow copy construction.
223  *
224  * \param rhs the other threaded runner.
225  */
226  WThreadedRunner( const WThreadedRunner & rhs );
227 
228  /**
229  * Disallow copy assignment.
230  *
231  * \param rhs the other threaded runner.
232  * \return this.
233  */
234  WThreadedRunner& operator=( const WThreadedRunner & rhs );
235 
236  /**
237  * Signal fired whenever a thread throws an exception/error.
238  */
239  t_ThreadErrorSignalType signal_thread_error;
240 
241  /**
242  * The is the thread entry point. It does exception handling and calls threadMain.
243  */
244  void threadMainSave();
245 
246  /**
247  * This threads name.
248  */
249  std::string m_threadName;
250 };
251 
252 #endif // WTHREADEDRUNNER_H
virtual ~WThreadedRunner()
Destructor.
virtual void run()
Run thread.
boost::thread m_thread
Thread instance.
const std::string & getCrashMessage() const
Get the message of the exception finally causing the crash.
void threadMainSave()
The is the thread entry point.
const WBoolFlag & isCrashed() const
Checks whether this thread has been crashed.
virtual boost::signals2::connection subscribeSignal(THREAD_SIGNAL signal, t_ThreadErrorSignalHandlerType notifier)
Connects a specified notify function with a signal this thread instance is offering.
void msleep(const int32_t t) const
Sets thread asleep.
virtual void threadMain()
Function that has to be overwritten for execution.
boost::function< void(void) > THREADFUNCTION
Type used for simple thread functions.
void handleDeadlyException(const WException &e, std::string sender="WThreadedRunner")
Handle the specified exception which was not caught in the thread, which basically means the thread h...
Base class for all classes needing to be executed in a separate thread.
void sleep(const int32_t t) const
Sets thread asleep.
std::string m_crashMessage
The crash message.
WThreadedRunner & operator=(const WThreadedRunner &rhs)
Disallow copy assignment.
static void setThisThreadName(std::string name)
Static function to set the name of the calling thread.
std::string m_threadName
This threads name.
WThreadedRunner()
Default constructor.
WBoolFlag m_shutdownFlag
Condition getting fired whenever the thread should quit.
WBoolFlag m_isCrashed
True whenever an exception is thrown during threadMain.
virtual void onThreadException(const WException &e)
This method is called if an exception was caught, which came from the custom thread code...
virtual void requestStop()
This method's purpose is to request a stop without waiting for it.
void setThreadName(std::string name)
Set the name of the thread.
void yield() const
Give remaining execution timeslice to another thread.
void wait(bool requestFinish=false)
Wait for the thread to be finished.
void waitForStop()
Let the thread sleep until a stop request was given.
t_ThreadErrorSignalType signal_thread_error
Signal fired whenever a thread throws an exception/error.
Basic exception handler.
Definition: WException.h:38
std::string getThreadName() const
Returns the current thread name.
virtual void notifyStop()
Gets called when the thread should be stopped.