QThread Class

メンバ関数のドキュメント

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

新しいスレッドを管理するための新しい QThread を作成します。parent がその QThread の所有権を取得します。start() が呼び出されるまで、スレッドの実行は開始されません。

start()も参照してください 。

[virtual noexcept] QThread::~QThread()

QThread を破棄します。

QThread オブジェクトを削除しても、それが管理しているスレッドの実行は停止しないことに注意してください。実行中のQThread を削除すると（つまり、isFinished()がfalse を返す場合）、プログラムがクラッシュします。QThread を削除する前に、finished()シグナルを待機してください。

Qt 6.3 以降では、QThread::create() の呼び出しによって作成されたQThread インスタンスを、対応するスレッドがまだ実行中であっても削除できるようになりました。 そのような場合、Qt はそのスレッドに割り込み要求を送信し（requestInterruption() 経由）、スレッドのイベントループ（存在する場合）に終了を要求し（quit() 経由）、スレッドが終了するまでブロックします。

create()、isInterruptionRequested()、exec()、およびquit()も参照してください 。

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

引数args を用いて関数f を実行する、新しいQThread オブジェクトを作成します。

新しいスレッドは起動されません。start() を明示的に呼び出すことで起動する必要があります。これにより、そのシグナルへの接続、QObject のスレッドへの移動、新しいスレッドの優先順位の選択などを行うことができます。関数f は、新しいスレッド内で呼び出されます。

新しく作成されたQThread インスタンスを返します。

関連項目： start()。

[static] QThread *QThread::currentThread()

現在実行中のスレッドを管理するQThread へのポインタを返します。

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

現在実行中のスレッドのスレッドハンドルを返します。

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

QObject::event(QEvent *e) の再実装です。

QAbstractEventDispatcher *QThread::eventDispatcher() const

そのスレッドのイベントディスパッチャオブジェクトへのポインタを返します。そのスレッドにイベントディスパッチャが存在しない場合、この関数はnullptr を返します。

setEventDispatcher()も参照してください 。

[protected] int QThread::exec()

イベントループに入り、exit() が呼び出されるまで待機し、exit() に渡された値を返します。quit() を通じてexit() が呼び出された場合、返される値は 0 になります。

この関数は、run() 内から呼び出されることを意図しています。イベント処理を開始するには、この関数を呼び出す必要があります。

関連項目： quit() およびexit()。

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

スレッドのイベントループに、リターンコードを指定して終了するよう指示します。

この関数を呼び出すと、スレッドはイベントループを離れ、QEventLoop::exec() の呼び出しから戻ります。QEventLoop::exec() 関数は、returnCode を返します。

慣例により、returnCode の値が0の場合は成功を意味し、0以外の値はエラーを示します。

なお、同名の C ライブラリ関数とは異なり、この関数は呼び出し元に制御を戻します。停止するのはイベント処理そのものです。

QThread::exec()が再度呼び出されるまで、このスレッドではQEventLoopはこれ以上開始されません。QThread::exec()内のイベントループが実行されていない場合、次にQThread::exec()が呼び出されても即座に返ります。

注： この関数はスレッドセーフです。

quit() およびQEventLoopも参照してください 。

[private signal] void QThread::finished()

このシグナルは、関連するスレッドが実行を終了する直前に発せられます。

このシグナルが発せられた時点で、イベントループはすでに実行を停止しています。そのスレッドでは、遅延削除イベントを除き、これ以上のイベントは処理されません。このシグナルをQObject::deleteLater()に接続することで、そのスレッド内のオブジェクトを解放することができます。

started()も参照してください 。

[static noexcept] int QThread::idealThreadCount()

このプロセスが並列で実行できる理想的なスレッド数を返します。これは、このプロセスが利用可能な論理プロセッサの数（OSがサポートしている場合）またはシステム内の論理プロセッサの総数を照会することで行われます。どちらの値も特定できなかった場合、この関数は 1 を返します。

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

このスレッドがQThread::currentThread である場合、trueを返します。

この関数は Qt 6.8 で導入されました。

currentThreadId()も参照してください 。

bool QThread::isFinished() const

スレッドが終了している場合は `true ` を返し、そうでない場合は `false` を返します。

スレッドは、run() 関数から戻り、かつfinished() シグナルが発信された場合に、終了したとみなされます。

finished() シグナルが発信された後も、スレッドは任意の時間だけ実行され続け、thread_local 変数のデストラクタの実行などのクリーンアップ操作を行う場合があることに注意してください。スレッドによるすべての影響を同期させるには、wait() を呼び出し、true が返されたことを確認してください。

注： この関数はスレッドセーフです。

isRunning()も参照してください 。

bool QThread::isInterruptionRequested() const

このスレッドで実行中のタスクを停止すべき場合は、true を返します。中断は `requestInterruption()` を呼び出すことで要求できます。

この関数を使用することで、長時間実行されるタスクを適切に中断可能にすることができます。この関数が返す値を確認したり、それに基づいて処理を行ったりしなくても安全ですが、長時間実行される関数では定期的に確認することをお勧めします。オーバーヘッドを抑えるため、呼び出し頻度が高くなりすぎないよう注意してください。

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

関連項目： currentThread() およびrequestInterruption()。

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

現在実行中のスレッドがメインスレッドであるかどうかを返します。

メインスレッドとは、QCoreApplication が生成されたスレッドのことです。これは通常、main() 関数を呼び出したスレッドですが、必ずしもそうとは限りません。これは、GUI イベントを処理し、グラフィカルオブジェクト（QWindow 、QWidget ）を作成できるスレッドです。

この関数は Qt 6.8 で導入されました。

currentThread() およびQCoreApplication::instance()も参照してください 。

bool QThread::isRunning() const

スレッドが実行中の場合は `true ` を返し、そうでない場合は `false` を返します。

QThread がstart()によって開始され、まだ終了していない場合、そのスレッドは実行中とみなされます。

finished() シグナルが送信された後も、スレッドは任意の時間だけ実行され続け、thread_local 変数のデストラクタの実行などのクリーンアップ操作を行う場合があることに注意してください。スレッドによるすべての影響を同期させるには、wait() を呼び出し、true が返されたことを確認してください。

注： この関数はスレッドセーフです。

isFinished()も参照してください 。

int QThread::loopLevel() const

そのスレッドの現在のイベントループレベルを返します。

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

これはオーバーロードされた関数であり、以下の呼び出しと同等です：

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

sleep() およびusleep()も参照してください 。

QThread::Priority QThread::priority() const

実行中のスレッドの優先度を返します。スレッドが実行されていない場合、この関数はInheritPriority を返します。

Priority 、setPriority()、およびstart()も参照してください 。

[slot] void QThread::quit()

スレッドのイベントループに対し、リターンコード 0（成功）で終了するよう指示します。QThread::exit(0) を呼び出すのと同じです。

スレッドにイベントループがない場合、この関数は何も行いません。

注： この関数はスレッドセーフです。

exit() およびQEventLoopも参照してください 。

void QThread::requestInterruption()

スレッドの中断を要求します。この要求は勧告的なものであり、その要求に応じて動作するかどうか、またどのように動作するかは、そのスレッド上で実行されているコードに委ねられています。この関数は、スレッド上で実行中のイベントループを停止させることはなく、いかなる方法でもスレッドを終了させることはありません。

この関数はメインスレッドには影響を与えず、スレッドが現在実行されていない場合は何も行いません。

注： この関数はスレッドセーフです。

関連項目： isInterruptionRequested()。

[virtual protected] void QThread::run()

スレッドの開始点です。start() を呼び出した後、新しく作成されたスレッドがこの関数を呼び出します。デフォルトの実装では、単にexec() を呼び出すだけです。

高度なスレッド管理を行うために、この関数を再実装することができます。このメソッドから戻ると、スレッドの実行が終了します。

start() およびwait()も参照してください 。

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

スレッドの現在のサービス品質（QoS）レベルを返します。

この関数は Qt 6.9 で導入されました。

setServiceLevel() およびQThreadPool::serviceLevel()も参照してください 。

void QThread::setEventDispatcher(QAbstractEventDispatcher *eventDispatcher)

スレッドのイベントディスパッチャを `eventDispatcher` に設定します。これは、そのスレッドにまだイベントディスパッチャが設定されていない場合にのみ可能です。

QCoreApplication がインスタンス化されるとメインスレッド用に、start()が呼び出されると補助スレッド用に、イベントディスパッチャが自動的に作成されます。

このメソッドは、オブジェクトの所有権を取得します。

eventDispatcher()も参照してください 。

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

この関数は、実行中のスレッドのpriority を設定します。スレッドが実行されていない場合、この関数は何も行わず、直ちに返ります。特定の優先度でスレッドを起動するには、start() を使用してください。

priority 引数には、InheritPriority を除く、QThread::Priority 列挙型の任意の値を指定できます。

priority パラメータの効果は、オペレーティングシステムのスケジューリングポリシーに依存します。特に、スレッドの優先度をサポートしていないシステム（Linuxなど。詳細についてはhttp://linux.die.net/man/2/sched_setschedulerを参照）では、priority は無視されます。

Priority 、priority()、およびstart()も参照してください 。

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

スレッドオブジェクトのサービス品質（QoS）レベルをserviceLevel に設定します。この関数は、スレッド自体から、またはスレッドが起動される前にのみ呼び出すことができます！

これは現在、AppleプラットフォームおよびWindowsでのみ実装されています。他のプラットフォームでは関数呼び出しは正常に完了しますが、現時点では何の効果もありません。

この関数は Qt 6.9 で導入されました。

serviceLevel() およびQThreadPool::setServiceLevel()も参照してください 。

void QThread::setStackSize(uint stackSize)

スレッドのスタックサイズをstackSize バイトに設定します。stackSize が0の場合、オペレーティングシステムまたはランタイムがデフォルト値を選択します。それ以外の場合は、指定された値がスレッドのスタックサイズとなります（値は切り上げまたは切り捨てされる場合があります）。

ほとんどのオペレーティングシステムでは、スタック用に割り当てられるメモリ量は当初stackSize より小さく、スレッドがスタックを使用するにつれて増加します。このパラメータは、スタックが拡大できる最大サイズ（つまり、スタックが占有できる仮想メモリ領域のサイズ）を設定します。

この関数は、スレッドが起動される前にのみ呼び出すことができます。

関連項目： stackSize()。

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

enabled パラメータに基づいて、現在のスレッドの終了を有効または無効にします。このスレッドは、QThread によって開始されている必要があります。

enabled がfalseの場合、終了は無効になります。以降のQThread::terminate()への呼び出しは、何の影響も与えずに即座に返ります。その代わり、終了は終了が有効になるまで延期されます。

enabled がtrueの場合、終了が有効になります。以降のQThread::terminate()の呼び出しは、スレッドを通常通り終了させます。終了が先送りされている場合（つまり、QThread::terminate()が終了無効状態で呼び出されていた場合）、この関数は呼び出し元のスレッドを直ちに終了させます。この場合、この関数は戻り値を出さないことに注意してください。

terminate()も参照してください 。

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

現在のスレッドをnsecs の間スリープ状態に強制します。

特定の条件が変化するのを待つ必要がある場合は、この関数の使用を避けてください。代わりに、その変化を示すシグナルにスロットを接続するか、イベントハンドラを使用してください（QObject::event() を参照）。

この関数は Qt 6.6 で導入されました。

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

現在のスレッドをsecs 秒間スリープ状態にします。

これはオーバーロードされた関数であり、以下の呼び出しと同等です:

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

msleep() およびusleep()も参照してください 。

uint QThread::stackSize() const

そのスレッドの最大スタックサイズをバイト単位で返します（setStackSize() で設定されている場合）。そうでない場合は 0 を返します。

setStackSize()も参照してください 。

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

run() を呼び出して、スレッドの実行を開始します。オペレーティングシステムは、priority パラメータに従ってスレッドをスケジューリングします。スレッドがすでに実行中の場合、この関数は何もしません。

priority パラメータの挙動は、オペレーティングシステムのスケジューリングポリシーによって異なります。特に、スレッドの優先度をサポートしていないシステム（Linuxなど。詳細についてはsched_setschedulerのドキュメントを参照）では、priority は無視されます。

run() およびterminate()も参照してください 。

[private signal] void QThread::started()

このシグナルは、関連するスレッドが実行を開始した際にそのスレッドから発信されるため、このスレッドに接続されているスロットは、キュー経由の呼び出しによって呼び出される可能性があります。run() が呼び出される前にイベントが投稿されていた場合でも、スレッド間のシグナル配信がまだ保留中である可能性があります。

関連項目： run() およびfinished()。

[slot] void QThread::terminate()

スレッドの実行を終了します。スレッドが直ちに終了するかどうかは、オペレーティングシステムのスケジューリング方針によって異なります。確実に終了させるには、terminate() の後に `QThread::wait()` を実行してください。

スレッドが終了すると、そのスレッドの終了を待機していたすべてのスレッドが呼び出されます。

QThread::setTerminationEnabled() を呼び出すことで、終了を明示的に有効または無効にできます。終了が無効になっている状態でこの関数を呼び出すと、終了は再有効化されるまで延期されます。詳細については、QThread::setTerminationEnabled() のドキュメントを参照してください。

注： この関数はスレッドセーフです。

setTerminationEnabled()も参照してください 。

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

これはオーバーロードされた関数であり、以下の呼び出しと同等です：

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

sleep() およびmsleep()も参照してください 。

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

以下のいずれかの条件が満たされるまで、スレッドをブロックします：

• このQThread オブジェクトに関連付けられたスレッドの実行が終了したとき（つまり、run()から戻ったとき）。スレッドが終了している場合、この関数はtrueを返します。また、スレッドがまだ開始されていない場合もtrueを返します。
• deadline に到達した。期限が到来した場合、この関数は false を返します。

QDeadlineTimer::Forever に設定された期限タイマー（デフォルト）はタイムアウトすることはありません。この場合、関数は、スレッドがrun() から戻ったとき、またはスレッドがまだ開始されていない場合にのみ値を返します。

これは、POSIXのpthread_join() 関数と同様の機能を提供します。

sleep() およびterminate()も参照してください 。

bool QThread::wait(unsigned long time)

time は、待機時間をミリ秒単位で表します。time がULONG_MAXの場合、待機はタイムアウトすることはありません。

[static] void QThread::yieldCurrentThread()

現在のスレッドの実行を、もしあれば別の実行可能スレッドに譲ります。どのスレッドに切り替えるかは、オペレーティングシステムが決定することに注意してください。