juce::ThreadPool Class Reference

A set of threads that will run a list of jobs. More...

#include <juce_ThreadPool.h>

Collaboration diagram for juce::ThreadPool:

Classes
class	JobSelector
	A callback class used when you need to select which ThreadPoolJob objects are suitable for some kind of operation. More...

Public Member Functions
	ThreadPool (int numberOfThreads, size_t threadStackSize=0)
	Creates a thread pool. More...
	ThreadPool ()
	Creates a thread pool with one thread per CPU core. More...
	~ThreadPool ()
	Destructor. More...
void	addJob (ThreadPoolJob *job, bool deleteJobWhenFinished)
	Adds a job to the queue. More...
void	addJob (std::function< ThreadPoolJob::JobStatus()> job)
	Adds a lambda function to be called as a job. More...
void	addJob (std::function< void()> job)
	Adds a lambda function to be called as a job. More...
bool	contains (const ThreadPoolJob *job) const noexcept
	Returns true if the given job is currently queued or running. More...
ThreadPoolJob *	getJob (int index) const noexcept
	Returns one of the jobs in the queue. More...
StringArray	getNamesOfAllJobs (bool onlyReturnActiveJobs) const
	Returns a list of the names of all the jobs currently running or queued. More...
int	getNumJobs () const noexcept
	Returns the number of jobs currently running or queued. More...
int	getNumThreads () const noexcept
	Returns the number of threads assigned to this thread pool. More...
bool	isJobRunning (const ThreadPoolJob *job) const noexcept
	Returns true if the given job is currently being run by a thread. More...
void	moveJobToFront (const ThreadPoolJob *jobToMove) noexcept
	If the given job is in the queue, this will move it to the front so that it is the next one to be executed. More...
bool	removeAllJobs (bool interruptRunningJobs, int timeOutMilliseconds, JobSelector *selectedJobsToRemove=nullptr)
	Tries to remove all jobs from the pool. More...
bool	removeJob (ThreadPoolJob *job, bool interruptIfRunning, int timeOutMilliseconds)
	Tries to remove a job from the pool. More...
bool	setThreadPriorities (int newPriority)
	Changes the priority of all the threads. More...
bool	waitForJobToFinish (const ThreadPoolJob *job, int timeOutMilliseconds) const
	Waits until a job has finished running and has been removed from the pool. More...

Private Member Functions
void	addToDeleteList (OwnedArray< ThreadPoolJob > &, ThreadPoolJob *) const
void	createThreads (int numThreads, size_t threadStackSize=0)
ThreadPoolJob *	pickNextJobToRun ()
void	removeAllJobs (bool, int, bool)
bool	runNextJob (ThreadPoolThread &)
void	stopThreads ()

Private Attributes
WaitableEvent	jobFinishedSignal
Array< ThreadPoolJob * >	jobs
CriticalSection	lock
OwnedArray< ThreadPoolThread >	threads

Friends
class	ThreadPoolJob

Detailed Description

A set of threads that will run a list of jobs.

When a ThreadPoolJob object is added to the ThreadPool's list, its runJob() method will be called by the next pooled thread that becomes free.

See also

ThreadPoolJob, Thread

{Core}

Constructor & Destructor Documentation

ThreadPool() [1/2]

juce::ThreadPool::ThreadPool	(	int	numberOfThreads,
		size_t	threadStackSize = 0
	)

Creates a thread pool.

Once you've created a pool, you can give it some jobs by calling addJob().

Parameters

numberOfThreads	the number of threads to run. These will be started immediately, and will run until the pool is deleted.
threadStackSize	the size of the stack of each thread. If this value is zero then the default stack size of the OS will be used.

ThreadPool() [2/2]

juce::ThreadPool::ThreadPool

(

)

Creates a thread pool with one thread per CPU core.

Once you've created a pool, you can give it some jobs by calling addJob(). If you want to specify the number of threads, use the other constructor; this one creates a pool which has one thread for each CPU core.

See also

SystemStats::getNumCpus()

~ThreadPool()

juce::ThreadPool::~ThreadPool

(

)

Destructor.

This will attempt to remove all the jobs before deleting, but if you want to specify a timeout, you should call removeAllJobs() explicitly before deleting the pool.

Member Function Documentation

addJob() [1/3]

void juce::ThreadPool::addJob	(	ThreadPoolJob *	job,
		bool	deleteJobWhenFinished
	)

Adds a job to the queue.

Once a job has been added, then the next time a thread is free, it will run the job's ThreadPoolJob::runJob() method. Depending on the return value of the runJob() method, the pool will either remove the job from the pool or add it to the back of the queue to be run again.

If deleteJobWhenFinished is true, then the job object will be owned and deleted by the pool when not needed - if you do this, make sure that your object's destructor is thread-safe.

If deleteJobWhenFinished is false, the pointer will be used but not deleted, and the caller is responsible for making sure the object is not deleted before it has been removed from the pool.

addJob() [2/3]

void juce::ThreadPool::addJob

(

std::function< ThreadPoolJob::JobStatus()>

job

)

Adds a lambda function to be called as a job.

This will create an internal ThreadPoolJob object to encapsulate and call the lambda.

addJob() [3/3]

void juce::ThreadPool::addJob

(

std::function< void()>

job

)

Adds a lambda function to be called as a job.

This will create an internal ThreadPoolJob object to encapsulate and call the lambda.

addToDeleteList()

void juce::ThreadPool::addToDeleteList ( OwnedArray< ThreadPoolJob > &  , ThreadPoolJob *    ) const

private

contains()

bool juce::ThreadPool::contains ( const ThreadPoolJob *  job ) const

noexcept

Returns true if the given job is currently queued or running.

See also

isJobRunning()

createThreads()

void juce::ThreadPool::createThreads ( int  numThreads, size_t  threadStackSize = 0  )

private

getJob()

ThreadPoolJob* juce::ThreadPool::getJob ( int  index ) const

noexcept

Returns one of the jobs in the queue.

Note that this can be a very volatile list as jobs might be continuously getting shifted around in the list, and this method may return nullptr if the index is currently out-of-range.

getNamesOfAllJobs()

StringArray juce::ThreadPool::getNamesOfAllJobs

(

bool

onlyReturnActiveJobs

)

const

Returns a list of the names of all the jobs currently running or queued.

If onlyReturnActiveJobs is true, only the ones currently running are returned.

getNumJobs()

int juce::ThreadPool::getNumJobs ( ) const

noexcept

Returns the number of jobs currently running or queued.

getNumThreads()

int juce::ThreadPool::getNumThreads ( ) const

noexcept

Returns the number of threads assigned to this thread pool.

isJobRunning()

bool juce::ThreadPool::isJobRunning ( const ThreadPoolJob *  job ) const

noexcept

Returns true if the given job is currently being run by a thread.

moveJobToFront()

void juce::ThreadPool::moveJobToFront ( const ThreadPoolJob *  jobToMove )

noexcept

If the given job is in the queue, this will move it to the front so that it is the next one to be executed.

pickNextJobToRun()

ThreadPoolJob* juce::ThreadPool::pickNextJobToRun ( )

private

removeAllJobs() [1/2]

bool juce::ThreadPool::removeAllJobs	(	bool	interruptRunningJobs,
		int	timeOutMilliseconds,
		JobSelector *	selectedJobsToRemove = nullptr
	)

Tries to remove all jobs from the pool.

Parameters

interruptRunningJobs	if true, then all running jobs will have their ThreadPoolJob::signalJobShouldExit() methods called to try to interrupt them
timeOutMilliseconds	the length of time this method should wait for all the jobs to finish before giving up and returning false
selectedJobsToRemove	if this is not a nullptr, the JobSelector object is asked to decide which jobs should be removed. If it is a nullptr, all jobs are removed

Returns

true if all jobs are successfully stopped and removed; false if the timeout period expires while waiting for one or more jobs to stop

removeAllJobs() [2/2]

void juce::ThreadPool::removeAllJobs ( bool  , int  , bool    )

private

removeJob()

bool juce::ThreadPool::removeJob	(	ThreadPoolJob *	job,
		bool	interruptIfRunning,
		int	timeOutMilliseconds
	)

Tries to remove a job from the pool.

If the job isn't yet running, this will simply remove it. If it is running, it will wait for it to finish.

If the timeout period expires before the job finishes running, then the job will be left in the pool and this will return false. It returns true if the job is successfully stopped and removed.

Parameters

job	the job to remove
interruptIfRunning	if true, then if the job is currently busy, its ThreadPoolJob::signalJobShouldExit() method will be called to try to interrupt it. If false, then if the job will be allowed to run until it stops normally (or the timeout expires)
timeOutMilliseconds	the length of time this method should wait for the job to finish before giving up and returning false

runNextJob()

bool juce::ThreadPool::runNextJob ( ThreadPoolThread &  )

private

setThreadPriorities()

bool juce::ThreadPool::setThreadPriorities

(

int

newPriority

)

Changes the priority of all the threads.

This will call Thread::setPriority() for each thread in the pool. May return false if for some reason the priority can't be changed.

stopThreads()

void juce::ThreadPool::stopThreads ( )

private

waitForJobToFinish()

bool juce::ThreadPool::waitForJobToFinish	(	const ThreadPoolJob *	job,
		int	timeOutMilliseconds
	)		const

Waits until a job has finished running and has been removed from the pool.

This will wait until the job is no longer in the pool - i.e. until its runJob() method returns ThreadPoolJob::jobHasFinished.

If the timeout period expires before the job finishes, this will return false; it returns true if the job has finished successfully.

Friends And Related Function Documentation

ThreadPoolJob

friend class ThreadPoolJob

friend

Member Data Documentation

jobFinishedSignal

WaitableEvent juce::ThreadPool::jobFinishedSignal

private

jobs

Array<ThreadPoolJob*> juce::ThreadPool::jobs

private

lock

CriticalSection juce::ThreadPool::lock

private

threads

OwnedArray<ThreadPoolThread> juce::ThreadPool::threads

private

---

The documentation for this class was generated from the following file:

• juce_ThreadPool.h