QThreads general usage: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(Remove non-functioning "toc" command)
(fixed syntaxhighlighting and use more modern connect() methods)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Cleanup | reason=Auto-imported from ExpressionEngine.}}
{{LangSwitch}}
 
[[Category:Developing_with_Qt]]
[[Category:Developing_with_Qt]]
[[Category:snippets]]
[[Category:snippets]]
 
__NOTOC__
= QThreads General Usage =
Threads in an operating system are a very simple thing. Write a function, maybe bundle it with some data and push it onto a newly created thread. Use a mutex or other method to safely communicate with the thread if necessary. Whether it are Win32, POSIX or other threads, they all basically work the same and are quite fool-proof.
 
== Introduction ==
 
Threads in an operating system are a very simple thing. Write a function, maybe bundle it with some data and push it onto a newly created thread. Use a mutex or other method to safely communicate with the thread if necessary. Whether it are Win32, POSIX or other threads, they all basically work the same and are quite fool-proof. I'd venture to say that they're at least a lot easier to use and handle than sockets :)


Those who have discovered the joys of the Qt framework may assume that threads in Qt are just like this, and they would be right. However, there are several different ways to use threads in Qt, and it might not be obvious which approach to choose. The article, [http://doc.qt.io/qt-5/threads-technologies.html Multithreading Technologies in Qt], compares the different approaches.
Those who have discovered the joys of the Qt framework may assume that threads in Qt are just like this, and they would be right. However, there are several different ways to use threads in Qt, and it might not be obvious which approach to choose. The article, [http://doc.qt.io/qt-5/threads-technologies.html Multithreading Technologies in Qt], compares the different approaches.
Line 14: Line 9:
The rest of this article demonstrates one of these methods: '''QThread + a worker QObject'''. This method is intended for use cases which involve event-driven programming and signals + slots across threads.
The rest of this article demonstrates one of these methods: '''QThread + a worker QObject'''. This method is intended for use cases which involve event-driven programming and signals + slots across threads.


== Usage ==
== Usage with Worker class ==


The main thing to keep in mind when using a QThread is that it's not a thread. It's a wrapper around a thread object. This wrapper provides the signals, slots and methods to easily use the thread object within a Qt project. To use it, prepare a QObject subclass with all your desired functionality in it. Then create a new QThread instance, push the QObject onto it using moveToThread(QThread*) of the QObject instance and call start() on the QThread instance. That's all. You set up the proper signal/slot connections to make it quit properly and such, and that's all.
The main thing in this example to keep in mind when using a QThread is that it's not a thread. It's a wrapper around a thread object. This wrapper provides the signals, slots and methods to easily use the thread object within a Qt project. To use it, prepare a QObject subclass with all your desired functionality in it. Then create a new QThread instance, push the QObject onto it using moveToThread(QThread*) of the QObject instance and call start() on the QThread instance. That's all. You set up the proper signal/slot connections to make it quit properly and such, and that's all.


=== Declare Worker class ===
=== Declare Worker class ===
Line 22: Line 17:
For a basic example, check this class declaration for the Worker class:
For a basic example, check this class declaration for the Worker class:


<code>class Worker : public QObject {
<syntaxhighlight lang="c++">
Q_OBJECT
class Worker : public QObject {
 
    Q_OBJECT
public:
public:
Worker();
    Worker();
~Worker();
    ~Worker();
 
public slots:
public slots:
void process();
    void process();
 
signals:
signals:
void finished();
    void finished();
void error(QString err);
    void error(QString err);
 
private:
private:
// add your variables here
    // add your variables here
};</code>
};
</syntaxhighlight>


We add at least one public slot which will be used to trigger the instance and make it start processing data once the thread has started. Now, let's see what the implementation for this basic class looks like.
We add at least one public slot which will be used to trigger the instance and make it start processing data once the thread has started. Now, let's see what the implementation for this basic class looks like.


<code>// — CONSTRUCTOR —
<syntaxhighlight lang="c++">
Worker::Worker() {
Worker::Worker() { // Constructor
// you could copy data from constructor arguments to internal variables here.
    // you could copy data from constructor arguments to internal variables here.
}
}


// — DESTRUCTOR—
Worker::~Worker() { // Destructor
Worker::~Worker() {
    // free resources
// free resources
}
}


// — PROCESS —
void Worker::process() { // Process. Start processing data.
// Start processing data.
    // allocate resources using new here
void Worker::process() {
    qDebug("Hello World!");
// allocate resources using new here
    emit finished();
qDebug("Hello World!");
}
emit finished();
</syntaxhighlight>
}</code>


While this Worker class doesn't do anything special, it nevertheless contains all the required elements. It starts processing when its main function, in this case process(), is called and when it is done it emits the signal finished() which will then be used to trigger the shutdown of the QThread instance it is contained in.
While this Worker class doesn't do anything special, it nevertheless contains all the required elements. It starts processing when its main function, in this case process(), is called and when it is done it emits the signal finished() which will then be used to trigger the shutdown of the QThread instance it is contained in.
Line 68: Line 59:
Now, let's see how to use this new construction by creating a new Worker instance and putting it on a QThread instance:
Now, let's see how to use this new construction by creating a new Worker instance and putting it on a QThread instance:


<code>QThread* thread = new QThread;
<syntaxhighlight lang="c++">
QThread* thread = new QThread();
Worker* worker = new Worker();
Worker* worker = new Worker();
worker->moveToThread(thread);
worker->moveToThread(thread);
connect(worker, SIGNAL (error(QString)), this, SLOT (errorString(QString)));
connect( worker, &Worker::error, this, &MyClass::errorString);
connect(thread, SIGNAL (started()), worker, SLOT (process()));
connect( thread, &QThread::started, worker, &Worker::process);
connect(worker, SIGNAL (finished()), thread, SLOT (quit()));
connect( worker, &Worker::finished, thread, &QThread::quit);
connect(worker, SIGNAL (finished()), worker, SLOT (deleteLater()));
connect( worker, &Worker::finished, worker, &Worker::deleteLater);
connect(thread, SIGNAL (finished()), thread, SLOT (deleteLater()));
connect( thread, &QThread::finished, thread, &QThread::deleteLater);
thread->start();</code>
thread->start();
</syntaxhighlight>


The connect() series here is the most crucial part. The first connect() line hooks up the error message signal from the worker to an error processing function in the main thread. The second connects the thread's started() signal to the processing() slot in the worker, causing it to start.
The connect() series here is the most crucial part. The first connect() line hooks up the error message signal from the worker to an error processing function in the main thread. The second connects the thread's started() signal to the processing() slot in the worker, causing it to start.
Line 82: Line 75:
Then the clean-up: when the worker instance emits finished(), as we did in the example, it will signal the thread to quit, i.e. shut down. We then mark the worker instance using the same finished() signal for deletion. Finally, to prevent nasty crashes because the thread hasn't fully shut down yet when it is deleted, we connect the finished() of the thread (not the worker!) to its own deleteLater() slot. This will cause the thread to be deleted only after it has fully shut down.
Then the clean-up: when the worker instance emits finished(), as we did in the example, it will signal the thread to quit, i.e. shut down. We then mark the worker instance using the same finished() signal for deletion. Finally, to prevent nasty crashes because the thread hasn't fully shut down yet when it is deleted, we connect the finished() of the thread (not the worker!) to its own deleteLater() slot. This will cause the thread to be deleted only after it has fully shut down.


(taken from [http://mayaposch.wordpress.com/2011/11/01/how-to-really-truly-use-qthreads-the-full-explanation/ http://mayaposch.wordpress.com/2011/11/01/how-to-really-truly-use-qthreads-the-full-explanation/])
 
== External Links ==
# Maya Posch's blog, [http://mayaposch.wordpress.com/2011/11/01/how-to-really-truly-use-qthreads-the-full-explanation/ http://mayaposch.wordpress.com/2011/11/01/how-to-really-truly-use-qthreads-the-full-explanation/]
# Qt Blog on subclassing QThread is wrong, [https://blog.qt.io/blog/2010/06/17/youre-doing-it-wrong/]
# Woboq Blog on subclassing QThread is not always wrong, [http://woboq.com/blog/qthread-you-were-not-doing-so-wrong.html]

Latest revision as of 14:58, 5 May 2021

En Ar Bg De El Es Fa Fi Fr Hi Hu It Ja Kn Ko Ms Nl Pl Pt Ru Sq Th Tr Uk Zh

Threads in an operating system are a very simple thing. Write a function, maybe bundle it with some data and push it onto a newly created thread. Use a mutex or other method to safely communicate with the thread if necessary. Whether it are Win32, POSIX or other threads, they all basically work the same and are quite fool-proof.

Those who have discovered the joys of the Qt framework may assume that threads in Qt are just like this, and they would be right. However, there are several different ways to use threads in Qt, and it might not be obvious which approach to choose. The article, Multithreading Technologies in Qt, compares the different approaches.

The rest of this article demonstrates one of these methods: QThread + a worker QObject. This method is intended for use cases which involve event-driven programming and signals + slots across threads.

Usage with Worker class

The main thing in this example to keep in mind when using a QThread is that it's not a thread. It's a wrapper around a thread object. This wrapper provides the signals, slots and methods to easily use the thread object within a Qt project. To use it, prepare a QObject subclass with all your desired functionality in it. Then create a new QThread instance, push the QObject onto it using moveToThread(QThread*) of the QObject instance and call start() on the QThread instance. That's all. You set up the proper signal/slot connections to make it quit properly and such, and that's all.

Declare Worker class

For a basic example, check this class declaration for the Worker class:

class Worker : public QObject {
    Q_OBJECT
public:
    Worker();
    ~Worker();
public slots:
    void process();
signals:
    void finished();
    void error(QString err);
private:
    // add your variables here
};

We add at least one public slot which will be used to trigger the instance and make it start processing data once the thread has started. Now, let's see what the implementation for this basic class looks like.

Worker::Worker() { // Constructor
    // you could copy data from constructor arguments to internal variables here.
}

Worker::~Worker() { // Destructor
    // free resources
}

void Worker::process() { // Process. Start processing data.
    // allocate resources using new here
    qDebug("Hello World!");
    emit finished();
}

While this Worker class doesn't do anything special, it nevertheless contains all the required elements. It starts processing when its main function, in this case process(), is called and when it is done it emits the signal finished() which will then be used to trigger the shutdown of the QThread instance it is contained in.

By the way, one extremely important thing to note here is that you should NEVER allocate heap objects (using new) in the constructor of the QObject class as this allocation is then performed on the main thread and not on the new QThread instance, meaning that the newly created object is then owned by the main thread and not the QThread instance. This will make your code fail to work. Instead, allocate such resources in the main function slot such as process() in this case as when that is called the object will be on the new thread instance and thus it will own the resource.

Create a new Worker instance

Now, let's see how to use this new construction by creating a new Worker instance and putting it on a QThread instance:

QThread* thread = new QThread();
Worker* worker = new Worker();
worker->moveToThread(thread);
connect( worker, &Worker::error, this, &MyClass::errorString);
connect( thread, &QThread::started, worker, &Worker::process);
connect( worker, &Worker::finished, thread, &QThread::quit);
connect( worker, &Worker::finished, worker, &Worker::deleteLater);
connect( thread, &QThread::finished, thread, &QThread::deleteLater);
thread->start();

The connect() series here is the most crucial part. The first connect() line hooks up the error message signal from the worker to an error processing function in the main thread. The second connects the thread's started() signal to the processing() slot in the worker, causing it to start.

Then the clean-up: when the worker instance emits finished(), as we did in the example, it will signal the thread to quit, i.e. shut down. We then mark the worker instance using the same finished() signal for deletion. Finally, to prevent nasty crashes because the thread hasn't fully shut down yet when it is deleted, we connect the finished() of the thread (not the worker!) to its own deleteLater() slot. This will cause the thread to be deleted only after it has fully shut down.


External Links

  1. Maya Posch's blog, http://mayaposch.wordpress.com/2011/11/01/how-to-really-truly-use-qthreads-the-full-explanation/
  2. Qt Blog on subclassing QThread is wrong, [1]
  3. Woboq Blog on subclassing QThread is not always wrong, [2]