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 #include <boost/function.hpp>
33 #include <boost/signals2.hpp>
34 
35 #include <boost/thread.hpp>
36 #include <boost/thread/thread.hpp>
37 
38 #include "WFlag.h"
39 #include "WThreadedRunnerSignals.h"
40 
41 /**
42  * Base class for all classes needing to be executed in a separate thread.
43  */
44 class WThreadedRunner // NOLINT
45 {
46 public:
47  /**
48  * Type used for simple thread functions.
49  */
50  typedef boost::function< void ( void ) > THREADFUNCTION;
51 
52  /**
53  * Default constructor.
54  */
56 
57  /**
58  * Destructor.
59  */
60  virtual ~WThreadedRunner();
61 
62  /**
63  * Run thread.
64  */
65  virtual void run();
66 
67  /**
68  * Run thread. This does not start threadMain(() but runs a specified function instead.
69  *
70  * \param f the function to run instead of the threadMain method.
71  */
72  void run( THREADFUNCTION f );
73 
74  /**
75  * Wait for the thread to be finished.
76  *
77  * \param requestFinish true if the thread should be notified.
78  */
79  void wait( bool requestFinish = false );
80 
81  /**
82  * This method's purpose is to request a stop without waiting for it.
83  */
84  virtual void requestStop();
85 
86  /**
87  * Connects a specified notify function with a signal this thread instance is offering.
88  *
89  * \exception WSignalSubscriptionFailed thrown if the signal can't be connected.
90  *
91  * \param signal the signal to connect to.
92  * \param notifier the notifier function to bind.
93  *
94  * \return connection descriptor.
95  */
96  virtual boost::signals2::connection subscribeSignal( THREAD_SIGNAL signal, t_ThreadErrorSignalHandlerType notifier );
97 
98  /**
99  * Checks whether this thread has been crashed. This will be true whenever the code in the thread throws an unhandled
100  * exception.
101  *
102  * \return true if there has been an exception during threadMain().
103  */
104  const WBoolFlag& isCrashed() const;
105 
106  /**
107  * Get the message of the exception finally causing the crash.
108  *
109  * \return the message
110  */
111  const std::string& getCrashMessage() const;
112 
113  /**
114  * 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
115  * the thread.
116  *
117  * \param name the name
118  */
119  void setThreadName( std::string name );
120 
121  /**
122  * Returns the current thread name
123  *
124  * \return the name, empty if no name was specified.
125  */
126  std::string getThreadName() const;
127 
128  /**
129  * Static function to set the name of the calling thread.
130  *
131  * \param name the name.
132  */
133  static void setThisThreadName( std::string name );
134 protected:
135  /**
136  * Function that has to be overwritten for execution. It gets executed in a separate thread after run()
137  * has been called.
138  */
139  virtual void threadMain();
140 
141  /**
142  * Gets called when the thread should be stopped. The purpose of this method is to allow derived classes to handle this kind of event.
143  */
144  virtual void notifyStop();
145 
146  /**
147  * Thread instance.
148  */
149  boost::thread m_thread;
150 
151  /**
152  * Give remaining execution timeslice to another thread.
153  */
154  void yield() const;
155 
156  /**
157  * Sets thread asleep.
158  *
159  * \param t time to sleep in seconds.
160  */
161  void sleep( const int32_t t ) const;
162 
163  /**
164  * Sets thread asleep.
165  *
166  * \param t time to sleep in microseconds.
167  */
168  void msleep( const int32_t t ) const;
169 
170  /**
171  * Let the thread sleep until a stop request was given.
172  */
173  void waitForStop();
174 
175  /**
176  * Condition getting fired whenever the thread should quit. This is useful for waiting for stop requests.
177  */
179 
180  /**
181  * This method is called if an exception was caught, which came from the custom thread code. This method is virtual and allows you to
182  * overwrite the default behaviour. If you overwrite this method, you should call \ref handleDeadlyException or
183  * WThreadedRunner::onThreadException if you are finished with your customized code.
184  *
185  * \param e the exception that was caught.
186  */
187  virtual void onThreadException( const WException& e );
188 
189  /**
190  * Handle the specified exception which was not caught in the thread, which basically means the thread has crashed. This triggers the error
191  * notification and marks the thread as crashed. If you write your own exception/error mechanism (like \ref WModule), you should take care
192  * that these method gets called.
193  *
194  * \note this method does not re-throw the exception
195  * \note you should specify a custom sender string if you overwrite \ref onThreadException.
196  *
197  * \param e the exception
198  * \param sender allows to customize the sender information in the log entry created by this method.
199  */
200  void handleDeadlyException( const WException& e, std::string sender = "WThreadedRunner" );
201 
202  /**
203  * True whenever an exception is thrown during threadMain.
204  */
206 
207  /**
208  * The crash message. Only filled if m_isCrashed is true.
209  */
210  std::string m_crashMessage;
211 
212 private:
213  /**
214  * Disallow copy construction.
215  *
216  * \param rhs the other threaded runner.
217  */
218  WThreadedRunner( const WThreadedRunner & rhs );
219 
220  /**
221  * Disallow copy assignment.
222  *
223  * \param rhs the other threaded runner.
224  * \return this.
225  */
226  WThreadedRunner& operator=( const WThreadedRunner & rhs );
227 
228  /**
229  * Signal fired whenever a thread throws an exception/error.
230  */
231  t_ThreadErrorSignalType signal_thread_error;
232 
233  /**
234  * The is the thread entry point. It does exception handling and calls threadMain.
235  */
236  void threadMainSave();
237 
238  /**
239  * This threads name.
240  */
241  std::string m_threadName;
242 };
243 
244 #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.