Função SetThreadAffinityMask (winbase.h)

Artigo
08/27/2023

Define uma máscara de afinidade de processador para o thread especificado.

Sintaxe

DWORD_PTR SetThreadAffinityMask(
  [in] HANDLE    hThread,
  [in] DWORD_PTR dwThreadAffinityMask
);

Parâmetros

[in] hThread

Um identificador para o thread cuja máscara de afinidade deve ser definida.

Esse identificador deve ter o direito de acesso THREAD_SET_INFORMATION ou THREAD_SET_LIMITED_INFORMATION e o direito de acesso THREAD_QUERY_INFORMATION ou THREAD_QUERY_LIMITED_INFORMATION . Para obter mais informações, consulte Segurança de thread e direitos de acesso.

Windows Server 2003 e Windows XP: O identificador deve ter os direitos de acesso THREAD_SET_INFORMATION e THREAD_QUERY_INFORMATION .

[in] dwThreadAffinityMask

A máscara de afinidade para o thread.

Em um sistema com mais de 64 processadores, a máscara de afinidade deve especificar processadores no grupo de processadores atual do thread.

Retornar valor

Se a função for bem-sucedida, o valor retornado será a máscara de afinidade anterior do thread.

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

Se a máscara de afinidade de thread solicitar um processador que não esteja selecionado para a máscara de afinidade de processo, o último código de erro será ERROR_INVALID_PARAMETER.

Comentários

Uma máscara de afinidade de thread é um vetor de bits no qual cada bit representa um processador lógico no qual um thread tem permissão para ser executado. Uma máscara de afinidade de thread deve ser um subconjunto da máscara de afinidade de processo para o processo de contenção de um thread. Um thread só pode ser executado nos processadores em que seu processo pode ser executado. Portanto, a máscara de afinidade de thread não pode especificar um 1 bit para um processador quando a máscara de afinidade de processo especifica um 0 bit para esse processador.

Definir uma máscara de afinidade para um processo ou thread pode resultar em threads recebendo menos tempo de processador, pois o sistema está impedido de executar os threads em determinados processadores. Na maioria dos casos, é melhor permitir que o sistema selecione um processador disponível.

Se a nova máscara de afinidade de thread não especificar o processador que está executando o thread no momento, o thread será reagendado em um dos processadores permitidos.

A partir do Windows 11 e do Windows Server 2022, em um sistema com mais de 64 processadores, afinidades de processo e thread abrangem todos os processadores no sistema, em todos os grupos de processadores, por padrão. O dwThreadAffinityMask deve especificar processadores no grupo primário atual do thread.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winbase.h (incluir Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll