SetProcessInformation 函式 (processthreadsapi.h)

發行項
02/05/2024

設定指定進程的資訊。

語法

BOOL SetProcessInformation(
  [in] HANDLE                    hProcess,
  [in] PROCESS_INFORMATION_CLASS ProcessInformationClass,
       LPVOID                    ProcessInformation,
  [in] DWORD                     ProcessInformationSize
);

參數

[in] hProcess

進程的句柄。此句柄必須具有 PROCESS_SET_INFORMATION 訪問許可權。如需詳細資訊，請參閱處理安全性和訪問許可權。

[in] ProcessInformationClass

PROCESS_INFORMATION_CLASS列舉的成員，指定要設定的資訊種類。

ProcessInformation

物件的指標，其中包含 ProcessInformationClass 參數所指定的信息類型。

如果 ProcessInformationClass 參數為 ProcessMemoryPriority，此參數必須指向 MEMORY_PRIORITY_INFORMATION結構 MEMORY_PRIORITY_INFORMATION 結構。

如果 ProcessInformationClass 參數是 ProcessPowerThrottling，此參數必須指向 PROCESS_POWER_THROTTLING_STATE結構。

如果 ProcessInformationClass 參數是 ProcessLeapSecondInfo，此參數必須指向 PROCESS_LEAP_SECOND_INFO結構。

如果 ProcessInformationClass 參數是 ProcessOverrideSubsequentPrefetchParameter，此參數必須指向 OVERRIDE_PREFETCH_PARAMETER結構。

[in] ProcessInformationSize

ProcessInformation 參數所指定的結構位元組大小。

如果 ProcessInformationClass 參數是 ProcessMemoryPriority，這個參數必須是 sizeof(MEMORY_PRIORITY_INFORMATION)。

如果 ProcessInformationClass 參數是 ProcessPowerThrottling，這個參數必須是 sizeof(PROCESS_POWER_THROTTLING_STATE)。

如果 ProcessInformationClass 參數是 ProcessLeapSecondInfo，這個參數必須是 sizeof(PROCESS_LEAP_SECOND_INFO)。

傳回值

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

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

備註

為了協助改善系統效能，應用程式應該使用 SetProcessInformation 函式搭配 ProcessMemoryPriority ，降低執行背景作業的線程預設記憶體優先順序，或存取預期很快就會再次存取的檔案和數據。例如，檔案索引應用程式可能會為執行編製索引工作的進程設定較低的預設優先順序。

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

ProcessPowerThrottling 可在不需要最佳效能的情況下，啟用進程上的節流原則，可用來平衡效能和電源效率。

當行程選擇啟用 PROCESS_POWER_THROTTLING_EXECUTION_SPEED時，此程式會分類為 EcoQoS。系統會嘗試透過降低 CPU 頻率或使用更有效率的核心等策略來提升電源效率。當工作未參與前景用戶體驗時，應該使用 EcoQoS，以提供較長的電池使用時間，並減少熱度和風扇雜訊。 EcoQoS 不應用於效能關鍵或前景用戶體驗。 (Windows 11 之前，EcoQoS 層級不存在，而且程式標示為 LowQoS) 。如果應用程式未明確啟用 PROCESS_POWER_THROTTLING_EXECUTION_SPEED，則系統會使用自己的啟發學習法來自動推斷服務質量等級。如需詳細資訊，請參閱服務品質。

當進程選擇啟用 PROCESS_POWER_THROTTLING_IGNORE_TIMER_RESOLUTION時，將會忽略進程所做的任何目前定時器解析要求。屬於進程的定時器不再保證會以較高的定時器解析度到期，這可提升電源效率。明確停用 PROCESS_POWER_THROTTLING_IGNORE_TIMER_RESOLUTION之後，系統會記住並接受程式先前的任何定時器解析要求。根據預設，在 Windows 11 如果視窗擁有程式變成完全遮蔽、最小化或使用者看不到，且無法看見，Windows 可能會自動忽略定時器解析要求，因此不保證比默認系統解析度更高的解析度。

範例

下列範例示範如何使用 ProcessMemoryPriority 呼叫 SetProcessInformation，將低記憶體優先順序設定為呼叫進程的預設值。

    DWORD ErrorCode;
    BOOL Success;
    MEMORY_PRIORITY_INFORMATION MemPrio;

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

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

    Success = SetProcessInformation(GetCurrentProcess(),
                                   ProcessMemoryPriority,
                                   &MemPrio,
                                   sizeof(MemPrio));

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

下列範例示範如何使用 ProcessPowerThrottling 呼叫 SetProcessInformation，以控制進程的服務品質。

PROCESS_POWER_THROTTLING_STATE PowerThrottling;
RtlZeroMemory(&PowerThrottling, sizeof(PowerThrottling));
PowerThrottling.Version = PROCESS_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 = PROCESS_POWER_THROTTLING_EXECUTION_SPEED;
PowerThrottling.StateMask = PROCESS_POWER_THROTTLING_EXECUTION_SPEED;

SetProcessInformation(GetCurrentProcess(), 
                      ProcessPowerThrottling, 
                      &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 = PROCESS_POWER_THROTTLING_EXECUTION_SPEED;
PowerThrottling.StateMask = 0;

SetProcessInformation(GetCurrentProcess(), 
                      ProcessPowerThrottling, 
                      &PowerThrottling,
                      sizeof(PowerThrottling));

下列範例示範如何使用 ProcessPowerThrottling 呼叫 SetProcessInformation，以控制進程的定時器解析。

PROCESS_POWER_THROTTLING_STATE PowerThrottling;
RtlZeroMemory(&PowerThrottling, sizeof(PowerThrottling));
PowerThrottling.Version = PROCESS_POWER_THROTTLING_CURRENT_VERSION;

//
// Ignore Timer Resolution Requests.
// Turn IGNORE_TIMER_RESOLUTION throttling on. 
// ControlMask selects the mechanism and StateMask declares which mechanism should be on or off.
//

PowerThrottling.ControlMask = PROCESS_POWER_THROTTLING_IGNORE_TIMER_RESOLUTION;
PowerThrottling.StateMask = PROCESS_POWER_THROTTLING_IGNORE_TIMER_RESOLUTION;

SetProcessInformation(GetCurrentProcess(), 
                      ProcessPowerThrottling, 
                      &PowerThrottling,
                      sizeof(PowerThrottling));

//
// Always honor Timer Resolution Requests.
// Turn IGNORE_TIMER_RESOLUTION throttling off. 
// ControlMask selects the mechanism and StateMask is set to zero as mechanisms should be turned off.
//

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

SetProcessInformation(GetCurrentProcess(), 
                      ProcessPowerThrottling, 
                      &PowerThrottling,
                      sizeof(PowerThrottling));

下列範例示範如何使用 ProcessPowerThrottling 呼叫 SetProcessInformation，以重設為預設系統管理的行為。

PROCESS_POWER_THROTTLING_STATE PowerThrottling;
RtlZeroMemory(&PowerThrottling, sizeof(PowerThrottling));
PowerThrottling.Version = PROCESS_POWER_THROTTLING_CURRENT_VERSION;

//
// 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;

SetProcessInformation(GetCurrentProcess(), 
                      ProcessPowerThrottling, 
                      &PowerThrottling,
                      sizeof(PowerThrottling));

規格需求

需求	值
最低支援的用戶端	Windows 8 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2012 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	processthreadsapi.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll

另請參閱

GetProcessInformation 函式、 SetThreadInformation 函式、 MEMORY_PRIORITY_INFORMATION 結構、 SetProcessInformation 函式、 PROCESS_INFORMATION_CLASS列舉、 OVERRIDE_PREFETCH_PARAMETER 結構

Share via

SetProcessInformation 函式 (processthreadsapi.h)

語法

參數

傳回值

備註

範例

規格需求

另請參閱

意見反應

意見反應

其他資源