Класс QThreadPool

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

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

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

Свойства

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

• 1 свойство унаследовано от QObject

Публичные функции

• 32 публичные функции унаследованы от QObject

Статические публичные члены

• 11 статических публичных членов унаследованы от QObject

Дополнительные унаследованные члены

• 1 публичный слот унаследован от QObject
• 2 сигналы унаследованы от QObject
• 9 защищенных функций унаследованы от QObject

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

Класс QThreadPool управляет коллекцией QThreads.

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(). Установка отрицательного значения expiryTimeout отключает механизм истечения срока годности.

Вызовите 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().

[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 после вызова этой функции приводит к неопределённому поведению.

bool QThreadPool::tryStart(QRunnable *runnable)

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

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

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