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，这样可以延长电池使用时间，减少热量和风扇噪音。 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