class QThreadPool#

QThreadPool 类管理一组 QThread。 更多…

Inheritance diagram of PySide6.QtCore.QThreadPool

概述#

属性#

  • activeThreadCount - 线程池中的活动线程数

  • expiryTimeout - 线程过期超时值，单位为毫秒

  • maxThreadCount - 线程池使用的最大线程数。此属性将在创建 QThreadPool 对象时默认为 QThread::idealThreadCount() 的值

  • stackSize - 线程池工作线程的堆栈大小

  • threadPriority - 新工作线程的线程优先级

方法#

静态函数#

注释

此文档可能包含自动从C++翻译到Python的片段。我们始终欢迎对片段翻译的贡献。如果您发现翻译有问题，也可以通过在https:/bugreports.qt.io/projects/PYSIDE上创建票据来告诉我们

详细描述#

警告

本节包含自动从C++翻译到Python的代码片段，可能包含错误。

《QThreadPool》管理并回收单个《QThread》对象，以帮助降低在需要线程的程序中创建线程的成本。每个Qt应用程序都有一个全局的《QThreadPool》对象，可以通过调用《globalInstance》（全局实例）方法来获取。

要使用《QThreadPool》中的线程，需要从《QRunnable》派生一个子类，并实现`run()`虚拟函数。然后创建该类的对象，并将其传递给`start()`方法。

class HelloWorldTask(QRunnable):

    def run():

        print("Hello world from thread", QThread.currentThread())


hello = HelloWorldTask()
# QThreadPool takes ownership and deletes 'hello' automatically
QThreadPool.globalInstance().start(hello)

默认情况下，《QThreadPool》会自动删除《QRunnable》。如果要更改自动删除标志，请使用`setAutoDelete()`方法。

《QThreadPool》支持通过在`run()`方法内部调用`tryStart`（重载的该实例方法）多次执行相同的《QRunnable》对象。如果启用了自动删除，当最后一个线程退出`run`函数时，《QRunnable》将被删除。当启用了自动删除时，多次使用相同的《QRunnable》调用`start()`将导致竞争条件，因此不推荐这么做。

一段时间内未被使用的线程将过期。默认的到期超时时间是30000毫秒（30秒）。可以使用`setExpiryTimeout()`方法来改变这个超时时间。设置负的超时时间将禁用过期机制。

调用 maxThreadCount() 查询要使用的最大线程数。如果需要，可以使用 setMaxThreadCount() 改变限制。默认的 maxThreadCount() 是 idealThreadCount() 。函数 activeThreadCount() 返回当前正在执行工作的线程数量。

reserveThread() 函数为外部使用保留一个线程。当您完成对线程的使用时，使用 releaseThread() ，以便它可以被重新使用。基本上，这些函数临时增加或减少活动的线程数，在实现对 QThreadPool 不可见的耗时操作时非常有用。

请注意，QThreadPool 是一个用于管理线程的低级别类，有关高级别的替代方案，请参阅 Qt 并发模块。

另请参阅

QRunnable

注释

当使用 from __feature__ import true_property 时可以直接使用属性，否则可以通过访问函数使用。

property activeThreadCountᅟ: int#

此属性包含线程池中活动线程的数量。

注释

此函数可能会返回一个大于 maxThreadCount() 的值。有关更多信息，请参阅 reserveThread()。

另请参阅

reserveThread() releaseThread()

访问函数
property expiryTimeoutᅟ: int#

此属性包含线程的超时时间（毫秒）。

如果线程在 expiryTimeout 毫秒内未使用，则被认为是已过期并将退出。这些线程将根据需要重新启动。默认的 expiryTimeout 是 30000 毫秒（30 秒）。如果 expiryTimeout 是负数，则新创建的线程将不会过期，例如，它们将不会退出，直到线程池被销毁。

请注意，设置 expiryTimeout 对已经运行的线程没有影响。只有新创建的线程才会使用新的 expiryTimeout。我们建议在创建线程池后立即设置 expiryTimeout，但是在调用 start()之前。

访问函数
属性maxThreadCount: int#

该属性包含线程池使用的最大线程数。当创建 QThreadPool 对象时，该属性默认为 idealThreadCount() 的值。

注释

即使 maxThreadCount 限制为零或负数，线程池也总是使用至少1个线程。

默认的 maxThreadCount 是 idealThreadCount()。

访问函数
属性stackSize: int#

该属性包含线程池工作线程的堆栈大小。

仅当线程池创建新线程时才使用属性的值。更改它对已创建或正在运行的线程没有影响。

默认值是 0，这将使 QThread 使用操作系统默认的堆栈大小。

访问函数
属性threadPriority: QThread.Priority#

该属性包含新工作线程的线程优先级。

仅当线程池启动新线程时才会使用属性的值。更改它对已运行的线程没有影响。

默认值是 InheritPriority，这将使 QThread 使用与 QThreadPool 对象相同的优先级。

另请参阅

Priority

访问函数
__init__([parent=None])#
参数：

parent – QObject

使用给定的 parent 构造一个线程池。

activeThreadCount()#
返回类型：

int

属性 activeThreadCount 的获取器。

clear()#

从队列中删除尚未启动的可执行程序。对于使 runnable->autoDelete() 返回 true 的可执行程序，将进行删除。

另请参阅

start()

contains(thread)#
参数：

thread – QThread

返回类型：

bool

如果 thread 是由该线程池管理的线程，返回 true。

expiryTimeout()#
返回类型：

int

另请参阅

setExpiryTimeout()

属性 expiryTimeout 的获取器。

static globalInstance()#
返回类型：

QThreadPool

返回全局 QThreadPool 实例。

maxThreadCount()#
返回类型：

int

另请参阅

setMaxThreadCount()

属性 maxThreadCount 的获取器。

releaseThread()#

放弃之前通过 reserveThread() 调用预留的线程。

注释

在调用该函数之前没有预先保留线程时临时增加 maxThreadCount() 的值。这在线程进入睡眠等待更多工作，允许其他线程继续时非常有用。务必在停止等待后调用 reserveThread() ，以便线程池能够正确维护 activeThreadCount() 的值。

另请参阅

reserveThread()

reserveThread()#

保留一个线程，忽略 activeThreadCount() 和 maxThreadCount() 的值。

完成线程操作后，调用 releaseThread() 允许其被重复使用。

注释

即使保留 maxThreadCount() 个或更多的线程，线程池仍将允许至少一个线程。

注释

此函数将增加报告的活动线程数。这意味着使用此函数时，activeThreadCount() 可以返回一个大于 maxThreadCount() 的值。

另请参阅

releaseThread()

setExpiryTimeout(expiryTimeout)#
参数：

expiryTimeout – int

另请参阅

expiryTimeout()

此属性是 expiryTimeoutᅟ 的设置器。

setMaxThreadCount(maxThreadCount)#
参数：

maxThreadCount – int

另请参阅

maxThreadCount()

此属性是 maxThreadCountᅟ 的设置器。

setStackSize(stackSize)#
参数：

stackSize – int

另请参阅

stackSize()

此属性是 stackSizeᅟ 的设置器。

setThreadPriority(priority)#
参数：

priority – Priority

另请参阅

threadPriority()

此属性是 threadPriorityᅟ 的设置器。

stackSize()#
返回类型：

int

另请参阅

setStackSize()

属性 stackSize 的获取器。

start(arg__1[, priority=0])#
参数：

  • arg__1 – PyCallable

  • priority – int

start(runnable[, priority=0])
参数：

保留一个线程并使用它来运行 runnable，除非这样做将使当前线程计数超过 maxThreadCount() 。在这种情况下，将 runnable 添加到运行队列中。可以使用 priority 参数来控制运行队列的执行顺序。

请注意，如果 runnable->autoDelete() 返回 true，则线程池会获取 runnable 的所有权，并且当 runnable->run() 返回后，线程池将自动删除 runnable。如果 runnable->autoDelete() 返回 false，则 runnable 的所有权仍属于调用者。请注意，在调用此函数后将自动删除 runnable 会导致未定义的行为。

startOnReservedThread(runnable)#
参数：

runnable – QRunnable

释放之前通过 reserveThread() 保留的线程，并使用它来运行 runnable。

请注意，如果 runnable->autoDelete() 返回 true，则线程池会获取 runnable 的所有权，并且当 runnable->run() 返回后，线程池将自动删除 runnable。如果 runnable->autoDelete() 返回 false，则 runnable 的所有权仍属于调用者。请注意，在调用此函数后将自动删除 runnable 会导致未定义的行为。

注释

在没有保留线程的情况下调用此函数会导致未定义的行为。

另请参阅

reserveThread() start()

threadPriority()#
返回类型：

Priority

另请参阅

setThreadPriority()

属性 threadPriority 的获取器。

tryStart(arg__1)
参数：

arg__1 – PyCallable

返回类型：

bool

tryStart(runnable)
参数：

runnable – QRunnable

返回类型：

bool

尝试为运行 runnable 预留一个线程。

如果在调用时没有可用线程，则此函数不执行任何操作并返回 false。否则，将立即使用一个可用的线程运行 runnable，此函数返回 true。

注意，在成功情况下，如果 runnable->autoDelete() 返回 true，线程池将接管 runnable 的所有权，并且在 runnable->run() 返回后由线程池自动删除 runnable。如果 runnable->autoDelete() 返回 false，则 runnable 的所有权仍然属于调用者。请注意，在调用此函数后更改 runnable 上的自动删除将导致未定义行为。

tryTake(runnable)
参数：

runnable – QRunnable

返回类型：

bool

尝试将指定的 runnable 从队列中移除，如果它尚未开始。如果可运行对象尚未启动，则返回 true，并且 runnable 的所有权将转移给调用者（即使 runnable->autoDelete() == true）。否则返回 false。

注释

如果 runnable->autoDelete() == true，此函数可能会移除错误的可运行对象。这称为 ABA 问题：原始的可运行对象可能已经执行并被删除。该内存已被重新用于另一个可运行对象，然后被移除而不是预期的对象。因此，我们建议只为非自动删除的可运行对象调用此函数。

另请参阅

start() autoDelete()

waitForDone([msecs=-1])
参数：

msecs – int

返回类型：

bool

等待最多 msecs 毫秒，直到所有线程退出并从线程池中删除所有线程。如果所有线程都已删除，则返回 true；否则返回 false。如果 msecs 为 -1（默认值），则忽略超时（等待最后一个线程退出）。