juce/source/src/threads/juce_ThreadPool.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_THREADPOOL_JUCEHEADER__
  27 #define __JUCE_THREADPOOL_JUCEHEADER__
  28
  29 #include "juce_Thread.h"
  30 #include "../text/juce_StringArray.h"
  31 #include "../containers/juce_Array.h"
  32 #include "../containers/juce_OwnedArray.h"
  33 class ThreadPool;
  34 class ThreadPoolThread;
  35
  36
  37 //==============================================================================
  38 /**
  39     A task that is executed by a ThreadPool object.
  40
  41     A ThreadPool keeps a list of ThreadPoolJob objects which are executed by
  42     its threads.
  43
  44     The runJob() method needs to be implemented to do the task, and if the code that
  45     does the work takes a significant time to run, it must keep checking the shouldExit()
  46     method to see if something is trying to interrupt the job. If shouldExit() returns
  47     true, the runJob() method must return immediately.
  48
  49     @see ThreadPool, Thread
  50 */
  51 class JUCE_API  ThreadPoolJob
  52 {
  53 public:
  54     //==============================================================================
  55     /** Creates a thread pool job object.
  56
  57         After creating your job, add it to a thread pool with ThreadPool::addJob().
  58     */
  59     explicit ThreadPoolJob (const String& name);
  60
  61     /** Destructor. */
  62     virtual ~ThreadPoolJob();
  63
  64     //==============================================================================
  65     /** Returns the name of this job.
  66         @see setJobName
  67     */
  68     String getJobName() const;
  69
  70     /** Changes the job's name.
  71         @see getJobName
  72     */
  73     void setJobName (const String& newName);
  74
  75     //==============================================================================
  76     /** These are the values that can be returned by the runJob() method.
  77     */
  78     enum JobStatus
  79     {
  80         jobHasFinished = 0,     /**< indicates that the job has finished and can be
  81                                      removed from the pool. */
  82
  83         jobHasFinishedAndShouldBeDeleted,  /**< indicates that the job has finished and that it
  84                                                 should be automatically deleted by the pool. */
  85
  86         jobNeedsRunningAgain    /**< indicates that the job would like to be called
  87                                      again when a thread is free. */
  88     };
  89
  90     /** Peforms the actual work that this job needs to do.
  91
  92         Your subclass must implement this method, in which is does its work.
  93
  94         If the code in this method takes a significant time to run, it must repeatedly check
  95         the shouldExit() method to see if something is trying to interrupt the job.
  96         If shouldExit() ever returns true, the runJob() method must return immediately.
  97
  98         If this method returns jobHasFinished, then the job will be removed from the pool
  99         immediately. If it returns jobNeedsRunningAgain, then the job will be left in the
 100         pool and will get a chance to run again as soon as a thread is free.
 101
 102         @see shouldExit()
 103     */
 104     virtual JobStatus runJob() = 0;
 105
 106
 107     //==============================================================================
 108     /** Returns true if this job is currently running its runJob() method. */
 109     bool isRunning() const                  { return isActive; }
 110
 111     /** Returns true if something is trying to interrupt this job and make it stop.
 112
 113         Your runJob() method must call this whenever it gets a chance, and if it ever
 114         returns true, the runJob() method must return immediately.
 115
 116         @see signalJobShouldExit()
 117     */
 118     bool shouldExit() const                 { return shouldStop; }
 119
 120     /** Calling this will cause the shouldExit() method to return true, and the job
 121         should (if it's been implemented correctly) stop as soon as possible.
 122
 123         @see shouldExit()
 124     */
 125     void signalJobShouldExit();
 126
 127     //==============================================================================
 128 private:
 129     friend class ThreadPool;
 130     friend class ThreadPoolThread;
 131     String jobName;
 132     ThreadPool* pool;
 133     bool shouldStop, isActive, shouldBeDeleted;
 134
 135     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ThreadPoolJob);
 136 };
 137
 138
 139 //==============================================================================
 140 /**
 141     A set of threads that will run a list of jobs.
 142
 143     When a ThreadPoolJob object is added to the ThreadPool's list, its run() method
 144     will be called by the next pooled thread that becomes free.
 145
 146     @see ThreadPoolJob, Thread
 147 */
 148 class JUCE_API  ThreadPool
 149 {
 150 public:
 151     //==============================================================================
 152     /** Creates a thread pool.
 153
 154         Once you've created a pool, you can give it some things to do with the addJob()
 155         method.
 156
 157         @param numberOfThreads              the maximum number of actual threads to run.
 158         @param startThreadsOnlyWhenNeeded   if this is true, then no threads will be started
 159                                             until there are some jobs to run. If false, then
 160                                             all the threads will be fired-up immediately so that
 161                                             they're ready for action
 162         @param stopThreadsWhenNotUsedTimeoutMs  if this timeout is > 0, then if any threads have been
 163                                             inactive for this length of time, they will automatically
 164                                             be stopped until more jobs come along and they're needed
 165     */
 166     ThreadPool (int numberOfThreads,
 167                 bool startThreadsOnlyWhenNeeded = true,
 168                 int stopThreadsWhenNotUsedTimeoutMs = 5000);
 169
 170     /** Destructor.
 171
 172         This will attempt to remove all the jobs before deleting, but if you want to
 173         specify a timeout, you should call removeAllJobs() explicitly before deleting
 174         the pool.
 175     */
 176     ~ThreadPool();
 177
 178     //==============================================================================
 179     /** A callback class used when you need to select which ThreadPoolJob objects are suitable
 180         for some kind of operation.
 181         @see ThreadPool::removeAllJobs
 182     */
 183     class JUCE_API  JobSelector
 184     {
 185     public:
 186         virtual ~JobSelector() {}
 187
 188         /** Should return true if the specified thread matches your criteria for whatever
 189             operation that this object is being used for.
 190
 191             Any implementation of this method must be extremely fast and thread-safe!
 192         */
 193         virtual bool isJobSuitable (ThreadPoolJob* job) = 0;
 194     };
 195
 196     //==============================================================================
 197     /** Adds a job to the queue.
 198
 199         Once a job has been added, then the next time a thread is free, it will run
 200         the job's ThreadPoolJob::runJob() method. Depending on the return value of the
 201         runJob() method, the pool will either remove the job from the pool or add it to
 202         the back of the queue to be run again.
 203     */
 204     void addJob (ThreadPoolJob* job);
 205
 206     /** Tries to remove a job from the pool.
 207
 208         If the job isn't yet running, this will simply remove it. If it is running, it
 209         will wait for it to finish.
 210
 211         If the timeout period expires before the job finishes running, then the job will be
 212         left in the pool and this will return false. It returns true if the job is sucessfully
 213         stopped and removed.
 214
 215         @param job                  the job to remove
 216         @param interruptIfRunning   if true, then if the job is currently busy, its
 217                                     ThreadPoolJob::signalJobShouldExit() method will be called to try
 218                                     to interrupt it. If false, then if the job will be allowed to run
 219                                     until it stops normally (or the timeout expires)
 220         @param timeOutMilliseconds  the length of time this method should wait for the job to finish
 221                                     before giving up and returning false
 222     */
 223     bool removeJob (ThreadPoolJob* job,
 224                     bool interruptIfRunning,
 225                     int timeOutMilliseconds);
 226
 227     /** Tries to remove all jobs from the pool.
 228
 229         @param interruptRunningJobs if true, then all running jobs will have their ThreadPoolJob::signalJobShouldExit()
 230                                     methods called to try to interrupt them
 231         @param timeOutMilliseconds  the length of time this method should wait for all the jobs to finish
 232                                     before giving up and returning false
 233         @param deleteInactiveJobs   if true, any jobs that aren't currently running will be deleted. If false,
 234                                     they will simply be removed from the pool. Jobs that are already running when
 235                                     this method is called can choose whether they should be deleted by
 236                                     returning jobHasFinishedAndShouldBeDeleted from their runJob() method.
 237         @param selectedJobsToRemove if this is non-zero, the JobSelector object is asked to decide which
 238                                     jobs should be removed. If it is zero, all jobs are removed
 239         @returns    true if all jobs are successfully stopped and removed; false if the timeout period
 240                     expires while waiting for one or more jobs to stop
 241     */
 242     bool removeAllJobs (bool interruptRunningJobs,
 243                         int timeOutMilliseconds,
 244                         bool deleteInactiveJobs = false,
 245                         JobSelector* selectedJobsToRemove = 0);
 246
 247     /** Returns the number of jobs currently running or queued.
 248     */
 249     int getNumJobs() const;
 250
 251     /** Returns one of the jobs in the queue.
 252
 253         Note that this can be a very volatile list as jobs might be continuously getting shifted
 254         around in the list, and this method may return 0 if the index is currently out-of-range.
 255     */
 256     ThreadPoolJob* getJob (int index) const;
 257
 258     /** Returns true if the given job is currently queued or running.
 259
 260         @see isJobRunning()
 261     */
 262     bool contains (const ThreadPoolJob* job) const;
 263
 264     /** Returns true if the given job is currently being run by a thread.
 265     */
 266     bool isJobRunning (const ThreadPoolJob* job) const;
 267
 268     /** Waits until a job has finished running and has been removed from the pool.
 269
 270         This will wait until the job is no longer in the pool - i.e. until its
 271         runJob() method returns ThreadPoolJob::jobHasFinished.
 272
 273         If the timeout period expires before the job finishes, this will return false;
 274         it returns true if the job has finished successfully.
 275     */
 276     bool waitForJobToFinish (const ThreadPoolJob* job,
 277                              int timeOutMilliseconds) const;
 278
 279     /** Returns a list of the names of all the jobs currently running or queued.
 280
 281         If onlyReturnActiveJobs is true, only the ones currently running are returned.
 282     */
 283     StringArray getNamesOfAllJobs (bool onlyReturnActiveJobs) const;
 284
 285     /** Changes the priority of all the threads.
 286
 287         This will call Thread::setPriority() for each thread in the pool.
 288         May return false if for some reason the priority can't be changed.
 289     */
 290     bool setThreadPriorities (int newPriority);
 291
 292
 293 private:
 294     //==============================================================================
 295     const int threadStopTimeout;
 296     int priority;
 297     class ThreadPoolThread;
 298     friend class OwnedArray <ThreadPoolThread>;
 299     OwnedArray <ThreadPoolThread> threads;
 300     Array <ThreadPoolJob*> jobs;
 301
 302     CriticalSection lock;
 303     uint32 lastJobEndTime;
 304     WaitableEvent jobFinishedSignal;
 305
 306     friend class ThreadPoolThread;
 307     bool runNextJob();
 308
 309     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ThreadPool);
 310 };
 311
 312
 313 #endif   // __JUCE_THREADPOOL_JUCEHEADER__