共用方式為

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)。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

為了協助改善系統效能，應用程式應該使用 SetThreadInformation 函式搭配 ThreadMemoryPriority ，以降低執行背景作業的線程記憶體優先順序，或存取預期很快就會再次存取的檔案和數據。 例如，反惡意代碼應用程式可能會降低掃描檔案相關線程的優先順序。

記憶體優先順序 有助於判斷頁面在修剪之前保留在進程 的工作集中 的時間長度。 線程的記憶體優先順序會決定該線程新增至進程工作集之實體頁面的最小優先順序。 當記憶體管理員修剪工作集時，它會在優先順序較高的頁面之前修剪較低的優先順序頁面。 這可改善整體系統效能，因為優先順序較高的頁面不太可能從工作集修剪，然後在再次存取頁面時觸發頁面錯誤。

ThreadPowerThrottling 可在線程上啟用節流原則，以在不需要最佳效能的情況下，用來平衡效能和電源效率。 當線程選擇啟用 THREAD_POWER_THROTTLING_EXECUTION_SPEED時，線程會分類為 EcoQoS。 系統會嘗試透過降低 CPU 頻率或使用更有電源效率的核心等策略來提升電源效率。 當工作不參與前景用戶體驗時，應該使用 EcoQoS，以提供較長的電池使用時間，並減少熱度和風扇雜訊。 EcQoS 不應該用於效能關鍵或前景用戶體驗。 (Windows 11 之前，Windows 11 未存在，而且程式會改為標示為 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)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

GetThreadInformation

SetProcessInformation