SetThreadPriority 関数 (processthreadsapi.h)

[アーティクル]
08/25/2023

指定したスレッドの優先度値を設定します。この値は、スレッドのプロセスの優先度クラスと共に、スレッドの基本優先度レベルを決定します。

構文

BOOL SetThreadPriority(
  [in] HANDLE hThread,
  [in] int    nPriority
);

パラメーター

[in] hThread

優先度の値を設定するスレッドへのハンドル。

ハンドルには、THREAD_SET_INFORMATIONまたは THREAD_SET_LIMITED_INFORMATION アクセス権が必要です。詳細については、「スレッドセキュリティとアクセス権」を参照してください。Windows Server 2003: ハンドルには 、THREAD_SET_INFORMATION アクセス権が必要です。

[in] nPriority

スレッドの優先度の値。このパラメーターには、次の値のいずれかを指定できます。

優先度	意味
THREAD_MODE_BACKGROUND_BEGIN 0x00010000	バックグラウンド処理モードを開始します。システムは、フォアグラウンドでのアクティビティに大きな影響を与えることなくバックグラウンド作業を実行できるように、スレッドのリソーススケジュールの優先順位を下げる。この値は、 hThread が現在のスレッドへのハンドルである場合にのみ指定できます。スレッドが既にバックグラウンド処理モードになっている場合、関数は失敗します。 Windows Server 2003: この値はサポートされていません。
THREAD_MODE_BACKGROUND_END 0x00020000	バックグラウンド処理モードを終了します。システムは、スレッドがバックグラウンド処理モードに入る前と同じように、スレッドのリソーススケジューリングの優先順位を復元します。この値は、 hThread が現在のスレッドへのハンドルである場合にのみ指定できます。スレッドがバックグラウンド処理モードでない場合、関数は失敗します。 Windows Server 2003: この値はサポートされていません。
THREAD_PRIORITY_ABOVE_NORMAL 1	優先度クラスより 1 ポイント上の優先度。
THREAD_PRIORITY_BELOW_NORMAL -1	優先度 1 ポイント下の優先度クラス。
THREAD_PRIORITY_HIGHEST 2	優先度 2 ポイント以上の優先度クラス。
THREAD_PRIORITY_IDLE -15	IDLE_PRIORITY_CLASS、BELOW_NORMAL_PRIORITY_CLASS、NORMAL_PRIORITY_CLASS、ABOVE_NORMAL_PRIORITY_CLASS、またはHIGH_PRIORITY_CLASSプロセスの場合は基本優先度 1、REALTIME_PRIORITY_CLASS プロセスの基本優先度は 16 です。
THREAD_PRIORITY_LOWEST -2	優先度 2 ポイント下の優先度クラス。
THREAD_PRIORITY_NORMAL 0	優先度クラスの通常の優先度。
THREAD_PRIORITY_TIME_CRITICAL 15	IDLE_PRIORITY_CLASS、BELOW_NORMAL_PRIORITY_CLASS、NORMAL_PRIORITY_CLASS、ABOVE_NORMAL_PRIORITY_CLASS、またはHIGH_PRIORITY_CLASSプロセスの場合は基本優先度 15、REALTIME_PRIORITY_CLASS プロセスの基本優先度は 31 です。

スレッドに REALTIME_PRIORITY_CLASS 基本クラスがある場合、このパラメーターは -7、-6、-5、-4、-3、3、4、5、または 6 にすることもできます。詳細については、「スケジュールの優先順位」を参照してください。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合は、0 を返します。詳細なエラー情報を得るには、GetLastError を呼び出します。

Windows Phone 8.1: Windows Phone ストアアプリはこの関数を呼び出す可能性がありますが、効果はありません。関数は、成功を示す 0 以外の値を返します。

注釈

すべてのスレッドには、スレッドの優先度値とそのプロセスの優先度クラスによって決まる基本優先度レベルがあります。システムは、すべての実行可能スレッドの基本優先度レベルを使用して、CPU 時間の次のスライスを取得するスレッドを決定します。スレッドは各優先度レベルでラウンドロビン方式でスケジュールされ、より高いレベルの実行可能スレッドがない場合にのみ、より低いレベルのスレッドのスケジュールが行われます。

SetThreadPriority 関数を使用すると、プロセスの優先度クラスに対する相対的なスレッドの基本優先度レベルを設定できます。たとえば、 IDLE_PRIORITY_CLASS プロセスのスレッドの SetThreadPriority の呼び出しで THREAD_PRIORITY_HIGHEST を指定すると、スレッドの基本優先度レベルが 6 に設定されます。優先度クラスとスレッド優先度値の組み合わせごとの基本優先度レベルを示すテーブルについては、「スケジュールの優先順位」を参照してください。

IDLE_PRIORITY_CLASS、BELOW_NORMAL_PRIORITY_CLASS、NORMAL_PRIORITY_CLASS、ABOVE_NORMAL_PRIORITY_CLASS、HIGH_PRIORITY_CLASSの各プロセスでは、スレッドにとって重要なイベントが発生したときに、システムによってスレッドの基本優先度レベルが動的に向上します。 REALTIME_PRIORITY_CLASS プロセスは動的ブーストを受け取りません。

すべてのスレッドは、最初は THREAD_PRIORITY_NORMALから開始されます。 GetPriorityClass 関数と SetPriorityClass 関数を使用して、プロセスの優先度クラスを取得および設定します。スレッドの優先度値を取得するには、 GetThreadPriority 関数を使用します。

プロセスの優先度クラスを使用して、タイムクリティカルなアプリケーションと、通常のスケジュール要件以下のアプリケーションを区別します。スレッド優先度の値を使用して、プロセスのタスクの相対的な優先順位を区別します。たとえば、ウィンドウの入力を処理するスレッドは、CPU に対して集中的な計算を実行するスレッドよりも優先度レベルが高い場合があります。

優先順位を操作する場合は、優先度の高いスレッドが使用可能なすべての CPU 時間を消費しないように十分に注意してください。基本優先度レベルが 11 を超えるスレッドは、オペレーティングシステムの通常の操作に干渉します。 REALTIME_PRIORITY_CLASSを使用すると、ディスクキャッシュがフラッシュされず、マウスが応答しなくなる可能性があります。

THREAD_PRIORITY_* 値は、スレッドの CPU スケジューリング優先度に影響します。ファイル I/O、ネットワーク I/O、データ処理などのバックグラウンド処理を実行するスレッドの場合、CPU スケジュールの優先順位を調整するだけでは十分ではありません。アイドル状態の CPU 優先度スレッドであっても、ディスクとメモリを使用すると、システムの応答性に簡単に干渉する可能性があります。バックグラウンド作業を実行するスレッドは、 THREAD_MODE_BACKGROUND_BEGIN 値と THREAD_MODE_BACKGROUND_END 値を使用して、リソーススケジュールの優先順位を調整する必要があります。ユーザーと対話するスレッドでは 、THREAD_MODE_BACKGROUND_BEGINを使用しないでください。

スレッドがバックグラウンド処理モードの場合、プロセス内の他のスレッドとのクリティカルセクション、ヒープ、ハンドルなどのリソースの共有を最小限に抑える必要があります。そうしないと、優先順位の逆転が発生する可能性があります。優先度の高いスレッドが実行されている場合、バックグラウンド処理モードのスレッドは速やかにスケジュールされないことがありますが、枯渇することはありません。

Windows Server 2008 と Windows Vista: システムの起動中、 SetThreadPriority 関数は成功の戻り値を返しますが、システムのスタートアップフォルダーから起動されたアプリケーションや 、HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run レジストリキーに一覧表示されているアプリケーションのスレッド優先度は変更されません。これらのアプリケーションは、起動時のユーザーアクションに対するシステムの応答性を高めるために、短時間 (約 60 秒) の低い優先度で実行されます。

Windows 8.1とWindows Server 2012 R2: この関数は、Windows ストアアプリでサポートされています。

Windows Phone 8.1:Windows Phone ストアアプリはこの関数を呼び出す可能性がありますが、効果はありません。

例

次の例では、スレッドバックグラウンドモードの使用を示します。

#include <windows.h>
#include <tchar.h>

int main( void )
{
   DWORD dwError, dwThreadPri;

   if(!SetThreadPriority(GetCurrentThread(), THREAD_MODE_BACKGROUND_BEGIN))
   {
      dwError = GetLastError();
      if( ERROR_THREAD_MODE_ALREADY_BACKGROUND == dwError)
         _tprintf(TEXT("Already in background mode\n"));
      else _tprintf(TEXT("Failed to enter background mode (%d)\n"), dwError);
      goto Cleanup;
   } 

   // Display thread priority

   dwThreadPri = GetThreadPriority(GetCurrentThread());

   _tprintf(TEXT("Current thread priority is 0x%x\n"), dwThreadPri);

   //
   // Perform background work
   //
   ;

   if(!SetThreadPriority(GetCurrentThread(), THREAD_MODE_BACKGROUND_END))
   {
      _tprintf(TEXT("Failed to end background mode (%d)\n"), GetLastError());
   }

Cleanup:
   // Clean up
   ;
return 0;
}

要件

要件	値
サポートされている最小のクライアント	Windows XP [デスクトップアプリ \| UWP アプリ]
サポートされている最小のサーバー	Windows Server 2003 [デスクトップアプリのみ \| UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	processthreadsapi.h (Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2 の場合は Windows.h を含む)
Library	Kernel32.lib;Windows Phone 8.1 の WindowsPhoneCore.lib
[DLL]	Kernel32.dll;Windows Phone 8.1 での KernelBase.dll