Класс QThreadPool

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

Этот класс был представлен в 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(). Если 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. Данная функция заблокируется до завершения всех выполняемых задач.

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