SetThreadInformation 関数 (processthreadsapi.h)

指定したスレッドの情報を設定します。

構文

BOOL SetThreadInformation(
  [in] HANDLE                   hThread,
  [in] THREAD_INFORMATION_CLASS ThreadInformationClass,
       LPVOID                   ThreadInformation,
  [in] DWORD                    ThreadInformationSize
);

パラメーター

[in] hThread

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

[in] ThreadInformationClass

設定する情報のクラス。 サポートされている値は ThreadMemoryPriority と ThreadPowerThrottling のみです。

ThreadInformation

ThreadInformationClass パラメーターで指定された情報の種類を含む構造体へのポインター。

ThreadInformationClass パラメーターが ThreadMemoryPriority の場合、このパラメーターはMEMORY_PRIORITY_INFORMATION構造体を指す必要があります。

ThreadInformationClass パラメーターが ThreadPowerThrottling の場合、このパラメーターはTHREAD_POWER_THROTTLING_STATE構造体を指す必要があります。

[in] ThreadInformationSize

ThreadInformation パラメーターで指定された構造体のサイズ (バイト単位)。

ThreadInformationClass パラメーターが ThreadMemoryPriority の場合、このパラメーターは であるsizeof(MEMORY_PRIORITY_INFORMATION)必要があります。

ThreadInformationClass パラメーターが ThreadPowerThrottling の場合、このパラメーターは であるsizeof(THREAD_POWER_THROTTLING_STATE)必要があります。

戻り値

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

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

解説

システムのパフォーマンスを向上させるために、アプリケーションでは、ThreadMemoryPriority を使用して SetThreadInformation 関数を使用して、バックグラウンド操作を実行するスレッドのメモリ優先度を下げるか、ファイルやデータにアクセスする予定のないファイルとデータにすぐにアクセスする必要があります。 たとえば、マルウェア対策アプリケーションでは、ファイルのスキャンに関連するスレッドの優先順位が低くなる可能性があります。

メモリ優先度 は、ページがトリミングされるまでにプロセスの ワーキング セット 内に残っている時間を判断するのに役立ちます。 スレッドのメモリ優先度は、そのスレッドによって設定されたプロセスに追加される物理ページの最小優先度を決定します。 メモリ マネージャーは、ワーキング セットをトリミングすると、優先度の低いページを優先度の高いページの前にトリミングします。 これにより、優先度の高いページがワーキング セットからトリミングされる可能性が低くなり、再びアクセスされたときにページ フォールトがトリガーされるため、システム全体のパフォーマンスが向上します。

ThreadPowerThrottling では、最適なパフォーマンスが必要ない場合にパフォーマンスと電力効率のバランスを取るために使用できる、スレッドで調整ポリシーを有効にします。 スレッドが を有効にすることを THREAD_POWER_THROTTLING_EXECUTION_SPEED選択すると、スレッドは EcoQoS として分類されます。 システムは、CPU 周波数の削減や、より電力効率の高いコアの使用などの戦略を通じて、電力効率の向上を試みます。 EcoQoS は、作業がフォアグラウンドのユーザー エクスペリエンスに貢献していない場合に使用する必要があります。これにより、バッテリ寿命が長くなり、熱とファンのノイズが軽減されます。 EcoQoS は、パフォーマンスクリティカルまたはフォアグラウンドのユーザー エクスペリエンスには使用しないでください。 (Windows 11より前は、EcoQoS レベルは存在せず、プロセスは LowQoS としてラベル付けされていました)。 アプリケーションで を明示的に有効 THREAD_POWER_THROTTLING_EXECUTION_SPEEDにしない場合、システムは独自のヒューリスティックを使用して、サービス品質レベルを自動的に推論します。 詳細については、「サービスの品質」を参照してください。

例

次の例では、ThreadMemoryPriority を使用して SetThreadInformation を呼び出して、現在のスレッドのメモリ優先度を低く設定する方法を示します。

DWORD ErrorCode;
BOOL Success;
MEMORY_PRIORITY_INFORMATION MemPrio;

//
// Set low memory priority on the current thread.
//

ZeroMemory(&MemPrio, sizeof(MemPrio));
MemPrio.MemoryPriority = MEMORY_PRIORITY_LOW;

Success = SetThreadInformation(GetCurrentThread(),
                               ThreadMemoryPriority,
                               &MemPrio,
                               sizeof(MemPrio));

if (!Success) {
    ErrorCode = GetLastError();
    fprintf(stderr, "Set thread memory priority failed: %d\n", ErrorCode);
}

次の例は、スレッドのサービス品質を制御するために、ThreadPowerThrottling で SetThreadInformation を呼び出す方法を示しています。

THREAD_POWER_THROTTLING_STATE PowerThrottling;
ZeroMemory(&PowerThrottling, sizeof(PowerThrottling));
PowerThrottling.Version = THREAD_POWER_THROTTLING_CURRENT_VERSION;

//
// EcoQoS
// Turn EXECUTION_SPEED throttling on. 
// ControlMask selects the mechanism and StateMask declares which mechanism should be on or off.
//

PowerThrottling.ControlMask = THREAD_POWER_THROTTLING_EXECUTION_SPEED;
PowerThrottling.StateMask = THREAD_POWER_THROTTLING_EXECUTION_SPEED;

SetThreadInformation(GetCurrentThread(), 
                     ThreadPowerThrottling, 
                     &PowerThrottling, 
                     sizeof(PowerThrottling));

//
// HighQoS
// Turn EXECUTION_SPEED throttling off.
// ControlMask selects the mechanism and StateMask is set to zero as mechanisms should be turned off.
//

PowerThrottling.ControlMask = THREAD_POWER_THROTTLING_EXECUTION_SPEED;
PowerThrottling.StateMask = 0;

SetThreadInformation(GetCurrentThread(), 
                     ThreadPowerThrottling, 
                     &PowerThrottling, 
                     sizeof(PowerThrottling));

//
// Let system manage all power throttling. ControlMask is set to 0 as we don’t want 
// to control any mechanisms.
//

PowerThrottling.ControlMask = 0;
PowerThrottling.StateMask = 0;

SetThreadInformation(GetCurrentThread(), 
                     ThreadPowerThrottling, 
                     &PowerThrottling, 
                     sizeof(PowerThrottling));

要件

要件	値
サポートされている最小のクライアント	Windows 8 [デスクトップ アプリのみ]
サポートされている最小のサーバー	Windows Server 2012 [デスクトップ アプリのみ]
対象プラットフォーム	Windows
ヘッダー	processthreadsapi.h (Windows.h を含む)
Library	Kernel32.lib
[DLL]	Kernel32.dll

関連項目

GetThreadInformation

SetProcessInformation