Класс QThreadPool

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

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