QThreadPool Class

The QThreadPool class manages a collection of threads. More…

List of all members, including inherited members

Public Functions

Static Public Members

Detailed Description

A thread pool runs QRunnable tasks on a limited number of reusable threads, which saves the cost of creating a thread for each task. Every program has a global pool, globalInstance(), and may create more.

QThreadPool::globalInstance()->start([] { compute(); });
QThreadPool::globalInstance()->waitForDone();

start() hands a task to an idle thread, starts a new thread if fewer than maxThreadCount() threads are busy, and otherwise queues the task; queued tasks run in order of priority, and in order of arrival among equal priorities. A thread that has had no work for expiryTimeout() exits. The destructor waits for all tasks, including queued ones. The destructor of QCoreApplication waits for the global pool.

See also QRunnable and QThread.

Differences from Qt

Member Function Documentation

[explicit] QThreadPool::QThreadPool(QObject *parent = nullptr)

Constructs a thread pool with the given parent. The maximum number of threads is QThread::idealThreadCount() and an idle thread expires after 30 seconds.

[override] QThreadPool::~QThreadPool()

Destroys the pool. It waits for all queued and running tasks to finish, then ends and joins its threads.

int QThreadPool::activeThreadCount() const

Returns the number of threads that run a task, plus the reserved threads. It can be larger than maxThreadCount() because of reserveThread().

See also maxThreadCount() and reserveThread().

void QThreadPool::clear()

Removes all queued runnables that have not started, and deletes those with autoDelete() set to true. Running tasks are not affected.

See also tryTake().

bool QThreadPool::contains(const QThread *thread) const

Returns true if thread is one of the threads of this pool, so a task can tell whether it runs in the pool.

This function was introduced in 6.0.

int QThreadPool::expiryTimeout() const

Returns the time in milliseconds that an idle thread waits for work before it exits. The default is 30000. A negative value means that threads never expire.

See also setExpiryTimeout().

[static] QThreadPool * QThreadPool::globalInstance()

Returns the global thread pool, which is created on first use. It is destroyed at exit, after QCoreApplication has waited for its tasks.

int QThreadPool::maxThreadCount() const

Returns the maximum number of threads the pool uses. The default is QThread::idealThreadCount().

See also setMaxThreadCount() and activeThreadCount().

void QThreadPool::releaseThread()

Releases a thread that reserveThread() reserved, which may start a queued task.

See also reserveThread().

void QThreadPool::reserveThread()

Reserves a thread without running anything on it: activeThreadCount() increases by one even if it is already at maxThreadCount(). Use it when the calling thread is going to block for a long time on something the pool does. Call releaseThread() when done.

See also releaseThread() and startOnReservedThread().

void QThreadPool::setExpiryTimeout(int expiryTimeout)

Sets the time an idle thread waits for work before it exits to expiryTimeout milliseconds. A negative value keeps threads alive until the pool is destroyed or waitForDone() is called. The new value applies the next time a thread becomes idle.

See also expiryTimeout().

void QThreadPool::setMaxThreadCount(int maxThreadCount)

Sets the maximum number of threads the pool uses to maxThreadCount. The pool always uses at least one thread, even if the limit is 0 or negative. Raising the limit starts queued tasks; lowering it does not stop running ones.

See also maxThreadCount() and reserveThread().

void QThreadPool::setStackSize(uint stackSize)

Sets the stack size of threads that the pool starts from now on to stackSize bytes. 0 selects the system default.

See also QThread::setStackSize().

void QThreadPool::setThreadPriority(QThread::Priority priority)

Sets the priority of the pool's threads, current and future, to priority. InheritPriority, the default, gives threads the priority of the thread that starts them.

See also threadPriority() and QThread::setPriority().

uint QThreadPool::stackSize() const

Returns the stack size used for new threads, or 0 for the system default.

See also setStackSize().

void QThreadPool::start(QRunnable *runnable, int priority = 0)

Runs runnable in a pool thread, or queues it if all threads are busy. Queued runnables run in order of priority, higher first, and in the order they were added if the priorities are equal. The pool deletes the runnable after it ran if autoDelete() is true.

See also tryStart() and QRunnable.

void QThreadPool::start(std::function<void()> functionToRun, int priority = 0)

This is an overloaded function.

Runs functionToRun in a pool thread, or queues it, with the given priority.

template <typename Callable, QtPrivate::IfRunnableCallable<Callable> = true>void QThreadPool::start(Callable &&functionToRun, int priority = 0)

This is an overloaded function.

Runs functionToRun, which may be a move-only callable, in a pool thread, or queues it, with the given priority.

This function was introduced in 6.0.

void QThreadPool::startOnReservedThread(QRunnable *runnable)

Runs runnable on a thread that was reserved with reserveThread(), and releases that reservation, so activeThreadCount() does not change. If runnable is nullptr, the thread is simply released.

This function was introduced in 6.3.

See also reserveThread() and releaseThread().

void QThreadPool::startOnReservedThread(std::function<void()> functionToRun)

This is an overloaded function.

Runs functionToRun on a reserved thread.

This function was introduced in 6.3.

template <typename Callable, QtPrivate::IfRunnableCallable<Callable> = true>void QThreadPool::startOnReservedThread(Callable &&functionToRun)

This is an overloaded function.

Runs functionToRun, which may be a move-only callable, on a reserved thread.

This function was introduced in 6.3.

QThread::Priority QThreadPool::threadPriority() const

Returns the priority of the pool's threads.

See also setThreadPriority().

bool QThreadPool::tryStart(QRunnable *runnable)

Reserves a thread to run runnable and returns true, or returns false if all threads are in use. The runnable is not queued. The pool takes ownership of the runnable if it has autoDelete() set.

See also start().

bool QThreadPool::tryStart(std::function<void()> functionToRun)

This is an overloaded function.

Runs functionToRun in a pool thread if one is available and returns true; returns false otherwise.

template <typename Callable, QtPrivate::IfRunnableCallable<Callable> = true>bool QThreadPool::tryStart(Callable &&functionToRun)

This is an overloaded function.

Runs functionToRun, which may be a move-only callable, in a pool thread if one is available and returns true; returns false otherwise, and the callable is destroyed.

This function was introduced in 6.0.

bool QThreadPool::tryTake(QRunnable *runnable)

Removes runnable from the queue if it has not started and returns true. Returns false if it is not queued, for instance because it is running. The pool does not delete the runnable, whatever autoDelete() says; the caller owns it again.

See also clear().

bool QThreadPool::waitForDone(int msecs = -1)

Waits up to msecs milliseconds for all queued and running tasks to finish and the pool's threads to exit; a negative value waits as long as it takes. Returns true if the pool is idle, and false if the time ran out. Threads that exit are replaced when new tasks arrive.

See also start().

bool QThreadPool::waitForDone(QDeadlineTimer deadline)

This is an overloaded function.

Waits until deadline has passed.