QThread Class

Dokumentation zu den Member-Funktionen

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

Erstellt einen neuen QThread zur Verwaltung eines neuen Threads. Der „ parent “ übernimmt die Verantwortung für den QThread. Der Thread beginnt erst mit der Ausführung, wenn „ start()“ aufgerufen wird.

Siehe auch ` start()`.

[virtual noexcept] QThread::~QThread()

Löscht das Objekt „ 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) führt zu einem Programmabsturz. Warten Sie auf das Signal „ finished()“, bevor Sie den „ QThread “ löschen.

Seit Qt 6.3 ist es zulässig, eine durch einen Aufruf von ` QThread::create()` erstellte ` QThread `-Instanz zu löschen, selbst 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, 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)

Erstellt 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 an seine Signale anzuhängen, `QObjects` in den Thread zu verschieben, die Priorität des neuen Threads festzulegen und so weiter. Die Funktion ` f ` wird im neuen Thread aufgerufen.

Gibt die neu erstellte QThread -Instanz zurück.

Siehe auch „ start()“.

[static] QThread *QThread::currentThread()

Gibt einen Zeiger auf ein ` QThread ` zurück, das 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)

Implementiert: ` QObject::event(QEvent *e)`.

QAbstractEventDispatcher *QThread::eventDispatcher() const

Gibt einen Zeiger auf das Ereignis-Dispatcher-Objekt für den Thread zurück. Wenn für den Thread kein Ereignis-Dispatcher vorhanden ist, gibt diese Funktion ` nullptr` zurück.

Siehe auch ` setEventDispatcher()`.

[protected] int QThread::exec()

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

Diese Funktion ist dafür vorgesehen, innerhalb von ` run()` aufgerufen zu werden. Der Aufruf dieser Funktion ist erforderlich, um die Ereignisbehandlung zu starten.

Siehe auch „ quit()“ und „ exit()“.

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

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

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

Gemäß Konvention bedeutet ein ` returnCode ` von 0 Erfolg, jeder Wert ungleich Null weist auf einen Fehler hin.

Beachten Sie, dass diese Funktion – anders als die gleichnamige C-Bibliotheksfunktion – zum Aufrufer zurückkehrt; es ist die Ereignisverarbeitung, die beendet wird.

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

Hinweis: Diese Funktion ist threadsicher.

Siehe auch quit() und QEventLoop.

[private signal] void QThread::finished()

Dieses Signal wird vom zugehörigen Thread unmittelbar vor Beendigung seiner Ausführung ausgesendet.

Wenn dieses Signal ausgesendet wird, ist die Ereignisschleife bereits angehalten. In diesem Thread werden keine weiteren Ereignisse mehr verarbeitet, mit Ausnahme von Ereignissen zum verzögerten Löschen. Dieses Signal kann mit ` QObject::deleteLater()` verknüpft 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. Dazu wird die Anzahl der für diesen Prozess verfügbaren logischen Prozessoren (sofern vom Betriebssystem unterstützt) oder die Gesamtzahl der logischen Prozessoren im System abgefragt. 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.

Ein Thread gilt als beendet, wenn er von der Funktion ` run()` zurückgekehrt ist und das Signal ` finished()` ausgelöst wurde.

Beachten Sie, dass der Thread nach dem Auslösen des Signals „ finished()“ noch für eine beliebige Zeitspanne weiterlaufen kann, um Aufräumvorgänge wie die Ausführung der Destruktoren für „ thread_local “-Variablen durchzuführen. Um die Synchronisation mit allen Auswirkungen des Threads sicherzustellen, rufen Sie „ wait()“ auf und überprüfen Sie, ob der Rückgabewert „true“ ist.

Hinweis: Diese Funktion ist threadsicher.

Siehe auch ` isRunning()`.

bool QThread::isInterruptionRequested() const

Gibt „true“ zurück, wenn die in diesem Thread ausgeführte Aufgabe angehalten werden soll. Eine Unterbrechung kann mit ` 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 überprüfen oder darauf zu reagieren; es ist jedoch ratsam, dies in lang laufenden Funktionen regelmäßig zu tun. Achten Sie darauf, die Funktion 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 Hauptthread ist der Thread, in dem „ QCoreApplication “ erstellt wurde. Dies ist in der Regel der Thread, der die Funktion „ main() “ aufgerufen hat, muss aber nicht unbedingt der Fall sein. Es handelt sich um den 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 gibt die Funktion „ false “ zurück.

Ein Thread gilt als laufend, wenn „ QThread “ mit „ start()“ gestartet wurde, aber noch nicht beendet ist.

Beachten Sie, dass der Thread nach dem Auslösen des Signals „ finished()“ noch für eine beliebige Zeitspanne weiterlaufen kann, um Aufräumvorgänge wie die Ausführung der Destruktoren für „ thread_local “-Variablen durchzuführen. Um die Synchronisation mit allen Auswirkungen des Threads sicherzustellen, rufen Sie „ wait()“ auf und überprüfen Sie, ob die Funktion „true“ zurückgibt.

Hinweis: Diese Funktion ist threadsicher.

Siehe auch ` isFinished()`.

int QThread::loopLevel() const

Gibt die aktuelle Event-Loop-Ebene für den Thread zurück.

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

Dies ist eine überladene Funktion, die dem Aufruf von

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

Siehe auch sleep() und usleep().

QThread::Priority QThread::priority() const

Gibt die Priorität eines laufenden Threads 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. Dies entspricht dem Aufruf von ` QThread::exit(0)`.

Diese Funktion hat keine Auswirkung, wenn der Thread keine Ereignisschleife besitzt.

Hinweis: Diese Funktion ist threadsicher.

Siehe auch ` exit()` und ` QEventLoop`.

void QThread::requestInterruption()

Fordert die Unterbrechung des Threads an. Diese Anforderung hat lediglich empfehlenden Charakter, und es liegt im Ermessen des auf dem Thread ausgeführten Codes, zu entscheiden, ob und wie er auf eine solche Anforderung reagieren soll. Diese Funktion stoppt keine auf dem Thread laufende Ereignisschleife und beendet den Thread in keiner Weise.

Diese Funktion hat keine Auswirkungen auf den Hauptthread und führt keine Aktion aus, wenn der Thread derzeit nicht läuft.

Hinweis: Diese Funktion ist threadsicher.

Siehe auch ` isInterruptionRequested()`.

[virtual protected] void QThread::run()

Der Startpunkt für den Thread. 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. Die Rückkehr aus dieser Methode beendet die Ausführung des Threads.

Siehe auch ` start()` und ` wait()`.

[since 6.9] QThread::QualityOfService QThread::serviceLevel() const

Gibt die aktuelle Quality-of-Service-Stufe des Threads zurück.

Diese Funktion wurde in Qt 6.9 eingeführt.

Siehe auch „ setServiceLevel()“ und „ QThreadPool::serviceLevel()“.

void QThread::setEventDispatcher(QAbstractEventDispatcher *eventDispatcher)

Legt den Ereignis-Dispatcher für den Thread auf „ eventDispatcher “ fest. Dies ist nur möglich, solange für den Thread noch kein Ereignis-Dispatcher installiert ist.

Ein Ereignis-Dispatcher wird automatisch für den Haupt-Thread erstellt, wenn „ QCoreApplication “ instanziiert wird, sowie bei „ start()“ für Hilfs-Threads.

Diese Methode übernimmt die Eigentümerschaft an dem Objekt.

Siehe auch ` eventDispatcher()`.

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

Diese Funktion legt die Priorität „ priority “ für einen laufenden Thread fest. Wenn der Thread nicht läuft, führt diese Funktion keine Aktion aus und kehrt sofort zurück. Verwenden Sie „ start()“, um einen Thread mit einer bestimmten Priorität zu starten.

Das Argument „ priority “ kann einen beliebigen Wert aus der Enumeration „ QThread::Priority “ annehmen, mit Ausnahme von „ InheritPriority “.

Die Wirkung des Parameters „ priority “ hängt von der Scheduling-Richtlinie des Betriebssystems ab. Insbesondere wird „ priority “ auf Systemen ignoriert, die keine Thread-Prioritäten unterstützen (z. B. unter Linux; weitere Details finden Sie unter http://linux.die.net/man/2/sched_setscheduler).

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

[since 6.9] void QThread::setServiceLevel(QThread::QualityOfService serviceLevel)

Setzen Sie die Quality-of-Service-Stufe des Thread-Objekts auf „ serviceLevel “. Dies kann nur vom Thread selbst oder vor dem Start des Threads aufgerufen werden!

Dies ist derzeit nur auf Apple-Plattformen und unter Windows implementiert. Der Funktionsaufruf wird auf anderen Plattformen zwar erfolgreich ausgeführt, hat dort derzeit jedoch keine Wirkung.

Diese Funktion wurde in Qt 6.9 eingeführt.

Siehe auch „ serviceLevel()“ und „ QThreadPool::setServiceLevel()“.

void QThread::setStackSize(uint stackSize)

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

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

Diese Funktion kann nur vor dem Start des Threads aufgerufen werden.

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 mit „ QThread “ gestartet worden sein.

Wenn „ enabled “ auf „false“ gesetzt ist, ist die Beendigung deaktiviert. Zukünftige Aufrufe von „ QThread::terminate()“ kehren sofort und ohne Wirkung zurück. Stattdessen wird die Beendigung aufgeschoben, bis sie aktiviert wird.

Ist ` enabled ` auf `true` gesetzt, ist die Beendigung aktiviert. Zukünftige Aufrufe von ` QThread::terminate()` beenden den Thread wie gewohnt. Wurde die Beendigung aufgeschoben (d. h., ` QThread::terminate()` wurde bei deaktivierter Beendigung aufgerufen), beendet diese Funktion den aufrufenden Thread sofort. 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 die Dauer von ` nsecs` in den Ruhezustand zu wechseln.

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 Ereignishandler (siehe QObject::event()).

Diese Funktion wurde in Qt 6.6 eingeführt.

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

Zwingt den aktuellen Thread, secs Sekunden lang zu ruhen.

Dies ist eine überladene Funktion, die dem Aufruf von

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

Siehe auch ` msleep()` und ` usleep()`.

uint QThread::stackSize() const

Gibt die maximale Stackgröße für den Thread in Byte zurück (sofern diese mit ` setStackSize()` festgelegt wurde); andernfalls wird Null zurückgegeben.

Siehe auch ` setStackSize()`.

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

Leitet die Ausführung des Threads durch Aufruf von ` run()` ein. Das Betriebssystem plant den Thread entsprechend dem Parameter ` priority ` ein. Wenn der Thread bereits läuft, führt diese Funktion keine Aktion aus.

Die Wirkung des Parameters ` priority ` hängt von der Planungsrichtlinie des Betriebssystems ab. Insbesondere wird ` priority ` auf Systemen ignoriert, die keine Thread-Prioritäten unterstützen (wie z. B. unter Linux; weitere Details finden Sie in der Dokumentation zu `sched_setscheduler` ).

Siehe auch ` run()` und ` terminate()`.

[private signal] void QThread::started()

Dieses Signal wird vom zugehörigen Thread ausgegeben, sobald dieser mit der Ausführung beginnt, sodass alle damit verbundenen Slots über einen Aufruf in der Warteschlange aufgerufen werden können. Auch wenn das Ereignis möglicherweise bereits vor dem Aufruf von run() gesendet wurde, kann die threadübergreifende Übermittlung des Signals noch ausstehen.

Siehe auch ` run()` und ` finished()`.

[slot] void QThread::terminate()

Beendet die Ausführung des Threads. Je nach den Scheduling-Richtlinien des Betriebssystems wird der Thread möglicherweise sofort beendet – oder auch nicht. Verwenden Sie zur Sicherheit nach `terminate()` die Funktion ` QThread::wait()`.

Wenn der Thread beendet wird, werden alle Threads, die auf dessen Beendigung warten, geweckt.

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 sie wieder aktiviert wird. Weitere Informationen finden Sie in der Dokumentation zu ` QThread::setTerminationEnabled()`.

Hinweis: Diese Funktion ist threadsicher.

Siehe auch ` setTerminationEnabled()`.

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

Dies ist eine überladene Funktion, die dem Aufruf von

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 ebenfalls „true“ zurück, wenn der Thread noch nicht gestartet wurde.
• Die Frist „ deadline “ ist abgelaufen. Diese Funktion gibt „false“ zurück, wenn die Frist abgelaufen ist.

Ein auf „ QDeadlineTimer::Forever “ (Standard) gesetzter Deadline-Timer läuft niemals ab: In diesem Fall gibt die Funktion erst dann einen Wert zurück, wenn der Thread von ` run()` zurückkehrt oder wenn der Thread noch nicht gestartet wurde.

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

Siehe auch ` sleep()` und ` terminate()`.

bool QThread::wait(unsigned long time)

time ist die Wartezeit in Millisekunden. Wenn „ time “ den Wert ULONG_MAX annimmt, läuft die Wartezeit unbegrenzt.

[static] void QThread::yieldCurrentThread()

Überträgt die Ausführung des aktuellen Threads an einen anderen ausführbaren Thread, sofern vorhanden. Beachten Sie, dass das Betriebssystem entscheidet, zu welchem Thread gewechselt wird.