SetThreadPriority 関数 (processthreadsapi.h)

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

構文

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

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

スレッドに 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;
}

要件

こちらもご覧ください

GetPriorityClass

GetThreadPriority

プロセス関数とスレッド関数

優先度のスケジュール設定

SetPriorityClass

スレッド