Класс QThreadPool

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

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

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

Свойства

• 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. Эта функция заблокируется до завершения всех задач.

[since 5.2] void QThreadPool::clear()

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

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

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

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

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

[since 5.15] bool QThreadPool::tryStart(std::function<void ()> functionToRun)

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

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

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

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

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