Класс QThreadPool

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

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

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

void QThreadPool::reserveThread()

Резервирует один поток, игнорируя activeThreadCount() и maxThreadCount().

После завершения работы с потоком вызовите releaseThread(), чтобы разрешить его повторное использование.

См. также 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 из очереди, если он ещё не запущен. Если запуск runnable не начался, функция возвращает true, и владение runnable передаётся вызывающему коду (даже если runnable->autoDelete() == true). В противном случае возвращает false.

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

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

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

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