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

Потоки, которые не используются в течение определенного времени, истекут. Время истечения по умолчанию составляет 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-проблема: исходный запуск уже мог выполниться и с тех пор был удалён. Память повторно используется для другого запуска, который затем удаляется вместо предназначенного. По этой причине мы рекомендуем вызывать эту функцию только для запусков, которые не удаляются автоматически.

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

См. также start() и QRunnable::autoDelete().

bool QThreadPool::waitForDone(int msecs = -1)

Ожидает до msecs миллисекунд, пока все потоки завершат работу, и удаляет все потоки из пула потоков. Возвращает true если все потоки были удалены; в противном случае возвращает false. Если msecs равно -1 (по умолчанию), таймаут игнорируется (ожидается завершение последнего потока).