内容

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

QThreadPool 类

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

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

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

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

特性

• activeThreadCount : const int
• expiryTimeout : int
• maxThreadCount : int

• 1 特性继承自 QObject

公共函数

	QThreadPool (QObject * parent = Q_NULLPTR)
	~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	start (QRunnable * runnable , int priority = 0)
bool	tryStart (QRunnable * runnable )
bool	tryTake (QRunnable * runnable )
bool	waitForDone (int msecs = -1)

• 32 公共函数继承自 QObject

静态公共成员

QThreadPool *

globalInstance ()

• 11 静态公共成员继承自 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()
    {
        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 )

成员函数文档编制

QThreadPool:: QThreadPool ( QObject * parent = Q_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 (默认)，忽略超时 (等待最后一个线程退出)。