Loading...
Searching...
No Matches
juce::ThreadPool Class Reference

## 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

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

- juce_core/threads/juce_ThreadPool.h

## Classes

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

## Public Types

using | Options = ThreadPoolOptions

## Public Member Functions

| ThreadPool (const Options &options)
| Creates a thread pool based on the provided options.
| ThreadPool ()
| Creates a thread pool based using the default arguments provided by ThreadPoolOptions.
| ThreadPool (int numberOfThreads, size_t threadStackSizeBytes=Thread::osDefaultStackSize, Thread::Priority desiredThreadPriority=Thread::Priority::normal)
| Creates a thread pool.
| ~ThreadPool ()
| Destructor.
void | addJob (ThreadPoolJob *job, bool deleteJobWhenFinished)
| Adds a job to the queue.
void | addJob (std::function< ThreadPoolJob::JobStatus()> job)
| Adds a lambda function to be called as a job.
void | addJob (std::function< void()> job)
| Adds a lambda function to be called as a job.
bool | removeJob (ThreadPoolJob *job, bool interruptIfRunning, int timeOutMilliseconds)
| Tries to remove a job from the pool.
bool | removeAllJobs (bool interruptRunningJobs, int timeOutMilliseconds, JobSelector *selectedJobsToRemove=nullptr)
| Tries to remove all jobs from the pool.
int | getNumJobs () const noexcept
| Returns the number of jobs currently running or queued.
int | getNumThreads () const noexcept
| Returns the number of threads assigned to this thread pool.
ThreadPoolJob * | getJob (int index) const noexcept
| Returns one of the jobs in the queue.
bool | contains (const ThreadPoolJob *job) const noexcept
| Returns true if the given job is currently queued or running.
bool | isJobRunning (const ThreadPoolJob *job) const noexcept
| Returns true if the given job is currently being run by a thread.
bool | waitForJobToFinish (const ThreadPoolJob *job, int timeOutMilliseconds) const
| Waits until a job has finished running and has been removed from the pool.
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.
StringArray | getNamesOfAllJobs (bool onlyReturnActiveJobs) const
| Returns a list of the names of all the jobs currently running or queued.

## Member Typedef Documentation

## Options

using juce::ThreadPool::Options = ThreadPoolOptions

## Constructors and Destructors

## ThreadPool() [1/3]

juce::ThreadPool::ThreadPool | ( | const Options & | options | ) |

explicit

Creates a thread pool based on the provided options.

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

See also
  ThreadPool::ThreadPoolOptions

Referenced by ThreadPool(), and ThreadPoolJob.

## ThreadPool() [2/3]

juce::ThreadPool::ThreadPool | ( |  | ) |

inline

Creates a thread pool based using the default arguments provided by ThreadPoolOptions.

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

See also
  ThreadPoolOptions

References ThreadPool().

## ThreadPool() [3/3]

juce::ThreadPool::ThreadPool | ( | int | numberOfThreads,
|  | size_t | threadStackSizeBytes = Thread::osDefaultStackSize,
|  | Thread::Priority | desiredThreadPriority = Thread::Priority::normal )

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.
  threadStackSizeBytes | the size of the stack of each thread. If this value is zero then the default stack size of the OS will be used.
  desiredThreadPriority | the desired priority of each thread in the pool.

References juce::Thread::normal, and juce::Thread::osDefaultStackSize.

## ~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 Functions

## 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.

References ThreadPoolJob.

## 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.

## 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

References ThreadPoolJob.

## removeAllJobs()

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

Referenced by ThreadPoolJob.

## 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.

References getNumThreads().

Referenced by getNumThreads().

## 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.

References getJob(), and ThreadPoolJob.

Referenced by getJob().

## contains()

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

noexcept

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

See also
  isJobRunning()

References contains(), and ThreadPoolJob.

Referenced by contains().

## isJobRunning()

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

noexcept

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

References isJobRunning(), and ThreadPoolJob.

Referenced by isJobRunning().

## 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.

References ThreadPoolJob, and waitForJobToFinish().

Referenced by waitForJobToFinish().

## 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.

References moveJobToFront(), and ThreadPoolJob.

Referenced by moveJobToFront().

## 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.

References getNamesOfAllJobs(), and ThreadPoolJob.

Referenced by getNamesOfAllJobs().

### Purchase

Get JUCE

### Discover

What's New in JUCE Features

### Learn

Documentaion Tutorials Made with JUCE Resources

### Support

JUCE Forum Newsletter Archive

### About

Contact Us JUCE Legal JUCE Licensing FAQ

### Events

Audio Developer Conference
© Raw Material Software Limited