Nektar++
Thread.h
Go to the documentation of this file.
1 ///////////////////////////////////////////////////////////////////////////////
2 //
3 // File Thread.h
4 //
5 // For more information, please see: http://www.nektar.info
6 //
7 // The MIT License
8 //
9 // Copyright (c) 2006 Division of Applied Mathematics, Brown University (USA),
10 // Department of Aeronautics, Imperial College London (UK), and Scientific
11 // Computing and Imaging Institute, University of Utah (USA).
12 //
13 // Permission is hereby granted, free of charge, to any person obtaining a
14 // copy of this software and associated documentation files (the "Software"),
15 // to deal in the Software without restriction, including without limitation
16 // the rights to use, copy, modify, merge, publish, distribute, sublicense,
17 // and/or sell copies of the Software, and to permit persons to whom the
18 // Software is furnished to do so, subject to the following conditions:
19 //
20 // The above copyright notice and this permission notice shall be included
21 // in all copies or substantial portions of the Software.
22 //
23 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
24 // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
26 // THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
28 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
29 // DEALINGS IN THE SOFTWARE.
30 //
31 // Description:
32 //
33 ///////////////////////////////////////////////////////////////////////////////
34 
35 #ifndef NEKTAR_LIB_UTILITIES_THREAD_H_
36 #define NEKTAR_LIB_UTILITIES_THREAD_H_
37 
38 #include <boost/thread/condition_variable.hpp>
39 #include <boost/thread/locks.hpp>
40 #include <boost/thread/mutex.hpp>
41 #include <boost/thread/thread.hpp>
42 #include <memory>
43 #include <queue>
44 #include <vector>
45 
47 
48 namespace Nektar
49 {
50 namespace Thread
51 {
52 
53 /**
54  * @brief Identifies the algorithm for scheduling.
55  *
56  * Currently there are two strategies to determine the number of jobs.
57  * e_static always loads m_chunkSize jobs onto each worker,
58  * e_guided uses a simple algorithm that loads a larger proportion of jobs
59  * onto the worker as the size of the queue list is large, but scales down
60  * to no fewer than m_chunkSize as the queue empties.
61  *
62  * @see ThreadManager::SetChunkSize()
63  *
64  */
66 {
68  e_dynamic
69 };
70 
71 class ThreadManager;
72 typedef std::shared_ptr<ThreadManager> ThreadManagerSharedPtr;
76 
77 /**
78  * @brief Base class for tasks to be sent to the ThreadManager to run.
79  *
80  * For a parallel region the overall task should be divided into tasklets, each
81  * capable of running independently of other tasklets, in any order. Each of
82  * these tasklets should be represented by an instance of a subclass of
83  * ThreadJob.
84  *
85  * Exactly how to partition the overall task will be problem dependent, but the
86  * ideal case is to have as many tasklets as there are worker threads (available
87  * through ThreadManager::GetNumWorkers() ) and for each tasklet to take the
88  * same amount of computational effort. Clearly, the tasklets should not
89  * overwrite one another's data, and data locations they are writing to should
90  * be sufficiently far apart to avoid cache ping pong.
91  *
92  * Subclasses may define as many variables and functions as are necessary.
93  * Instance of the subclass will be destructed once the ThreadManager has
94  * finished the Run() method.
95  */
96 class ThreadJob
97 {
98 public:
99  /// Base constructor
101  /// Base destructor.
103 
104  /**
105  * This method will be called when the task is loaded
106  * onto a worker thread and is ready to run. When Run
107  * has finished this instance will be destructed.
108  */
109  LIB_UTILITIES_EXPORT virtual void Run() = 0;
110 
111  /// Set number of worker threads.
112  LIB_UTILITIES_EXPORT void SetWorkerNum(unsigned int num);
113 
114 protected:
115  /**
116  * Returns an integer identifying the worker thread the
117  * job is running on. Value will be 0...N, where N is
118  * the number of active worker threads.
119  */
120  unsigned int GetWorkerNum();
121 
122 private:
123  unsigned int m_workerNum;
124 };
125 
126 /**
127  * @brief The interface class for the controller for worker threads and jobs.
128  *
129  * There may be multiple instances of implementations of this class.
130  * They are instantiated by ThreadMaster::CreateInstance(string, int).
131  * Use ThreadMaster::GetInstance(string)
132  * to get a pointer to the instance. Each ThreadManager is associated
133  * in ThreadMaster with a string.
134  *
135  * Jobs are sent to the worker threads by placing them in the
136  * queue with QueueJob() and QueueJobs(). Jobs may be run in
137  * indeterminate order. Jobs are permitted to run *immediately*
138  * they are queued. If this is not desired set the number of active
139  * workers to 0 until all jobs are queued.
140  *
141  * Jobs are taken from the master queue by active worker threads.
142  *
143  * We have the concept of the *master thread*. This is the thread
144  * that instantiates the ThreadManager, calls QueueJob(), Wait()
145  * and so on. This thread must be included in the number of threads
146  * started when the ThreadManager is created, so that no more than
147  * this number of threads are ever executing work at any time. The
148  * master thread is assumed to be working unless it is in Wait().
149  *
150  * Thus if the ThreadManager is called with CreateInstance(string s, int N)
151  * there should be N threads /em including the master thread. If the master
152  * thread calls Wait() (which causes the master thread to sleep until
153  * the job queue is empty) then the master thread should become available
154  * to run jobs from the queue.
155  *
156  * Only the master thread should call ThreadManager methods. Although
157  * it should always be possible for code to identify whether it's the
158  * master thread (through design) there is a InThread() method that returns
159  * true if the thread is a worker.
160  *
161  */
162 class ThreadManager : public std::enable_shared_from_this<ThreadManager>
163 {
164 public:
165  /// Destructor.
167  /**
168  * @brief Pass a list of tasklets to the master queue.
169  * @param joblist Vector of ThreadJob pointers.
170  *
171  * The list of jobs is copied into the master queue. Jobs may be
172  * available for running *immediately*, even before the list has been
173  * fully copied. This can have consequences for the scheduling. If
174  * this is an issue then suspend the workers with SetNumWorkers(0) until
175  * the jobs are queued.
176  *
177  * @see SchedType
178  */
180  std::vector<ThreadJob *> &joblist) = 0;
181  /**
182  * @brief Pass a single job to the master queue.
183  * @param job A pointer to a ThreadJob subclass.
184  *
185  * The job may become available for running immediately. If this is an
186  * issue then suspend the workers with SetNumWorkers(0) until the jobs
187  * are queued.
188  */
189  LIB_UTILITIES_EXPORT virtual void QueueJob(ThreadJob *job) = 0;
190  /**
191  * @brief Return the number of active workers.
192  *
193  * Active workers are threads that are either running jobs
194  * or are waiting for jobs to be queued.
195  */
196  LIB_UTILITIES_EXPORT virtual unsigned int GetNumWorkers() = 0;
197  /**
198  * @brief Returns the worker number of the executing thread.
199  *
200  * Returns an unsigned int between 0 and N-1 where N is the number of
201  * active worker threads. Repeated calls from within this thread will
202  * always return the same value and the value will be the same as
203  * returned from ThreadJob.GetWorkerNum(). The same thread will run a
204  * job until it finishes.
205  *
206  * Although if there are active threads then thread 0 is always one of
207  * them, it is possible that thread 0 does not run for a given set of
208  * jobs. For example, if there are 4 active threads and 3 jobs are
209  * submitted with a e_static scheduling strategy and a chunksize of 1,
210  * then it is possible that threads 1,2, and 3 pick up the jobs and
211  * thread 0 remains idle.
212  *
213  * Returns 0 if called by non-thread.
214  */
215  LIB_UTILITIES_EXPORT virtual unsigned int GetWorkerNum() = 0;
216  /**
217  * @brief Sets the number of active workers.
218  * @param num The number of active workers.
219  *
220  * Active workers are threads that are either running jobs or are
221  * waiting for jobs to be queued.
222  *
223  * If num is greater than the maximum allowed number of active workers,
224  * then the maximum value will be used instead.
225  */
226  LIB_UTILITIES_EXPORT virtual void SetNumWorkers(const unsigned int num) = 0;
227  /**
228  * @brief Sets the number of active workers to the maximum.
229  *
230  * Sets the number of active workers to the maximum available.
231  */
233  /**
234  * @brief Gets the maximum available number of threads.
235  * @return The maximum number of workers.
236  */
237  LIB_UTILITIES_EXPORT virtual unsigned int GetMaxNumWorkers() = 0;
238  /**
239  * @brief Waits until all queued jobs are finished.
240  *
241  * If there are no jobs running or queued this method returns
242  * immediately. Otherwise it blocks until the queue is empty and the
243  * worker threads are idle.
244  *
245  * Implementations *must* ensure that trivial deadlocks are not possible
246  * from this method, that is, that this code:
247  * @code
248  * // assume ThreadManager* tm
249  * // assume SomeJob is subclass of ThreadJob
250  * // assume SomeJob job
251  *
252  * tm->SetNumWorkers(0);
253  * tm->QueueJob(job);
254  * tm->Wait();
255  * @endcode
256  * does not wait forever. Since the master thread is counted in the
257  * number of worker threads, implementations should increase the number
258  * of active workers by 1 on entering Wait().
259  */
260  LIB_UTILITIES_EXPORT virtual void Wait() = 0;
261  /**
262  * @brief Controls how many jobs are sent to each worker at a time.
263  *
264  * The exact meaning of this parameter depends on the current scheduling
265  * algorithm.
266  *
267  * @see SchedType
268  * @see SetSchedType()
269  */
270  LIB_UTILITIES_EXPORT virtual void SetChunkSize(unsigned int chnk) = 0;
271  /**
272  * @brief Sets the current scheduling algorithm.
273  * @see SetChunkSize()
274  */
276  /**
277  * @brief Indicates whether the code is in a worker thread or not.
278  * @return True if the caller is in a worker thread.
279  */
280  LIB_UTILITIES_EXPORT virtual bool InThread() = 0;
281  /**
282  * @brief A calling threads holds until all active threads call this
283  * method.
284  *
285  * When called, the calling thread will sleep until all active workers
286  * have called this method. Once all have done so all threads awake and
287  * continue execution.
288  *
289  * @note Behaviour is likely undefined if the number of active workers
290  * is altered after a thread has called this method. It is only safe to
291  * call SetNumWorkers() when no threads are holding.
292  */
293  LIB_UTILITIES_EXPORT virtual void Hold() = 0;
294  /**
295  * @brief Returns a description of the type of threading.
296  *
297  * E.g. "Threading with Boost"
298  */
299  LIB_UTILITIES_EXPORT virtual const std::string &GetType() const = 0;
300 
301  /// ThreadManager implementation.
302  LIB_UTILITIES_EXPORT virtual bool IsInitialised();
303 
304  inline int GetThrFromPartition(int pPartition)
305  {
306  return pPartition % GetMaxNumWorkers();
307  }
308 
309  inline int GetRankFromPartition(int pPartition)
310  {
311  return pPartition / GetMaxNumWorkers();
312  }
313 
314  inline int GetPartitionFromRankThr(int pRank, unsigned int pThr)
315  {
316  return pRank * GetMaxNumWorkers() + pThr;
317  }
318 };
319 
320 typedef boost::unique_lock<boost::shared_mutex> WriteLock;
321 typedef boost::shared_lock<boost::shared_mutex> ReadLock;
322 
323 /**
324  * A class to manage multiple ThreadManagers. It also acts as a cut-out during
325  * static initialisation, where code attempts to grab a ThreadManager before any
326  * can have been initialised. When this happens the ThreadMaster creates a
327  * simple implementation of ThreadManager, ThreadStartupManager, which behaves
328  * as a single-threaded ThreadManager that fails if anything non-trivial is
329  * attempted. This means code should be cautious about caching the value of
330  * GetInstance(string), as it might change once that particular threading system
331  * is initialised.
332  *
333  * Multiple ThreadManagers should now be possible. Each is identified with a
334  * string and can be recovered by calling
335  * Thread::GetThreadMaster().GetInstance(string).
336  *
337  * ThreadMaster is thread-safe apart from CreateInstance. Call CreateInstance
338  * in single threaded code only.
339  */
341 {
342 private:
343  std::vector<ThreadManagerSharedPtr> m_threadManagers;
344  boost::shared_mutex m_mutex;
345  std::string m_threadingType;
346 
347 public:
349  {
352  };
353  /// Constructor
355  /// Destructor
357  /// Sets what ThreadManagers will be created in CreateInstance.
358  LIB_UTILITIES_EXPORT void SetThreadingType(const std::string &p_type);
359  /// Gets the ThreadManager associated with string s.
361  const ThreadManagerName t);
362  /// Creates an instance of a ThreadManager (which one is determined by
363  /// a previous call to SetThreadingType) and associates it with
364  /// the string s.
366  CreateInstance(const ThreadManagerName t, unsigned int nThr);
367 };
368 LIB_UTILITIES_EXPORT ThreadMaster &GetThreadMaster();
369 
370 /**
371  * @brief A default ThreadManager.
372  *
373  * This will be returned by ThreadMaster if a ThreadManager has not been
374  * initialised, such as if the code is still in static initialisation.
375  *
376  * This manager pretends to be a ThreadManager with 1 thread. It will
377  * cause an error if anything more than trivial functions are called.
378  */
380 {
381 public:
384  virtual ~ThreadStartupManager();
385  virtual void QueueJobs(std::vector<ThreadJob *> &joblist);
386  virtual void QueueJob(ThreadJob *job);
387  virtual unsigned int GetNumWorkers();
388  virtual unsigned int GetWorkerNum();
389  virtual void SetNumWorkers(const unsigned int num);
390  virtual void SetNumWorkers();
391  virtual unsigned int GetMaxNumWorkers();
392  virtual void Wait();
393  virtual void SetChunkSize(unsigned int chnk);
394  virtual void SetSchedType(SchedType s);
395  virtual bool InThread();
396  virtual void Hold();
397  virtual bool IsInitialised();
398  virtual const std::string &GetType() const;
399 
400 private:
401  // Do not allow assignment as m_type is const
403 
404  const std::string m_type;
405 };
406 
407 } // namespace Thread
408 
409 } // namespace Nektar
410 #endif /* THREAD_H_ */
#define LIB_UTILITIES_EXPORT
Provides a generic Factory class.
Definition: NekFactory.hpp:105
Base class for tasks to be sent to the ThreadManager to run.
Definition: Thread.h:97
virtual ~ThreadJob()
Base destructor.
Definition: Thread.cpp:66
void SetWorkerNum(unsigned int num)
Set number of worker threads.
Definition: Thread.cpp:76
virtual void Run()=0
ThreadJob()
Base constructor.
Definition: Thread.cpp:58
unsigned int m_workerNum
Definition: Thread.h:123
unsigned int GetWorkerNum()
Definition: Thread.cpp:84
The interface class for the controller for worker threads and jobs.
Definition: Thread.h:163
virtual void SetNumWorkers(const unsigned int num)=0
Sets the number of active workers.
virtual unsigned int GetWorkerNum()=0
Returns the worker number of the executing thread.
virtual unsigned int GetNumWorkers()=0
Return the number of active workers.
virtual void SetNumWorkers()=0
Sets the number of active workers to the maximum.
virtual void QueueJobs(std::vector< ThreadJob * > &joblist)=0
Pass a list of tasklets to the master queue.
virtual const std::string & GetType() const =0
Returns a description of the type of threading.
int GetPartitionFromRankThr(int pRank, unsigned int pThr)
Definition: Thread.h:314
int GetThrFromPartition(int pPartition)
Definition: Thread.h:304
virtual ~ThreadManager()
Destructor.
Definition: Thread.cpp:106
virtual unsigned int GetMaxNumWorkers()=0
Gets the maximum available number of threads.
virtual void SetChunkSize(unsigned int chnk)=0
Controls how many jobs are sent to each worker at a time.
virtual bool InThread()=0
Indicates whether the code is in a worker thread or not.
int GetRankFromPartition(int pPartition)
Definition: Thread.h:309
virtual void Hold()=0
A calling threads holds until all active threads call this method.
virtual void QueueJob(ThreadJob *job)=0
Pass a single job to the master queue.
virtual bool IsInitialised()
ThreadManager implementation.
Definition: Thread.cpp:95
virtual void SetSchedType(SchedType s)=0
Sets the current scheduling algorithm.
virtual void Wait()=0
Waits until all queued jobs are finished.
~ThreadMaster()
Destructor.
Definition: Thread.cpp:123
void SetThreadingType(const std::string &p_type)
Sets what ThreadManagers will be created in CreateInstance.
Definition: Thread.cpp:147
ThreadManagerSharedPtr CreateInstance(const ThreadManagerName t, unsigned int nThr)
Creates an instance of a ThreadManager (which one is determined by a previous call to SetThreadingTyp...
Definition: Thread.cpp:183
ThreadManagerSharedPtr & GetInstance(const ThreadManagerName t)
Gets the ThreadManager associated with string s.
Definition: Thread.cpp:167
ThreadMaster()
Constructor.
Definition: Thread.cpp:114
std::vector< ThreadManagerSharedPtr > m_threadManagers
Definition: Thread.h:343
boost::shared_mutex m_mutex
Definition: Thread.h:344
std::string m_threadingType
Definition: Thread.h:345
A default ThreadManager.
Definition: Thread.h:380
virtual bool IsInitialised()
ThreadManager implementation.
Definition: Thread.cpp:317
virtual void SetChunkSize(unsigned int chnk)
Controls how many jobs are sent to each worker at a time.
Definition: Thread.cpp:281
virtual void Wait()
Waits until all queued jobs are finished.
Definition: Thread.cpp:273
ThreadStartupManager & operator=(const ThreadStartupManager &src)
ThreadDefaultManager copy constructor.
Definition: Thread.cpp:333
virtual unsigned int GetNumWorkers()
Return the number of active workers.
Definition: Thread.cpp:232
virtual unsigned int GetMaxNumWorkers()
Gets the maximum available number of threads.
Definition: Thread.cpp:265
ThreadStartupManager()
ThreadDefaultManager.
Definition: Thread.cpp:196
virtual void SetNumWorkers()
Sets the number of active workers to the maximum.
Definition: Thread.cpp:257
virtual bool InThread()
Indicates whether the code is in a worker thread or not.
Definition: Thread.cpp:301
ThreadStartupManager(const ThreadStartupManager &src)=default
virtual const std::string & GetType() const
Returns a description of the type of threading.
Definition: Thread.cpp:325
virtual void QueueJobs(std::vector< ThreadJob * > &joblist)
Pass a list of tasklets to the master queue.
Definition: Thread.cpp:212
virtual void SetSchedType(SchedType s)
Sets the current scheduling algorithm.
Definition: Thread.cpp:291
virtual void QueueJob(ThreadJob *job)
Pass a single job to the master queue.
Definition: Thread.cpp:222
virtual unsigned int GetWorkerNum()
Returns the worker number of the executing thread.
Definition: Thread.cpp:240
virtual void Hold()
A calling threads holds until all active threads call this method.
Definition: Thread.cpp:309
SchedType
Identifies the algorithm for scheduling.
Definition: Thread.h:66
LibUtilities::NekFactory< std::string, ThreadManager, unsigned int > ThreadManagerFactory
Definition: Thread.h:74
ThreadManagerFactory & GetThreadManagerFactory()
Definition: Thread.cpp:49
std::shared_ptr< ThreadManager > ThreadManagerSharedPtr
Definition: Thread.h:71
boost::shared_lock< boost::shared_mutex > ReadLock
Definition: Thread.h:321
ThreadMaster & GetThreadMaster()
Definition: Thread.cpp:132
boost::unique_lock< boost::shared_mutex > WriteLock
Definition: Thread.h:320
The above copyright notice and this permission notice shall be included.
Definition: CoupledSolver.h:1