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 綫程類 .

注意： 此類的所有函數綫程安全 .

特性

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)
`(從 6.3 起)` void	startOnReservedThread (QRunnable * runnable )
`(從 6.3 起)` void	startOnReservedThread (Callable && callableToRun )
QThread::Priority	threadPriority () const
bool	tryStart (QRunnable * runnable )
bool	tryStart (Callable && callableToRun )
bool	tryTake (QRunnable * runnable )
`(從 6.8 起)` bool	waitForDone (QDeadlineTimer deadline = QDeadlineTimer::Forever)
bool	waitForDone (int msecs )

靜態公共成員

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 自變量可以用於控製運行隊列的執行次序。

注意： 此函數僅參與重載解析，若 Callable 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 .

注意： 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 .

注意： 此函數僅參與重載解析，若 Callable 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 .

注意： 此函數僅參與重載解析，若 Callable 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 ().

`[since 6.8]` bool QThreadPool:: waitForDone ( QDeadlineTimer deadline = QDeadlineTimer::Forever)

Waits until deadline expires for all threads to exit and removes all threads from the thread pool. Returns true 若所有綫程被移除；否則它返迴 false .

該函數在 Qt 6.8 引入。

bool QThreadPool:: waitForDone ( int msecs )

等待直到 msecs 毫秒以便所有綫程退齣並移除所有綫程從綫程池。返迴 true 若所有綫程被移除；否則它返迴 false 。若 msecs is -1, this function waits for the last thread to exit.

QThreadPool 類

特性

公共函數

靜態公共成員

詳細描述

特性文檔編製

[read-only] activeThreadCount : const int

expiryTimeout : int

maxThreadCount : int

stackSize : uint

[since 6.2] threadPriority : QThread::Priority

成員函數文檔編製

QThreadPool:: QThreadPool ( QObject * parent = nullptr)

[virtual noexcept] QThreadPool:: ~QThreadPool ()

void QThreadPool:: clear ()

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

[static] QThreadPool *QThreadPool:: globalInstance ()

void QThreadPool:: releaseThread ()

void QThreadPool:: reserveThread ()

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

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

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

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

bool QThreadPool:: tryStart ( QRunnable * runnable )

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

bool QThreadPool:: tryTake ( QRunnable * runnable )

[since 6.8] bool QThreadPool:: waitForDone ( QDeadlineTimer deadline = QDeadlineTimer::Forever)

bool QThreadPool:: waitForDone ( int msecs )

內容

`[read-only]` activeThreadCount : const int

`[since 6.2]` threadPriority : QThread::Priority

`[virtual noexcept]` QThreadPool:: ~QThreadPool ()

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

`[static]` QThreadPool *QThreadPool:: globalInstance ()

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

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

`[since 6.8]` bool QThreadPool:: waitForDone ( QDeadlineTimer deadline = QDeadlineTimer::Forever)