Compartilhar via


Função GetLogicalProcessorInformation (sysinfoapi.h)

Recupera informações sobre processadores lógicos e hardware relacionado.

Para recuperar informações sobre processadores lógicos e hardware relacionado, incluindo grupos de processadores, use a função GetLogicalProcessorInformationEx .

Sintaxe

BOOL GetLogicalProcessorInformation(
  [out]     PSYSTEM_LOGICAL_PROCESSOR_INFORMATION Buffer,
  [in, out] PDWORD                                ReturnedLength
);

Parâmetros

[out] Buffer

Um ponteiro para um buffer que recebe uma matriz de estruturas SYSTEM_LOGICAL_PROCESSOR_INFORMATION . Se a função falhar, o conteúdo desse buffer será indefinido.

[in, out] ReturnedLength

Na entrada, especifica o comprimento do buffer apontado por Buffer, em bytes. Se o buffer for grande o suficiente para conter todos os dados, essa função terá êxito e ReturnLength será definido como o número de bytes retornados. Se o buffer não for grande o suficiente para conter todos os dados, a função falhará, GetLastError retornará ERROR_INSUFFICIENT_BUFFER e ReturnLength será definido como o comprimento do buffer necessário para conter todos os dados. Se a função falhar com um erro diferente de ERROR_INSUFFICIENT_BUFFER, o valor de ReturnLength será indefinido.

Retornar valor

Se a função for bem-sucedida, o valor retornado será TRUE e pelo menos uma estrutura SYSTEM_LOGICAL_PROCESSOR_INFORMATION será gravada no buffer de saída.

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

Comentários

GetLogicalProcessorInformation pode ser usado para obter informações sobre a relação entre processadores lógicos no sistema, incluindo:

  • Os processadores lógicos que fazem parte de um nó NUMA .
  • Os processadores lógicos que compartilham recursos. Um exemplo desse tipo de compartilhamento de recursos seria cenários de hyperthreading.
Seu aplicativo pode usar essas informações ao afinidader seus threads e processos para aproveitar melhor as propriedades de hardware da plataforma ou determinar o número de processadores lógicos e físicos para fins de licenciamento.

Cada uma das estruturas SYSTEM_LOGICAL_PROCESSOR_INFORMATION retornadas no buffer contém o seguinte:

  • Uma máscara de afinidade de processador lógico, que indica os processadores lógicos aos quais as informações na estrutura se aplicam.
  • Uma máscara de processador lógico do tipo LOGICAL_PROCESSOR_RELATIONSHIP, que indica a relação entre os processadores lógicos na máscara. Os aplicativos que chamam essa função devem estar preparados para lidar com valores de indicadores adicionais no futuro.
Observe que a ordem na qual as estruturas são retornadas no buffer pode ser alterada entre chamadas para essa função.

O tamanho da estrutura SYSTEM_LOGICAL_PROCESSOR_INFORMATION varia entre arquiteturas de processador e versões do Windows. Por esse motivo, os aplicativos devem primeiro chamar essa função para obter o tamanho do buffer necessário e, em seguida, alocar dinamicamente a memória para o buffer.

Em sistemas com mais de 64 processadores lógicos, a função GetLogicalProcessorInformation recupera informações do processador lógico sobre processadores no grupo de processadores ao qual o thread de chamada está atribuído no momento. Use a função GetLogicalProcessorInformationEx para recuperar informações sobre processadores em todos os grupos de processadores no sistema.

Observação

A partir do Ferro de Versão TBD, o comportamento dessa e de outras funções NUMA foi modificado para dar melhor suporte a sistemas com nós contendo mais de 64 processadores. Para obter mais informações sobre essa alteração, incluindo informações sobre como habilitar o comportamento antigo dessa API, consulte Suporte a NUMA.

Comportamento começando com Ferro de Liberação TBD

As estruturas de relação para RelationNumaNode contêm a máscara de afinidade para a afinidade do nó dentro do grupo do thread de chamada.

Exemplos

O exemplo C++ a seguir usa a função GetLogicalProcessorInformation para exibir informações sobre processadores no sistema atual. Como GetLogicalProcessorInformation não está presente em todos os sistemas, este exemplo usa a função GetProcAddress em vez de chamar GetLogicalProcessorInformation diretamente.

Este exemplo relata o número de núcleos de processador ativos. Este exemplo também relata o número de nós NUMA, pacotes físicos e caches em sistemas que dão suporte a essas informações. Para obter mais informações, consulte a descrição do membro Relationship da estrutura SYSTEM_LOGICAL_PROCESSOR_INFORMATION . Windows Server 2003, Windows XP Professional x64 Edition e Windows XP com SP3: Este exemplo relata o número de processadores físicos em vez do número de núcleos de processador ativos.


#include <windows.h>
#include <malloc.h>    
#include <stdio.h>
#include <tchar.h>

typedef BOOL (WINAPI *LPFN_GLPI)(
    PSYSTEM_LOGICAL_PROCESSOR_INFORMATION, 
    PDWORD);


// Helper function to count set bits in the processor mask.
DWORD CountSetBits(ULONG_PTR bitMask)
{
    DWORD LSHIFT = sizeof(ULONG_PTR)*8 - 1;
    DWORD bitSetCount = 0;
    ULONG_PTR bitTest = (ULONG_PTR)1 << LSHIFT;    
    DWORD i;
    
    for (i = 0; i <= LSHIFT; ++i)
    {
        bitSetCount += ((bitMask & bitTest)?1:0);
        bitTest/=2;
    }

    return bitSetCount;
}

int _cdecl _tmain ()
{
    LPFN_GLPI glpi;
    BOOL done = FALSE;
    PSYSTEM_LOGICAL_PROCESSOR_INFORMATION buffer = NULL;
    PSYSTEM_LOGICAL_PROCESSOR_INFORMATION ptr = NULL;
    DWORD returnLength = 0;
    DWORD logicalProcessorCount = 0;
    DWORD numaNodeCount = 0;
    DWORD processorCoreCount = 0;
    DWORD processorL1CacheCount = 0;
    DWORD processorL2CacheCount = 0;
    DWORD processorL3CacheCount = 0;
    DWORD processorPackageCount = 0;
    DWORD byteOffset = 0;
    PCACHE_DESCRIPTOR Cache;

    glpi = (LPFN_GLPI) GetProcAddress(
                            GetModuleHandle(TEXT("kernel32")),
                            "GetLogicalProcessorInformation");
    if (NULL == glpi) 
    {
        _tprintf(TEXT("\nGetLogicalProcessorInformation is not supported.\n"));
        return (1);
    }

    while (!done)
    {
        DWORD rc = glpi(buffer, &returnLength);

        if (FALSE == rc) 
        {
            if (GetLastError() == ERROR_INSUFFICIENT_BUFFER) 
            {
                if (buffer) 
                    free(buffer);

                buffer = (PSYSTEM_LOGICAL_PROCESSOR_INFORMATION)malloc(
                        returnLength);

                if (NULL == buffer) 
                {
                    _tprintf(TEXT("\nError: Allocation failure\n"));
                    return (2);
                }
            } 
            else 
            {
                _tprintf(TEXT("\nError %d\n"), GetLastError());
                return (3);
            }
        } 
        else
        {
            done = TRUE;
        }
    }

    ptr = buffer;

    while (byteOffset + sizeof(SYSTEM_LOGICAL_PROCESSOR_INFORMATION) <= returnLength) 
    {
        switch (ptr->Relationship) 
        {
        case RelationNumaNode:
            // Non-NUMA systems report a single record of this type.
            numaNodeCount++;
            break;

        case RelationProcessorCore:
            processorCoreCount++;

            // A hyperthreaded core supplies more than one logical processor.
            logicalProcessorCount += CountSetBits(ptr->ProcessorMask);
            break;

        case RelationCache:
            // Cache data is in ptr->Cache, one CACHE_DESCRIPTOR structure for each cache. 
            Cache = &ptr->Cache;
            if (Cache->Level == 1)
            {
                processorL1CacheCount++;
            }
            else if (Cache->Level == 2)
            {
                processorL2CacheCount++;
            }
            else if (Cache->Level == 3)
            {
                processorL3CacheCount++;
            }
            break;

        case RelationProcessorPackage:
            // Logical processors share a physical package.
            processorPackageCount++;
            break;

        default:
            _tprintf(TEXT("\nError: Unsupported LOGICAL_PROCESSOR_RELATIONSHIP value.\n"));
            break;
        }
        byteOffset += sizeof(SYSTEM_LOGICAL_PROCESSOR_INFORMATION);
        ptr++;
    }

    _tprintf(TEXT("\nGetLogicalProcessorInformation results:\n"));
    _tprintf(TEXT("Number of NUMA nodes: %d\n"), 
             numaNodeCount);
    _tprintf(TEXT("Number of physical processor packages: %d\n"), 
             processorPackageCount);
    _tprintf(TEXT("Number of processor cores: %d\n"), 
             processorCoreCount);
    _tprintf(TEXT("Number of logical processors: %d\n"), 
             logicalProcessorCount);
    _tprintf(TEXT("Number of processor L1/L2/L3 caches: %d/%d/%d\n"), 
             processorL1CacheCount,
             processorL2CacheCount,
             processorL3CacheCount);
    
    free(buffer);

    return 0;
}


Requisitos

Requisito Valor
Cliente mínimo com suporte Windows Vista, Windows XP Professional x64 Edition, Windows XP com SP3 [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 sysinfoapi.h
Biblioteca Kernel32.lib
DLL Kernel32.dll

Confira também

GetLogicalProcessorInformationEx

LOGICAL_PROCESSOR_RELATIONSHIP

Funções de thread e processo

SYSTEM_LOGICAL_PROCESSOR_INFORMATION