Открытые типы
Открытые функции
Открытые слоты
Сигналы
Статические открытые члены
Защищенные функции
Статические защищенные члены
Подробное описание
Managing threads
Subclassing QThread

Описание класса QThread

The QThread class provides a platform-independent way to manage threads. Далее...

 #include <QThread>

Унаследован от: QObject.

От него наследуются:

Открытые типы

enum	Priority { IdlePriority, LowestPriority, LowPriority, NormalPriority, ..., InheritPriority }

Открытые функции

	QThread ( QObject * parent = 0 )
	~QThread ()
void	exit ( int returnCode = 0 )
bool	isFinished () const
bool	isRunning () const
Priority	priority () const
void	setPriority ( Priority priority )
void	setStackSize ( uint stackSize )
uint	stackSize () const
bool	wait ( unsigned long time = ULONG_MAX )

29 открытых функций, унаследованных от QObject

Открытые слоты

void	quit ()
void	start ( Priority priority = InheritPriority )
void	terminate ()

1 открытый слот, унаследованный от QObject

Сигналы

void	finished ()
void	started ()
void	terminated ()

1 сигнал, унаследованный от QObject

Статические открытые члены

QThread *	currentThread ()
Qt::HANDLE	currentThreadId ()
int	idealThreadCount ()
void	yieldCurrentThread ()

7 статических открытых членов, унаследованных от QObject

Защищенные функции

int	exec ()
virtual void	run ()

8 защищенных функций, унаследованных от QObject

Статические защищенные члены

void	msleep ( unsigned long msecs )
void	setTerminationEnabled ( bool enabled = true )
void	sleep ( unsigned long secs )
void	usleep ( unsigned long usecs )

Дополнительные унаследованные члены

1 свойство, унаследованное от QObject

Подробное описание

The QThread class provides a platform-independent way to manage threads.

A QThread object manages one thread of control within the program. To make code run in a separate thread, simply create a QThread, change the thread affinity of the QObject(s) that contain the code, and start() the new event loop. Например:

 class Worker : public QObject
 {
     Q_OBJECT

 public slots:
     void doWork() {
         ...
     }
 };

 void MyObject::putWorkerInAThread()
 {
     Worker *worker = new Worker;
     QThread *workerThread = new QThread(this);

     connect(workerThread, SIGNAL(started()), worker, SLOT(doWork()));
     connect(workerThread, SIGNAL(finished()), worker, SLOT(deleteLater()));
     worker->moveToThread(workerThread);

     // Starts an event loop, and emits workerThread->started()
     workerThread->start();
 }

The code inside the Worker's slot would then execute in a separate thread. In this example, the QThread triggers the Worker's doWork() slot upon starting, and frees the Worker's memory upon terminating. However, you are free to connect the Worker's slots to any signal, from any object, in any thread. It is safe to connect signals and slots across different threads, thanks to a mechanism called queued connections.

Note: If you interact with an object, using any technique other than queued signal/slot connections (e.g. direct function calls), then the usual multithreading precautions need to be taken.

Note: It is not possible to change the thread affinity of GUI objects; they must remain in the main thread.

Managing threads

QThread will notifiy you via a signal when the thread is started(), finished(), and terminated(), or you can use isFinished() and isRunning() to query the state of the thread.

You can stop the thread by calling exit() or quit(). In extreme cases, you may want to forcibly terminate() an executing thread. Однако это опасно и не рекомендуется. Please read the documentation for terminate() and setTerminationEnabled() for detailed information.

From Qt 4.8 onwards, it is possible to deallocate objects that live in a thread that has just ended, by connecting the finished() signal to QObject::deleteLater().

Use wait() to block the calling thread, until the other thread has finished execution (or until a specified time has passed).

Статические функции currentThreadId() и currentThread() возвращают идентификатор для текущего выполняющегося потока. Первая возвращает платформозависимый идентификатор потока, последняя - указатель на QThread.

Subclassing QThread

Subclassing QThread is unnecessary for most purposes, since QThread provides fully-functional thread management capabilities. Nonetheless, QThread can be subclassed if you wish to implement advanced thread management. This is done by adding new member functions to the subclass, and/or by reimplementing run(). QThread's run() function is analogous to an application's main() function -- it is executed when the thread is started, and the thread will end when it returns.

Note: Prior to Qt 4.4, the only way to use QThread for parallel processing was to subclass it and implement the processing code inside run(). This approach is now considered \b {bad practice}; a QThread should only manage a thread, not process data.

If you require event handling and signal/slot connections to work in your thread, and if you reimplement run(), you must explicitly call exec() at the end of your reimplementation:

 class AdvancedThreadManager : public QThread
 {
 protected:
     void run()
     {
         /* ... other code to initialize thread... */

         // Begin event handling
         exec();
     }
 };

QThread also provides static, platform independent sleep functions: sleep(), msleep(), and usleep() allow full second, millisecond, and microsecond resolution respectively.

Note: wait() and the sleep() functions should be unnecessary in general, since Qt is an event-driven framework. Instead of wait(), consider listening for the finished() signal. Instead of the sleep() functions, consider using QTimer.

It is important to remember that a QThread object usually lives in the thread where it was created, not in the thread that it manages. This oft-overlooked detail means that a QThread's slots will be executed in the context of its home thread, not in the context of the thread it is managing. For this reason, implementing new slots in a QThread subclass is error-prone and discouraged.

Описание типов-членов

enum QThread::Priority

Это перечисление описывает, как операционная система должна планировать выполнение только что созданных потоков.

Константа	Значение	Описание
`QThread::IdlePriority`	`0`	запланировать выполнение только тогда, когда ни один другой поток не запущен.
`QThread::LowestPriority`	`1`	запланировать выполнение реже, чем LowPriority.
`QThread::LowPriority`	`2`	запланировать выполнение реже, чем NormalPriority.
`QThread::NormalPriority`	`3`	приоритет по умолчанию в операционной системе.
`QThread::HighPriority`	`4`	запланировать выполнение чаще, чем NormalPriority.
`QThread::HighestPriority`	`5`	запланировать выполнение чаще, чем HighPriority.
`QThread::TimeCriticalPriority`	`6`	запланировать выполнение как можно чаще.
`QThread::InheritPriority`	`7`	использовать тот же приоритет, что и у создающего потока. Это значение по умолчанию.

Описание функций-членов

QThread::QThread ( QObject * parent = 0 )

Constructs a new QThread to manage a new thread. The parent takes ownership of the QThread. The thread does not begin executing until start() is called.

Смотрите также start().

QThread::~QThread ()

Destroys the QThread.

Note that deleting a QThread object will not stop the execution of the thread it manages. Удаление выполняющегося QThread (т.е. isFinished() возвращает false), вероятно, приведет к аварийному завершению программы. Wait for the finished() signal before deleting the QThread.

QThread * QThread::currentThread () `[static]`

Returns a pointer to a QThread which manages the currently executing thread.

Qt::HANDLE QThread::currentThreadId () `[static]`

Возвращает дескриптор потока, который выполняется в данный момент.

Предупреждение: Дескриптор, возвращаемый этой функцией, используется для внутренних целей и не должен использоваться нигде в коде приложения.

Предупреждение: В Windows возвращаемое значение является псевдодескриптором текущего потока. Оно не может быть использовано для числового сравнения. т.е., эта функция возвращает DWORD (Windows-Thread ID), возвращаемый Win32-функцией getCurrentThreadId(), а не HANDLE (Windows-Thread HANDLE), возвращаемый Win32-функцией getCurrentThread().

int QThread::exec () `[protected]`

Входит в цикл обработки событий и ждет вызова exit(), возвращая значение, которое было передано функцией exit(). Возвращается значение 0, если exit() была вызвана через quit().

Эту функцию необходимо вызвать, чтобы начать обработку событий.

Смотрите также quit() and exit().

void QThread::exit ( int returnCode = 0 )

Сообщает циклу обработки событий потока о необходимости выхода с кодом возврата returnCode.

После вызова этой функции поток выходит из цикла обработки событий и возвращается из вызова QEventLoop::exec(). Функция QEventLoop::exec() возвращает returnCode.

По соглашению, returnCode возвращает 0 при успехе и любое ненулевое значение, указывающее об ошибке.

Обратите внимание, что в отличие от библиотечной функции C с тем же именем, эта функция действительно возвращается в место вызова - она останавливает обработку событий.

QEventLoops больше не будет запущен в этом потоке, до тех пор пока снова не будет вызван QThread::exec(). Если цикл обработки событий в QThread::exec() не запущен, то и из следующего вызова QThread::exec() возврат будет произведен сразу.

Смотрите также quit() и QEventLoop.

void QThread::finished () `[signal]`

Этот сигнал испускается, когда поток завершает выполнение.

Смотрите также started() и terminated().

int QThread::idealThreadCount () `[static]`

Возвращает идеальное количество потоков, которое может быть запущено в системе. Она делает запрос количества процессорных ядер, как реальных, так и логических. Эта функция возвращает -1, если количество процессорных ядер не может быть определено.

bool QThread::isFinished () const

Возвращает true, если поток был завершен; иначе возвращает false.

Смотрите также isRunning().

bool QThread::isRunning () const

Возвращает true, если поток запущен; иначе возвращает false.

Смотрите также isFinished().

void QThread::msleep ( unsigned long msecs ) `[static protected]`

Forces the current thread to sleep for msecs milliseconds.

Смотрите также sleep() и usleep().

Priority QThread::priority () const

Возвращает приоритет запущенного потока. Если поток не запущен, функция возвращает InheritPriority.

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

Смотрите также Priority, setPriority() и start().

void QThread::quit () `[slot]`

Сообщает циклу обработки событий потока о необходимости выхода с кодом возврата 0 (успешное завершение). Эквивалентно вызову QThread::exit (0).

Эта функция ничего не делает, если поток не имеет цикла обработки событий.

Смотрите также exit() и QEventLoop.

void QThread::run () `[virtual protected]`

Начальная точка для потока. После вызова start() вновь созданный поток вызывает эту функцию. Реализация по умолчанию просто вызывает exec().

You can reimplement this function to facilitate advanced thread management. Возврат из этого метода закончит выполнение потока.

Смотрите также start() и wait().

void QThread::setPriority ( Priority priority )

Эта функция устанавливает приоритет priority для работы потока. Если поток не запущен, эта функция ничего не делает и сразу же возвращается. Используйте start() для запуска потока с определенным приоритетом.

Аргумент priority может принимать любые значения из перечисления QThread::Priority за исключением InheritPriorty.

Эффект от параметра priority зависит от политики планирования операционной системы. В частности, приоритет priority будет проигнорирован в системах, не поддерживающих приоритеты потоков (таких как Linux, смотрите http://linux.die.net/man/2/sched_setscheduler для получения дополнительной информации).

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

Смотрите также Priority, priority() и start().

void QThread::setStackSize ( uint stackSize )

Устанавливает максимальный размер стека для потока в stackSize. Если stackSize больше нуля, то максимальный размер стека устанавливается размером stackSize байт, иначе максимальный размер стека автоматически определяется операционной системой.

Предупреждение: Большинство операционных систем устанавливают ограничения на минимальный и максимальный размер стека потока. Поток не запустится, если размер стека находится вне этих пределов.

Смотрите также stackSize().

void QThread::setTerminationEnabled ( bool enabled = true ) `[static protected]`

Включает или отключает возможность прерывания текущего потока, основываясь на параметре enabled. Поток должен быть запущен QThread.

Когда enabled равен false, прерывание выключено. Последующие вызовы QThread::terminate() будут завершаться сразу же, без эффекта. Вместо этого завершение откладывается до тех пор, пока прерывание не будет включено.

Когда enabled равен true, прерывание включено. Последующие вызовы QThread::terminate() будут прерывать поток в нормальном режиме. Если прерывание было отложено (т.е. QThread::terminate() была вызвана, когда прерывание было отключено), эта функция немедленно прервет вызывающий поток. Обратите внимание на то, что в этом случае функция не вернет управление.

Смотрите также terminate().

void QThread::sleep ( unsigned long secs ) `[static protected]`

Заставляет текущий поток заснуть на secs секунд.

Смотрите также msleep() и usleep().

uint QThread::stackSize () const

Возвращает максимальный размер стека для потока (если он был установлен функцией setStackSize()); в противном случае возвращает ноль.

Смотрите также setStackSize().

void QThread::start ( Priority priority = InheritPriority ) `[slot]`

Begins execution of the thread by calling run(). The operating system will schedule the thread according to the priority parameter. Если поток уже запущен, то эта функция ничего не делает.

Смотрите также run() и terminate().

void QThread::started () `[signal]`

Этот сигнал испускается, когда поток начинает выполнение.

Смотрите также finished() и terminated().

void QThread::terminate () `[slot]`

Прерывает выполнение потока. The thread may or may not be terminated immediately, depending on the operating system's scheduling policies. Listen for the terminated() signal, or use QThread::wait() after terminate(), to be sure.

Когда поток прерывается, все потоки, ожидающие завершения этого потока, будут разбужены.

Предупреждение: Эта функция является опасной и ее использование не рекомендуется. Поток может быть прерван в любой точке алгоритма. Потоки могут быть прерваны во время изменения данных. Нет никаких шансов того, что поток произведет очистку за собой, разблокирует любые удерживаемые мьютексы и т.д. Словом, используйте эту функцию только в случае крайней необходимости.

Прерывание может быть явно включено или выключено вызовом QThread::setTerminationEnabled(). Вызов этой функции в то время, как прерывание отключено, приведет к тому, что прерывание будет отложено до тех пор, пока оно не будет повторно включено. Для получения дополнительной информации смотрите описание QThread::setTerminationEnabled().

Смотрите также setTerminationEnabled().

void QThread::terminated () `[signal]`

Этот сигнал испускается, когда поток прерывается.

Смотрите также started() и finished().

void QThread::usleep ( unsigned long usecs ) `[static protected]`

Forces the current thread to sleep for usecs microseconds.

Смотрите также sleep() и msleep().

bool QThread::wait ( unsigned long time = ULONG_MAX )

Блокирует поток до выполнения любого из этих условий:

Поток, связанный с этим объектом QThread, завершил выполнение (т.е. он вернулся из run()). Эта функция вернет true, если поток завершился. Она также вернет true, если поток еще не был запущен.
Истекло time миллисекунд. Если time равен ULONG_MAX (по умолчанию), то эта функция никогда не завершится по таймауту (поток должен будет вернуть управление из run()). Эта функция вернет false, если время ожидания истекло.

Это обеспечивает схожую с функцией POSIX pthread_join() функциональность.

Смотрите также sleep() и terminate().

void QThread::yieldCurrentThread () `[static]`

Отдает время выполнения текущего потока другому запущенному потоку, если такой имеется. Обратите внимание, что операционная система сама решает, на какой поток переключиться.

Оглавление