iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
ThreadPool.H
Go to the documentation of this file.
1 /*! @file
2  @author Randolph Voorhies
3  @copyright GNU Public License (GPL v3)
4  @section License
5  @verbatim
6  // ////////////////////////////////////////////////////////////////////////
7  // The iLab Neuromorphic Robotics Toolkit (NRT) //
8  // Copyright 2010-2012 by the University of Southern California (USC) //
9  // and the iLab at USC. //
10  // //
11  // iLab - University of Southern California //
12  // Hedco Neurociences Building, Room HNB-10 //
13  // Los Angeles, Ca 90089-2520 - USA //
14  // //
15  // See http://ilab.usc.edu for information about this project. //
16  // ////////////////////////////////////////////////////////////////////////
17  // This file is part of The iLab Neuromorphic Robotics Toolkit. //
18  // //
19  // The iLab Neuromorphic Robotics Toolkit is free software: you can //
20  // redistribute it and/or modify it under the terms of the GNU General //
21  // Public License as published by the Free Software Foundation, either //
22  // version 3 of the License, or (at your option) any later version. //
23  // //
24  // The iLab Neuromorphic Robotics Toolkit is distributed in the hope //
25  // that it will be useful, but WITHOUT ANY WARRANTY; without even the //
26  // implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR //
27  // PURPOSE. See the GNU General Public License for more details. //
28  // //
29  // You should have received a copy of the GNU General Public License //
30  // along with The iLab Neuromorphic Robotics Toolkit. If not, see //
31  // <http://www.gnu.org/licenses/>. //
32  // ////////////////////////////////////////////////////////////////////////
33  @endverbatim */
34 
35 
36 #ifndef INCLUDE_NRT_CORE_DESIGN_THREADPOOL_H
37 #define INCLUDE_NRT_CORE_DESIGN_THREADPOOL_H
38 
41 #include <boost/thread.hpp> // for shared_mutex, shared_lock and friends
42 #include <future>
43 
44 namespace nrt
45 {
46  //! The ThreadPool class is used to run a potentially large set of jobs on a fixed number of threads
47  /*! \ingroup design */
48  class ThreadPool
49  {
50  public:
51  //! Start a threadpool with the given number of threads
52  ThreadPool(size_t const numThreads = 4);
53 
54  //! Detach() all running threads
55  ~ThreadPool();
56 
57  //! Put a new job onto the work queue and get a future for its completion
58  /*! Use this method to push a single job onto the work queue. The returned future will be linked to the return
59  value of the function that you push, such that a call to the returned future's get() method will block until
60  your function has finished executing. The future's get() method will then return whatever value your method
61  returned.
62 
63  \param job The function to be pushed onto the work queue
64 
65  \tparam RETURN_TYPE The return type of the function being pushed onto the work queue. */
66  template <class RETURN_TYPE>
67  std::future<RETURN_TYPE> pushJob(std::function<RETURN_TYPE()> job);
68 
69  //! Put a set of jobs onto the work queue and get a future for their completion
70  /*! Use this method to push a set of jobs onto the queue simultaneously. The return future will block on a call
71  to wait() until all of the functions in the vector have completed. If you need to actually get the return
72  values of the functions you're pushing, then you must use the singular pushJob() method instead.
73 
74  \param jobs A set of jobs to be executed by the thread pool. */
75  std::future<void> pushJobs(std::vector<std::function<void()> > jobs);
76 
77  //! Wait for all jobs to finish and resize the thread pool to zero
78  /*! Must call resize() to reset the thread pool if doing a restart */
79  void joinAll();
80 
81  //! Resize the number of available workers
82  void resize(size_t const numThreads);
83 
84  //! Get the number of threads in the pool
85  size_t numWorkers();
86 
87  //! Get the number of jobs left in the queue
88  size_t numJobs();
89 
90  //! Returns true if all workers in the pool are currently in use
91  bool busy();
92 
93  private:
94  struct JobTicket;
95 
96  boost::shared_mutex itsMtx;
97 
98  nrt::SynchroQueue<std::pair<std::function<void()>, std::shared_ptr<JobTicket>>> itsWorkQueue;
99 
100  std::vector<std::thread> itsThreadPool;
101 
102  std::map<size_t, std::shared_ptr<bool>> itsRunningMap;
103 
104  void workerThread(std::shared_ptr<bool> running);
105  };
106 
107  //! Specialize for void jobs
108  /*! \relates ThreadPool */
109  template<> std::future<void> nrt::ThreadPool::pushJob(std::function<void()> job);
110 
111 } // namespace nrt
112 
114 
115 #endif // INCLUDE_NRT_CORE_DESIGN_THREADPOOL_H
116