QThreadPool 类

QThreadPool 类管理一批 QThread。 更多...

头：	#include <QThreadPool>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake:	QT += core
继承：	QObject

• 所有成员列表，包括继承成员
• QThreadPool is part of 线程类 .

注意： 此类的所有函数 thread-safe .

特性

activeThreadCount : const int expiryTimeout : int maxThreadCount : int

stackSize : uint (从 6.2 起) threadPriority : QThread::Priority

公共函数

	QThreadPool (QObject * parent = nullptr)
virtual	~QThreadPool ()
int	activeThreadCount () const
void	clear ()
(从 6.0 起) bool	contains (const QThread * thread ) const
int	expiryTimeout () const
int	maxThreadCount () const
void	releaseThread ()
void	reserveThread ()
void	setExpiryTimeout (int expiryTimeout )
void	setMaxThreadCount (int maxThreadCount )
void	setStackSize (uint stackSize )
void	setThreadPriority (QThread::Priority priority )
uint	stackSize () const
void	start (QRunnable * runnable , int priority = 0)
void	start (Callable && callableToRun , int priority = 0)
(since 6.3) void	startOnReservedThread (QRunnable * runnable )
(since 6.3) void	startOnReservedThread (Callable && callableToRun )
QThread::Priority	threadPriority () const
bool	tryStart (QRunnable * runnable )
bool	tryStart (Callable && callableToRun )
bool	tryTake (QRunnable * runnable )
bool	waitForDone (int msecs = -1)

静态公共成员

QThreadPool *

globalInstance ()

详细描述

QThreadPool manages and recycles individual QThread 对象以帮助缩减使用线程的程序创建线程的开销。每个 Qt 应用程序都有一全局 QThreadPool 对象，可以访问通过调用 globalInstance ().

要使用某一 QThreadPool 线程，子类 QRunnable 和实现 run() 虚函数。然后创建该类的对象并把它传递给 QThreadPool::start ().

class HelloWorldTask : public QRunnable
{
    void run() override
    {
        qDebug() << "Hello world from thread" << QThread::currentThread();
    }
};
HelloWorldTask *hello = new HelloWorldTask();
// QThreadPool takes ownership and deletes 'hello' automatically
QThreadPool::globalInstance()->start(hello);
					

QThreadPool 删除 QRunnable 默认情况下是自动的。使用 QRunnable::setAutoDelete () 以改变自动删除标志。

QThreadPool 支持执行相同 QRunnable 多次通过调用 tryStart (this) 从 QRunnable::run ()。若 autoDelete 被启用 QRunnable 会被删除当最后一个线程退出 run 函数时。调用 start () 多次采用同一 QRunnable 当启用 autoDelete 时会创建竞争条件且不推荐。

在一定时间内未使用线程将过期。默认过期超时为 30000 毫秒 (30 秒)。可以改变这使用 setExpiryTimeout ()。设置负值过期超时，将禁用过期机制。

调用 maxThreadCount () 以查询要使用的最大线程数。若需要，可以改变限制采用 setMaxThreadCount ()。默认 maxThreadCount () 是 QThread::idealThreadCount ()。 activeThreadCount () 函数返回目前在做工作的线程数。

The reserveThread () 函数预定线程以供外部使用。使用 releaseThread () when your are done with the thread, so that it may be reused. Essentially, these functions temporarily increase or reduce the active thread count and are useful when implementing time-consuming operations that are not visible to the QThreadPool.

Note that QThreadPool is a low-level class for managing threads, see the Qt Concurrent module for higher level alternatives.

另请参阅 QRunnable .

特性文档编制

[read-only] activeThreadCount : const int

This property holds the number of active threads in the thread pool.

注意： 它是可能的，此函数的返回值大于 maxThreadCount ()。见 reserveThread () 了解更多细节。

访问函数：

int	activeThreadCount () const

另请参阅 reserveThread () 和 releaseThread ().

expiryTimeout : int

This property holds the thread expiry timeout value in milliseconds.

线程未使用 expiryTimeout 毫秒被认为已过期且会退出。这种线程将根据需要重新启动。默认 expiryTimeout 为 30000 毫秒 (30 秒)。若 expiryTimeout 为负值，新近创建的线程不会过期，如：它们不会退出，直到线程池被销毁。

注意，设置 expiryTimeout 对已运行的线程没有作用。仅新近创建的线程会使用新的 expiryTimeout 。推荐设置 expiryTimeout 立即在创建线程池后，但先于调用 start ().

访问函数：

int	expiryTimeout () const
void	setExpiryTimeout (int expiryTimeout )

maxThreadCount : int

This property holds the maximum number of threads used by the thread pool. This property will default to the value of QThread::idealThreadCount () at the moment the QThreadPool 对象被创建。

注意： 线程池始终使用至少 1 线程，即使 maxThreadCount 限制为 0 (或负值)。

默认 maxThreadCount is QThread::idealThreadCount ().

访问函数：

int	maxThreadCount () const
void	setMaxThreadCount (int maxThreadCount )

stackSize : uint

This property holds the stack size for the thread pool worker threads.

The value of the property is only used when the thread pool creates new threads. Changing it has no effect for already created or running threads.

The default value is 0, which makes QThread use the operating system default stack size.

访问函数：

uint	stackSize () const
void	setStackSize (uint stackSize )

[since 6.2] threadPriority : QThread::Priority

This property holds the thread priority for new worker threads.

The value of the property is only used when the thread pool starts new threads. Changing it has no effect for already running threads.

默认值为 QThread::InheritPriority , which makes QThread use the same priority as the one the QThreadPool object lives in.

该特性在 Qt 6.2 引入。

访问函数：

QThread::Priority	threadPriority () const
void	setThreadPriority (QThread::Priority priority )

另请参阅 QThread::Priority .

成员函数文档编制

QThreadPool:: QThreadPool ( QObject * parent = nullptr)

构造线程池采用给定 parent .

[virtual noexcept] QThreadPool:: ~QThreadPool ()

销毁 QThreadPool 。此函数会阻塞，直到所有可运行已完成。

void QThreadPool:: clear ()

从队列移除尚未启动的可运行。可运行为 runnable->autoDelete () 返回 true 被删除。

另请参阅 start ().

[since 6.0] bool QThreadPool:: contains (const QThread * thread ) const

返回 true if thread is a thread managed by this thread pool.

该函数在 Qt 6.0 引入。

[static] QThreadPool *QThreadPool:: globalInstance ()

返回全局 QThreadPool 实例。

void QThreadPool:: releaseThread ()

释放先前预定的线程，预定是通过调用 reserveThread ().

注意： 若先前没有预定线程，调用此函数会临时递增 maxThreadCount ()。这很有用。当线程进入休眠等待更多工作时，允许其它线程继续。确保调用 reserveThread () 当等待完成时，以便线程池能够正确维护 activeThreadCount ().

另请参阅 reserveThread ().

void QThreadPool:: reserveThread ()

预定一线程，不管 activeThreadCount () 和 maxThreadCount ().

一旦线程完成，调用 releaseThread () 才允许它被重用。

注意： Even if reserving maxThreadCount () threads or more, the thread pool will still allow a minimum of one thread.

注意： This function will increase the reported number of active threads. This means that by using this function, it is possible for activeThreadCount () 返回值大于 maxThreadCount ().

另请参阅 releaseThread ().

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

预定线程并用它运行 runnable ，除非此线程将使当前线程数超过 maxThreadCount ()。在此情况下， runnable 取而代之是被添加到运行队列。 priority 自变量可以用于控制运行队列的执行次序。

注意，线程池拥有所有权对于 runnable if runnable->autoDelete () 返回 true ，和 runnable 将被线程池自动删除后于 runnable->run () returns. If runnable->autoDelete () 返回 false ，所有权对于 runnable 仍然属于调用者。注意，改变自动删除对 runnable 在调用此函数后将导致未定义行为。

template <typename Callable, QRunnable::if_callable<Callable> = true> void QThreadPool:: start ( 可调用 && callableToRun , int priority = 0)

这是重载函数。

预定线程并用它运行 callableToRun ，除非此线程将使当前线程数超过 maxThreadCount ()。在此情况下， callableToRun 取而代之是被添加到运行队列。 priority 自变量可以用于控制运行队列的执行次序。

注意： 此函数仅参与重载解析，若 可调用 is a function or function object which can be called with zero arguments.

注意： In Qt version prior to 6.6, this function took std::function<void()>, and therefore couldn't handle move-only callables.

[since 6.3] void QThreadPool:: startOnReservedThread ( QRunnable * runnable )

Releases a thread previously reserved with reserveThread () and uses it to run runnable .

注意，线程池拥有所有权对于 runnable if runnable->autoDelete () 返回 true ，和 runnable 将被线程池自动删除后于 runnable->run () returns. If runnable->autoDelete () 返回 false ，所有权对于 runnable 仍然属于调用者。注意，改变自动删除对 runnable 在调用此函数后将导致未定义行为。

注意： Calling this when no threads are reserved results in undefined behavior.

该函数在 Qt 6.3 引入。

另请参阅 reserveThread () 和 start ().

[since 6.3] template <typename Callable, QRunnable::if_callable<Callable> = true> void QThreadPool:: startOnReservedThread ( 可调用 && callableToRun )

这是重载函数。

Releases a thread previously reserved with reserveThread () and uses it to run callableToRun .

注意： 此函数仅参与重载解析，若 可调用 is a function or function object which can be called with zero arguments.

注意： In Qt version prior to 6.6, this function took std::function<void()>, and therefore couldn't handle move-only callables.

该函数在 Qt 6.3 引入。

bool QThreadPool:: tryStart ( QRunnable * runnable )

试图预定线程以运行 runnable .

若调用时没有可用线程，那么此函数什么都不做并返回 false 。否则， runnable 使用某一可用线程立即运行，且此函数返回 true .

Note that on success the thread pool takes ownership of the runnable if runnable->autoDelete () 返回 true ，和 runnable 将被线程池自动删除后于 runnable->run () returns. If runnable->autoDelete () 返回 false ，所有权对于 runnable 仍然属于调用者。注意，改变自动删除对 runnable 在调用此函数后将导致未定义行为。

template <typename Callable, QRunnable::if_callable<Callable> = true> bool QThreadPool:: tryStart ( 可调用 && callableToRun )

这是重载函数。

试图预定线程以运行 callableToRun .

若调用时没有可用线程，那么此函数什么都不做并返回 false 。否则， callableToRun 使用某一可用线程立即运行，且此函数返回 true .

注意： 此函数仅参与重载解析，若 可调用 is a function or function object which can be called with zero arguments.

注意： In Qt version prior to 6.6, this function took std::function<void()>, and therefore couldn't handle move-only callables.

bool QThreadPool:: tryTake ( QRunnable * runnable )

试图移除指定 runnable 从队列若它尚未启动。若可运行未启动，返回 true ，且所有权对于 runnable 会被转移给调用者 (甚至当 runnable->autoDelete() == true )。否则返回 false .

注意： 若 runnable->autoDelete() == true ，此函数可以移除出错的可运行。这称为 ABA 问题 ：原始 runnable 可能已执行且已被删除。内存被另一可运行重用，那么将移除，而不是打算移除。出于此原因，推荐仅对非自动删除的可运行调用此函数。

另请参阅 start () 和 QRunnable::autoDelete ().

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

等待直到 msecs 毫秒以便所有线程退出并移除所有线程从线程池。返回 true 若所有线程被移除；否则它返回 false 。若 msecs 为 -1 (默认)，忽略超时 (等待最后一个线程退出)。

内容

• 特性

• 公共函数

• 静态公共成员

• 详细描述