SetProcessInformation function

[Some information relates to pre-released product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.]

Sets information for the specified process.

Syntax

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

Parameters

hProcess

A handle to the process. This handle must have the PROCESS_SET_INFORMATION access right. For more information, see Process Security and Access Rights.

ProcessInformationClass

The class of information to set.

ProcessInformation

Pointer to an object that contains the type of information specified by the ProcessInformationClass parameter.

If the ProcessInformationClass parameter is ProcessMemoryPriority, this parameter must point to a MEMORY_PRIORITY_INFORMATION structure.

If the ProcessInformationClass parameter is ProcessPowerThrottling, this parameter must point to a PROCESS_POWER_THROTTLING_STATE structure.

If the ProcessInformationClass parameter is ProcessLeapSecondInfo, this parameter must point to a PROCESS_LEAP_SECOND_INFO structure.

ProcessInformationSize

The size in bytes of the structure specified by the ProcessInformation parameter.

If the ProcessInformationClass parameter is ProcessMemoryPriority, this parameter must be sizeof(MEMORY_PRIORITY_INFORMATION).

If the ProcessInformationClass parameter is ProcessPowerThrottling, this parameter must be sizeof(Process_POWER_THROTTLING_STATE).

If the ProcessInformationClass parameter is ProcessLeapSecondInfo, this parameter must be sizeof(PROCESS_LEAP_SECOND_INFO).

Return Value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

To help improve system performance, applications should use the SetProcessInformation function with ProcessMemoryPriority to lower the default memory priority of threads that perform background operations or access files and data that are not expected to be accessed again soon. For example, a file indexing application might set a lower default priority for the process that performs the indexing task.

Memory priority helps to determine how long pages remain in the working set of a process before they are trimmed. A process's memory priority determines the default priority of the physical pages that are added to the process working set by the threads of that process. When the memory manager trims the working set, it trims lower priority pages before higher priority pages. This improves overall system performance because higher priority pages are less likely to be trimmed from the working set and then trigger a page fault when they are accessed again.

Examples

The following example shows how to call SetProcessInformation with ProcessMemoryPriority to set low memory priority as the default for the calling process.

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

The following example shows how to call SetProcessInformation with ProcessPowerThrottling to enable throttling policies on a process.

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

//
// Turn ExecutionSpeed 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));

//
// Turn ExecutionSpeed 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));

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

Requirements

   
Minimum supported client Windows 8 [desktop apps | UWP apps]
Minimum supported server Windows Server 2012 [desktop apps | UWP apps]
Target Platform Windows
Header processthreadsapi.h (include Windows.h)
Library Kernel32.lib
DLL Kernel32.dll

See Also

GetProcessInformation

MEMORY_PRIORITY_INFORMATION

PROCESS_INFORMATION_CLASS

SetThreadInformation