Класс QThreadPool

Класс QThreadPool управляет набором потоков QThreads. Подробнее...

Этот класс был представлен в Qt 4.4.

• Список всех членов, включая наследуемые
• Устаревшие члены

Примечание: Все функции в этом классе являются безопасными для многопоточности.

Свойства

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

Открытые функции

Статические открытые члены

Подробное описание

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(). Если автоматическое удаление включено, QRunnable будет удален, когда последний поток завершит функцию run. Вызов start() несколько раз с тем же QRunnable, когда включено автоматическое удаление, создает гонку и не рекомендуется.

Потоки, которые не используются в течение определенного времени, истекают. По умолчанию время истечения срока действия равно 30000 миллисекунд (30 секунд). Это можно изменить, используя setExpiryTimeout(). Установка отрицательного времени истечения срока действия отключает механизм истечения срока действия.

Вызовите maxThreadCount(), чтобы получить максимальное количество используемых потоков. При необходимости вы можете изменить ограничение с помощью setMaxThreadCount(). Значение по умолчанию для maxThreadCount() — QThread::idealThreadCount(). Функция activeThreadCount() возвращает количество потоков, которые в данный момент выполняют работу.

Функция reserveThread() резервирует поток для внешнего использования. Используйте releaseThread(), когда закончите работу с потоком, чтобы он мог быть повторно использован. По сути, эти функции временно увеличивают или уменьшают количество активных потоков и полезны при реализации ресурсоёмких операций, которые не видны QThreadPool.

Обратите внимание, что QThreadPool — это класс низкого уровня для управления потоками. Для более высоких уровней альтернатив см. модуль Qt Concurrent.

См. также QRunnable.

Документация функций-членов

QThreadPool::QThreadPool(QObject *parent = nullptr)

Конструирует пул потоков с заданным parent.

[virtual] QThreadPool::~QThreadPool()

Уничтожает QThreadPool. Эта функция будет блокироваться до тех пор, пока все задачи не будут завершены.

void QThreadPool::clear()

Удаляет из очереди задачи, которые ещё не запущены. Задачи, для которых runnable->autoDelete() возвращает true удаляются.

Эта функция была добавлена в Qt 5.2.

См. также start().

bool QThreadPool::contains(const QThread *thread) const

Возвращает true , если thread управляется этим пулом потоков.

Эта функция была добавлена в Qt 6.0.

[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, если runnable->autoDelete() возвращает true, и runnable будет автоматически удалён пулом потоков после возврата из runnable->run(). Если runnable->autoDelete() возвращает false, владение runnable остаётся у вызывающего кода. Обратите внимание, что изменение автоудаления runnable после вызова этой функции приводит к неопределённому поведению.

void QThreadPool::start(std::function<void ()> functionToRun, int priority = 0)

Это перегруженная функция.

Резервирует поток и использует его для выполнения functionToRun, если при этом количество потоков не превысит maxThreadCount(). В противном случае functionToRun добавляется в очередь задач. Аргумент priority используется для управления порядком выполнения в очереди.

Эта функция была добавлена в Qt 5.15.

bool QThreadPool::tryStart(QRunnable *runnable)

Пытается зарезервировать поток для выполнения runnable.

Если потоков нет в момент вызова, эта функция ничего не делает и возвращает false. В противном случае runnable выполняется немедленно с использованием доступного потока, и эта функция возвращает true.

Обратите внимание, что в случае успеха, пул потоков берёт на себя ответственность за runnable, если runnable->autoDelete() возвращает true, и runnable будет автоматически удалён пулом потоков после возврата из runnable->run(). Если runnable->autoDelete() возвращает false, владение runnable остаётся у вызывающего кода. Изменение автоудаления runnable после вызова этой функции приводит к неопределённому поведению.

bool QThreadPool::tryStart(std::function<void ()> functionToRun)

Это перегруженная функция.

Пытается зарезервировать поток для выполнения functionToRun.

Если потоков нет в момент вызова, эта функция ничего не делает и возвращает false. В противном случае functionToRun выполняется немедленно с использованием доступного потока, и эта функция возвращает true.

Эта функция была добавлена в Qt 5.15.

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 (по умолчанию), таймаут игнорируется (ожидается завершение последнего потока).