Diagnosing Qt QThread Misuse: Subclassing vs moveToThread Workers

The Problem: Slots Never Fire, Timers Warn, and the App Crashes

Your Qt application spawns a background thread with QThread, but slots connected across threads never execute, QLabel or QWidget creation prints thread-affinity warnings, or the process segfaults inside QObject::connect. The common cause is mixing two incompatible ways of using QThread: overriding run() in a QThread subclass versus moving a QObject worker to a thread with moveToThread().

Useful takeaway: QThread is a thread controller, not a worker itself. If your subclass's run() performs procedural work and returns without starting an event loop, or creates QObjects before exec(), refactor to a Worker QObject moved to the thread before thread.start(). Shut down with quit() and wait(); never use terminate().

Recognizable Conditions

Look for these symptoms in logs, debugger output, or crashes:

• QObject::startTimer: Timers cannot be started from another thread
• Widgets such as QLabel or QPushButton created inside a worker thread
• Signals emitted from a worker that never reach slots in the GUI thread
• QObject::connect warnings about DirectConnection across thread boundaries
• A worker thread that starts and exits immediately without doing work

Cause and Diagnostic Table

Symptom	Likely Cause	Diagnostic Check
GUI widgets created in worker thread	run() constructs QObjects before exec()	Inspect QThread subclass run() for widget construction
Cross-thread DirectConnection failures	Worker QObject never moved to the thread	Compare QObject::thread() with QThread::currentThread()
Worker thread exits immediately	run() returns without an event loop	Check run() for exec() or blocking procedural code
Cross-thread parenting errors	Parent and child QObjects live in different threads	Audit parent-child relationships in object construction

Ordered Verification Checks

1. Search the source tree for QThread subclass declarations:

grep -R "public QThread" --include="*.cpp" --include="*.h" src/

Run this in the project root as a normal user. No elevated permissions are required. The command only reads files; it cannot modify state.

1. For each subclass, inspect run(). Does it call exec(), or does it perform procedural work and return?
2. Locate every QObject construction inside run() or functions called from run(). Widgets, timers, and network objects created here violate thread affinity.
3. Verify cross-thread connects. In Qt 5 and later, connect() auto-detects Qt::QueuedConnection when sender and receiver live in different threads, but only if the receiver's thread runs an event loop. Explicitly specify Qt::QueuedConnection when the intent must be unambiguous.
4. Confirm worker objects use moveToThread(&thread) before thread.start(). Moving an object after the thread starts, or moving an object with an active timer or pending network reply, is undefined behavior.
5. Check shutdown. The thread should use quit() followed by wait(). QThread::terminate() is dangerous and deprecated in Qt 6.

Fixes Tied to Findings

Finding: run() does procedural work without an event loop

Refactor to the worker pattern. Do not subclass QThread to do the work.

class Worker : public QObject {
    Q_OBJECT
public slots:
    void process() {
        // Background work runs here, in the worker thread.
        emit finished();
    }
signals:
    void finished();
};

// In the caller:
QThread thread;
Worker *worker = new Worker;
worker->moveToThread(&thread);
QObject::connect(&thread, &QThread::started, worker, &Worker::process);
QObject::connect(worker, &Worker::finished, &thread, &QThread::quit);
QObject::connect(worker, &Worker::finished, worker, &QObject::deleteLater);
QObject::connect(&thread, &QThread::finished, &thread, &QObject::deleteLater);
thread.start();

Place this configuration in the component that owns the background task, typically a controller or main window constructor. Run it as a normal user; it changes process state only at runtime.

Finding: QObjects created in run() before exec()

Move construction into the Worker constructor or an init slot invoked after moveToThread(). Never create GUI classes such as QLabel or QWidget inside run().

Finding: Cross-thread connects missing queued semantics

Add the connection type explicitly:

QObject::connect(worker, &Worker::resultReady,
                 receiver, &Receiver::handleResult,
                 Qt::QueuedConnection);

In Qt 5+, auto-connection usually handles this when threads differ, but Qt::QueuedConnection makes the requirement visible in code review. Remember: queued delivery requires an event loop in the receiver's thread.

Finding: No event loop in the worker thread

Ensure the thread runs exec() or use the moveToThread pattern above, where QThread supplies the event loop and the Worker supplies slots. A bare QThread subclass whose run() returns immediately will never deliver queued invocations.

Escalation Criteria

Escalate when:

• Crashes persist after correcting the QThread pattern. Suspect third-party library thread-safety or QObject reentrancy violations. Engage Qt commercial support with a minimal reproducer.
• Deadlocks involve QMutex or QWaitCondition across threads. Analyze with ThreadSanitizer (clang or gcc with -fsanitize=thread).
• Thread-priority inversion appears on embedded or RTOS targets. Consult the Qt Platform Abstraction (QPA) documentation for the target operating system.

Limitations and How to Verify

This guide covers well-established Qt 5 and Qt 6 behavior. Qt 6 deprecates QThread::terminate(); prefer requestInterruption() with quit() and wait(). Qt 6 also offers C++17 alternatives such as std::jthread and QtConcurrent, but legacy QThread patterns remain supported.

Verify your fix with these steps:

• Add qDebug() << QThread::currentThread() in constructors, slots, and run() to confirm thread affinity at runtime.
• Write a QSignalSpy unit test that emits a signal from the worker thread and asserts the receiving slot runs in the GUI thread with queued semantics.
• Compile with -fsanitize=thread and run under ThreadSanitizer to detect data races on shared QObjects.
• Use Qt Creator's Thread view to inspect each thread's call stack and event-loop status during debugging.

If the symptom disappears after the worker refactor and queued signals arrive in the correct thread, the diagnostic is complete. If crashes continue, collect a minimal reproducer before escalating.