QThread Class

Dokumentation der Mitgliedsfunktionen

[explicit] QThread::QThread(QObject *parent = nullptr)

Konstruiert einen neuen QThread, um einen neuen Thread zu verwalten. Die parent übernimmt den Besitz des QThreads. Der Thread beginnt nicht mit der Ausführung, bis start() aufgerufen wird.

Siehe auch start().

[virtual noexcept] QThread::~QThread()

Zerstört das QThread.

Beachten Sie, dass das Löschen eines QThread Objekts die Ausführung des von ihm verwalteten Threads nicht stoppt. Das Löschen eines laufenden QThread (d.h. isFinished() gibt false zurück) wird zu einem Programmabsturz führen. Warten Sie auf das Signal finished(), bevor Sie QThread löschen.

Seit Qt 6.3 ist es erlaubt, eine QThread Instanz zu löschen, die durch einen Aufruf von QThread::create() erzeugt wurde, auch wenn der entsprechende Thread noch läuft. In einem solchen Fall sendet Qt eine Unterbrechungsanforderung an diesen Thread (über requestInterruption()); fordert die Ereignisschleife des Threads (falls vorhanden) auf, ihn zu beenden (über quit()); und blockiert, bis der Thread beendet ist.

Siehe auch create(), isInterruptionRequested(), exec(), und quit().

[static] template <typename Function, typename... Args> QThread *QThread::create(Function &&f, Args &&... args)

Erzeugt ein neues QThread Objekt, das die Funktion f mit den Argumenten args ausführt.

Der neue Thread wird nicht gestartet - er muss durch einen expliziten Aufruf von start() gestartet werden. Dies ermöglicht es Ihnen, sich mit seinen Signalen zu verbinden, QObjects in den Thread zu verschieben, die Priorität des neuen Threads zu wählen und so weiter. Die Funktion f wird in dem neuen Thread aufgerufen.

Gibt die neu erstellte QThread Instanz zurück.

Siehe auch start().

[static] QThread *QThread::currentThread()

Gibt einen Zeiger auf eine QThread zurück, die den aktuell ausgeführten Thread verwaltet.

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

Gibt das Thread-Handle des aktuell ausgeführten Threads zurück.

[override virtual] bool QThread::event(QEvent *event)

Reimplements: QObject::event(QEvent *e).

QAbstractEventDispatcher *QThread::eventDispatcher() const

Gibt einen Zeiger auf das Event-Dispatcher-Objekt für den Thread zurück. Wenn kein Event-Dispatcher für den Thread existiert, gibt diese Funktion nullptr zurück.

Siehe auch setEventDispatcher().

[protected] int QThread::exec()

Tritt in die Ereignisschleife ein und wartet, bis exit() aufgerufen wird, und gibt den Wert zurück, der an exit() übergeben wurde. Der zurückgegebene Wert ist 0, wenn exit() über quit() aufgerufen wird.

Diese Funktion soll aus run() heraus aufgerufen werden. Es ist notwendig, diese Funktion aufzurufen, um die Ereignisbehandlung zu starten.

Siehe auch quit() und exit().

[slot] void QThread::exit(int returnCode = 0)

Weist die Ereignisschleife des Threads an, sie mit einem Rückgabewert zu beenden.

Nach dem Aufruf dieser Funktion verlässt der Thread die Ereignisschleife und kehrt zum Aufruf von QEventLoop::exec() zurück. Die Funktion QEventLoop::exec() gibt returnCode zurück.

Gemäß der Konvention bedeutet ein returnCode von 0 Erfolg, jeder Wert ungleich Null bedeutet einen Fehler.

Beachten Sie, dass diese Funktion, anders als die gleichnamige Funktion der C-Bibliothek , zum Aufrufer zurückkehrt - die Ereignisverarbeitung wird angehalten.

In diesem Thread werden keine QEventLoops mehr gestartet, bis QThread::exec() erneut aufgerufen wird. Wenn die Ereignisschleife in QThread::exec() nicht läuft, kehrt der nächste Aufruf von QThread::exec() ebenfalls sofort zurück.

Hinweis: Diese Funktion ist thread-sicher.

Siehe auch quit() und QEventLoop.

[private signal] void QThread::finished()

Dieses Signal wird von dem zugehörigen Thread ausgegeben, kurz bevor er seine Ausführung beendet.

Wenn dieses Signal ausgegeben wird, hat die Ereignisschleife bereits aufgehört zu laufen. Es werden keine weiteren Ereignisse in dem Thread verarbeitet, mit Ausnahme von aufgeschobenen Löschereignissen. Dieses Signal kann mit QObject::deleteLater() verbunden werden, um Objekte in diesem Thread freizugeben.

Siehe auch started().

[static noexcept] int QThread::idealThreadCount()

Gibt die ideale Anzahl von Threads zurück, die dieser Prozess parallel ausführen kann. Dies geschieht durch Abfrage der Anzahl der logischen Prozessoren, die diesem Prozess zur Verfügung stehen (falls vom Betriebssystem unterstützt) oder der Gesamtzahl der logischen Prozessoren im System. Diese Funktion gibt 1 zurück, wenn keiner der beiden Werte ermittelt werden konnte.

[noexcept, since 6.8] bool QThread::isCurrentThread() const

Gibt true zurück, wenn dieser Thread QThread::currentThread ist.

Diese Funktion wurde in Qt 6.8 eingeführt.

Siehe auch currentThreadId().

bool QThread::isFinished() const

Gibt true zurück, wenn der Thread beendet ist; andernfalls wird false zurückgegeben.

Hinweis: Diese Funktion ist thread-sicher.

Siehe auch isRunning().

bool QThread::isInterruptionRequested() const

Gibt true zurück, wenn die auf diesem Thread laufende Aufgabe angehalten werden soll. Eine Unterbrechung kann durch requestInterruption() angefordert werden.

Diese Funktion kann verwendet werden, um lang laufende Aufgaben sauber unterbrechbar zu machen. Es ist sicher, den von dieser Funktion zurückgegebenen Wert niemals zu prüfen oder zu verwenden, aber es ist ratsam, dies regelmäßig in lang laufenden Funktionen zu tun. Achten Sie darauf, sie nicht zu oft aufzurufen, um den Overhead gering zu halten.

void long_task() {
     forever {
        if ( QThread::currentThread()->isInterruptionRequested() ) {
            return;
        }
    }
}

Siehe auch currentThread() und requestInterruption().

[static noexcept, since 6.8] bool QThread::isMainThread()

Gibt zurück, ob der aktuell ausgeführte Thread der Hauptthread ist.

Der Haupt-Thread ist der Thread, in dem QCoreApplication erstellt wurde. Dies ist normalerweise der Thread, der die Funktion main() aufgerufen hat, aber nicht unbedingt. Es ist der Thread, der die GUI-Ereignisse verarbeitet und in dem grafische Objekte (QWindow, QWidget) erstellt werden können.

Diese Funktion wurde in Qt 6.8 eingeführt.

Siehe auch currentThread() und QCoreApplication::instance().

bool QThread::isRunning() const

Gibt true zurück, wenn der Thread läuft; andernfalls false.

Hinweis: Diese Funktion ist thread-sicher.

Siehe auch isFinished().

int QThread::loopLevel() const

Gibt die aktuelle Ereignisschleifenstufe des Threads zurück.

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

Dies ist eine überladene Funktion, die einem Aufruf entspricht:

QThread::sleep(std::chrono::milliseconds{msecs});

Siehe auch sleep() und usleep().

QThread::Priority QThread::priority() const

Gibt die Priorität für einen laufenden Thread zurück. Wenn der Thread nicht läuft, gibt diese Funktion InheritPriority zurück.

Siehe auch Priority, setPriority(), und start().

[slot] void QThread::quit()

Weist die Ereignisschleife des Threads an, mit dem Rückgabewert 0 (Erfolg) zu beenden. Äquivalent zum Aufruf von QThread::exit(0).

Diese Funktion bewirkt nichts, wenn der Thread keine Ereignisschleife hat.

Hinweis: Diese Funktion ist thread-sicher.

Siehe auch exit() und QEventLoop.

void QThread::requestInterruption()

die Unterbrechung des Threads anfordern. Diese Aufforderung hat beratenden Charakter und es obliegt dem auf dem Thread laufenden Code zu entscheiden, ob und wie er auf eine solche Aufforderung reagieren soll. Diese Funktion hält keine Ereignisschleife an, die auf dem Thread läuft, und beendet ihn in keiner Weise.

Hinweis: Diese Funktion ist thread-sicher.

Siehe auch isInterruptionRequested().

[virtual protected] void QThread::run()

Der Startpunkt des Threads. Nach dem Aufruf von start(), ruft der neu erstellte Thread diese Funktion auf. Die Standardimplementierung ruft einfach exec() auf.

Sie können diese Funktion neu implementieren, um eine erweiterte Thread-Verwaltung zu ermöglichen. Der Rücksprung von dieser Methode beendet die Ausführung des Threads.

Siehe auch start() und wait().

void QThread::setEventDispatcher(QAbstractEventDispatcher *eventDispatcher)

Setzt den Event-Dispatcher für den Thread auf eventDispatcher. Dies ist nur möglich, solange noch kein Event-Dispatcher für den Thread installiert ist.

Ein Ereignis-Dispatcher wird automatisch für den Haupt-Thread erstellt, wenn QCoreApplication instanziiert wird, und auf start() für Hilfs-Threads.

Diese Methode übernimmt das Eigentum an dem Objekt.

Siehe auch eventDispatcher().

void QThread::setPriority(QThread::Priority priority)

Diese Funktion setzt die priority für einen laufenden Thread. Wenn der Thread nicht läuft, tut diese Funktion nichts und kehrt sofort zurück. Verwenden Sie start(), um einen Thread mit einer bestimmten Priorität zu starten.

Das Argument priority kann ein beliebiger Wert aus der Aufzählung QThread::Priority sein, mit Ausnahme von InheritPriority.

Die Auswirkung des priority Parameters ist abhängig von der Scheduling Policy des Betriebssystems. Insbesondere wird priority auf Systemen ignoriert, die keine Thread-Prioritäten unterstützen (wie unter Linux, siehe http://linux.die.net/man/2/sched_setscheduler für weitere Details).

Siehe auch Priority, priority(), und start().

void QThread::setStackSize(uint stackSize)

Setzt die Stackgröße für den Thread auf stackSize. Ist stackSize gleich Null, wählt das Betriebssystem oder die Laufzeitumgebung einen Standardwert. Andernfalls entspricht die Stackgröße des Threads dem angegebenen Wert (der auf- oder abgerundet werden kann).

Auf den meisten Betriebssystemen ist der für den Stack zugewiesene Speicher anfangs kleiner als stackSize und wächst, wenn der Thread den Stack benutzt. Dieser Parameter legt die maximale Größe fest, auf die der Stack anwachsen darf (d.h. er legt die Größe des virtuellen Speicherplatzes fest, den der Stack belegen darf).

Diese Funktion kann nur aufgerufen werden, bevor der Thread gestartet wird.

Siehe auch stackSize().

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

Aktiviert oder deaktiviert die Beendigung des aktuellen Threads basierend auf dem Parameter enabled. Der Thread muss durch QThread gestartet worden sein.

Wenn enabled false ist, ist die Beendigung deaktiviert. Künftige Aufrufe von QThread::terminate() kehren sofort ohne Wirkung zurück. Stattdessen wird die Beendigung aufgeschoben, bis die Beendigung aktiviert wird.

Wenn enabled wahr ist, ist die Beendigung aktiviert. Zukünftige Aufrufe von QThread::terminate() werden den Thread normal beenden. Wenn die Beendigung aufgeschoben wurde (d.h. QThread::terminate() wurde mit deaktivierter Beendigung aufgerufen), wird diese Funktion den aufrufenden Thread sofort beenden. Beachten Sie, dass diese Funktion in diesem Fall nicht zurückkehrt.

Siehe auch terminate().

[static, since 6.6] void QThread::sleep(std::chrono::nanoseconds nsecs)

Zwingt den aktuellen Thread, für nsecs zu schlafen.

Vermeiden Sie die Verwendung dieser Funktion, wenn Sie auf die Änderung einer bestimmten Bedingung warten müssen. Verbinden Sie stattdessen einen Slot mit dem Signal, das die Änderung anzeigt, oder verwenden Sie einen Event-Handler (siehe QObject::event()).

Diese Funktion wurde in Qt 6.6 eingeführt.

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

Zwingt den aktuellen Thread, für secs Sekunden zu schlafen.

Dies ist eine überladene Funktion, die dem Aufruf entspricht:

QThread::sleep(std::chrono::seconds{secs});

Siehe auch msleep() und usleep().

uint QThread::stackSize() const

Gibt die maximale Stapelgröße für den Thread zurück (falls mit setStackSize() festgelegt); andernfalls wird Null zurückgegeben.

Siehe auch setStackSize().

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

Beginnt die Ausführung des Threads durch Aufruf von run(). Das Betriebssystem plant den Thread entsprechend dem Parameter priority. Wenn der Thread bereits läuft, bewirkt diese Funktion nichts.

Die Auswirkung des priority Parameters ist abhängig von der Scheduling Policy des Betriebssystems. Insbesondere wird priority auf Systemen ignoriert, die keine Thread-Prioritäten unterstützen (wie z.B. unter Linux, siehe die sched_setscheduler-Dokumentation für weitere Details).

Siehe auch run() und terminate().

[private signal] void QThread::started()

Dieses Signal wird von dem zugehörigen Thread ausgesendet, wenn er mit der Ausführung beginnt, so dass alle mit ihm verbundenen Slots über einen Aufruf in der Warteschlange aufgerufen werden können. Auch wenn das Ereignis bereits vor dem Aufruf von run() bekannt gegeben wurde, kann eine Thread-übergreifende Zustellung des Signals noch ausstehen.

Siehe auch run() und finished().

[slot] void QThread::terminate()

Beendet die Ausführung des Threads. Je nach den Zeitplanungsrichtlinien des Betriebssystems kann der Thread sofort beendet werden oder nicht. Verwenden Sie QThread::wait() nach terminate(), um sicherzugehen.

Wenn der Thread beendet wird, werden alle Threads, die auf die Beendigung des Threads warten, aufgeweckt.

Die Beendigung kann durch den Aufruf von QThread::setTerminationEnabled() explizit aktiviert oder deaktiviert werden. Der Aufruf dieser Funktion bei deaktivierter Beendigung führt dazu, dass die Beendigung aufgeschoben wird, bis die Beendigung wieder aktiviert wird. Siehe die Dokumentation von QThread::setTerminationEnabled() für weitere Informationen.

Hinweis: Diese Funktion ist thread-sicher.

Siehe auch setTerminationEnabled().

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

Dies ist eine überladene Funktion, die einem Aufruf entspricht:

QThread::sleep(std::chrono::microseconds{secs});

Siehe auch sleep() und msleep().

bool QThread::wait(QDeadlineTimer deadline = QDeadlineTimer(QDeadlineTimer::Forever))

Blockiert den Thread, bis eine der folgenden Bedingungen erfüllt ist:

• Der mit diesem QThread Objekt verbundene Thread hat die Ausführung beendet (d.h. wenn er von run() zurückkehrt). Diese Funktion gibt true zurück, wenn der Thread beendet ist. Sie gibt auch true zurück, wenn der Thread noch nicht gestartet wurde.
• Die deadline ist erreicht. Diese Funktion gibt false zurück, wenn die Frist erreicht ist.

Ein Deadline-Timer, der auf QDeadlineTimer::Forever (Standardeinstellung) gesetzt ist, läuft nie ab: In diesem Fall kehrt die Funktion nur zurück, wenn der Thread von run() zurückkehrt oder wenn der Thread noch nicht gestartet ist.

Dies bietet eine ähnliche Funktionalität wie die POSIX-Funktion pthread_join().

Siehe auch sleep() und terminate().

bool QThread::wait(unsigned long time)

Dies ist eine überladene Funktion.

time ist die zu wartende Zeit in Millisekunden. Wenn time ULONG_MAX ist, wird die Wartezeit nie überschritten.

[static] void QThread::yieldCurrentThread()

Übergibt die Ausführung des aktuellen Threads an einen anderen lauffähigen Thread, falls vorhanden. Beachten Sie, dass das Betriebssystem entscheidet, zu welchem Thread gewechselt werden soll.