内容

• 特性
• 公共函数
• 静态公共成员
• 详细描述

QThreadPool 类

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

头：	#include <QThreadPool>
qmake:	QT += core
Since:	Qt 4.4
继承：	QObject

• 所有成员列表，包括继承成员
• 过时成员

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

特性

• activeThreadCount : const int
• expiryTimeout : int
• maxThreadCount : int
• stackSize : uint

• 1 特性继承自 QObject

公共函数

	QThreadPool (QObject * parent = nullptr)
virtual	~QThreadPool ()
int	activeThreadCount () const
void	clear ()
int	expiryTimeout () const
int	maxThreadCount () const
void	releaseThread ()
void	reserveThread ()
void	setExpiryTimeout (int expiryTimeout )
void	setMaxThreadCount (int maxThreadCount )
void	setStackSize (uint stackSize )
uint	stackSize () const
void	start (QRunnable * runnable , int priority = 0)
bool	tryStart (QRunnable * runnable )
bool	tryTake (QRunnable * runnable )
bool	waitForDone (int msecs = -1)

• 32 公共函数继承自 QObject

静态公共成员

QThreadPool *	globalInstance ()
const QMetaObject	staticMetaObject

• 10 静态公共成员继承自 QObject

额外继承成员

• 1 公共槽继承自 QObject
• 2 信号继承自 QObject
• 9 保护函数继承自 QObject

详细描述

The QThreadPool 类管理一批 QThread。

QThreadPool 管理和回收单个 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 () 当线程完成时，以便可以重用它。本质上，这些函数临时递增 (或缩减) 活动线程数且很有用当实现的耗时操作不可见对于 QThreadPool .

注意， QThreadPool 是用于管理线程的低级类，见 Qt Concurrent 模块，了解更高级替代。

另请参阅 QRunnable .

特性文档编制

activeThreadCount : const int

此特性表示线程池中的活动线程数。

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

访问函数：

int	activeThreadCount () const

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

expiryTimeout : int

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

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

访问函数：

int	expiryTimeout () const
void	setExpiryTimeout (int expiryTimeout )

maxThreadCount : int

此特性表示用于线程池的最大线程数。

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

默认 maxThreadCount is QThread::idealThreadCount ().

访问函数：

int	maxThreadCount () const
void	setMaxThreadCount (int maxThreadCount )

stackSize : uint

This property contains 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.

该特性在 Qt 5.10 引入。

访问函数：

uint	stackSize () const
void	setStackSize (uint stackSize )

成员函数文档编制

QThreadPool:: QThreadPool ( QObject * parent = nullptr)

构造线程池采用给定 parent .

[虚拟] QThreadPool:: ~QThreadPool ()

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

void QThreadPool:: clear ()

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

该函数在 Qt 5.2 引入。

另请参阅 start ().

[static] QThreadPool *QThreadPool:: globalInstance ()

返回全局 QThreadPool 实例。

void QThreadPool:: releaseThread ()

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

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

另请参阅 reserveThread ().

void QThreadPool:: reserveThread ()

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

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

注意： 此函数将始终递增活动线程数。这意味着使用此函数，它是可能的对于 activeThreadCount () 返回值大于 maxThreadCount ().

另请参阅 releaseThread ().

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

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

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

bool QThreadPool:: tryStart ( QRunnable * runnable )

试图预定线程以运行 runnable .

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

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

bool QThreadPool:: tryTake ( QRunnable * runnable )

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

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

该函数在 Qt 5.9 引入。

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

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

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