Função SetThreadInformation (processthreadsapi.h)

Define informações para o thread especificado.

Sintaxe

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

Parâmetros

[in] hThread

Um identificador para o thread. O identificador deve ter THREAD_SET_INFORMATION acesso correto. Para obter mais informações, consulte Segurança de thread e direitos de acesso.

[in] ThreadInformationClass

A classe de informações a ser definida. Os únicos valores com suporte são ThreadMemoryPriority e ThreadPowerThrottling.

ThreadInformation

Ponteiro para uma estrutura que contém o tipo de informação especificado pelo parâmetro ThreadInformationClass .

Se o parâmetro ThreadInformationClass for ThreadMemoryPriority, esse parâmetro deverá apontar para uma estrutura MEMORY_PRIORITY_INFORMATION .

Se o parâmetro ThreadInformationClass for ThreadPowerThrottling, esse parâmetro deverá apontar para uma estrutura THREAD_POWER_THROTTLING_STATE .

[in] ThreadInformationSize

O tamanho em bytes da estrutura especificada pelo parâmetro ThreadInformation .

Se o parâmetro ThreadInformationClass for ThreadMemoryPriority, esse parâmetro deverá ser sizeof(MEMORY_PRIORITY_INFORMATION).

Se o parâmetro ThreadInformationClass for ThreadPowerThrottling, esse parâmetro deverá ser sizeof(THREAD_POWER_THROTTLING_STATE).

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Para ajudar a melhorar o desempenho do sistema, os aplicativos devem usar a função SetThreadInformation com ThreadMemoryPriority para reduzir a prioridade de memória dos threads que executam operações em segundo plano ou acessam arquivos e dados que não devem ser acessados novamente em breve. Por exemplo, um aplicativo antimalware pode reduzir a prioridade dos threads envolvidos na verificação de arquivos.

A prioridade de memória ajuda a determinar por quanto tempo as páginas permanecem no conjunto de trabalho de um processo antes de serem cortadas. A prioridade de memória de um thread determina a prioridade mínima das páginas físicas adicionadas ao processo de trabalho definido por esse thread. Quando o gerenciador de memória corta o conjunto de trabalho, ele corta páginas de prioridade mais baixas antes das páginas de prioridade mais alta. Isso melhora o desempenho geral do sistema porque as páginas de prioridade mais alta são menos propensas a serem cortadas do conjunto de trabalho e, em seguida, disparam uma falha de página quando são acessadas novamente.

O ThreadPowerThrottling permite políticas de limitação em um thread, que podem ser usadas para equilibrar o desempenho e a eficiência de energia em casos em que o desempenho ideal não é necessário. Quando um thread optar por habilitar THREAD_POWER_THROTTLING_EXECUTION_SPEED, o thread será classificado como EcoQoS. O sistema tentará aumentar a eficiência de energia por meio de estratégias como reduzir a frequência da CPU ou usar núcleos mais eficientes em termos de energia. O EcoQoS deve ser usado quando o trabalho não está contribuindo para a experiência do usuário em primeiro plano, que fornece maior duração da bateria e redução do calor e do ruído do ventilador. O EcoQoS não deve ser usado para experiências de usuário críticas ou em primeiro plano de desempenho. (Antes de Windows 11, o nível do EcoQoS não existia e o processo era rotulado como LowQoS). Se um aplicativo não habilitar THREAD_POWER_THROTTLING_EXECUTION_SPEEDexplicitamente , o sistema usará sua própria heurística para inferir automaticamente um nível de Qualidade de Serviço. Para obter mais informações, consulte Qualidade de Serviço.

Exemplos

O exemplo a seguir mostra como chamar SetThreadInformation com ThreadMemoryPriority para definir a baixa prioridade de memória no thread atual.

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

O exemplo a seguir mostra como chamar SetThreadInformation com ThreadPowerThrottling para controlar a Qualidade do Serviço de um thread.

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

Requisitos

Confira também

GetThreadInformation

SetProcessInformation