GetLogicalProcessorInformation, fonction (sysinfoapi.h)

Article
08/26/2023

Récupère des informations sur les processeurs logiques et le matériel associé.

Pour récupérer des informations sur les processeurs logiques et le matériel associé, y compris les groupes de processeurs, utilisez la fonction GetLogicalProcessorInformationEx .

Syntaxe

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

Paramètres

[out] Buffer

Pointeur vers une mémoire tampon qui reçoit un tableau de structures SYSTEM_LOGICAL_PROCESSOR_INFORMATION . Si la fonction échoue, le contenu de cette mémoire tampon n’est pas défini.

[in, out] ReturnedLength

Lors de l’entrée, spécifie la longueur de la mémoire tampon pointée par Buffer, en octets. Si la mémoire tampon est suffisamment grande pour contenir toutes les données, cette fonction réussit et ReturnLength est défini sur le nombre d’octets retournés. Si la mémoire tampon n’est pas assez grande pour contenir toutes les données, la fonction échoue, GetLastError retourne ERROR_INSUFFICIENT_BUFFER et ReturnLength est défini sur la longueur de mémoire tampon requise pour contenir toutes les données. Si la fonction échoue avec une erreur autre que ERROR_INSUFFICIENT_BUFFER, la valeur de ReturnLength n’est pas définie.

Valeur retournée

Si la fonction réussit, la valeur de retour est TRUE et au moins une structure SYSTEM_LOGICAL_PROCESSOR_INFORMATION est écrite dans la mémoire tampon de sortie.

Si la fonction échoue, la valeur de retour est FALSE. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

GetLogicalProcessorInformation peut être utilisé pour obtenir des informations sur la relation entre les processeurs logiques dans le système, notamment :

Processeurs logiques qui font partie d’un nœud NUMA .
Processeurs logiques qui partagent des ressources. Un exemple de ce type de partage de ressources serait des scénarios d’hyperthreading.

Votre application peut utiliser ces informations lors de l’affinité de vos threads et processus pour tirer le meilleur parti des propriétés matérielles de la plateforme, ou pour déterminer le nombre de processeurs logiques et physiques à des fins de licence.

Chacune des structures SYSTEM_LOGICAL_PROCESSOR_INFORMATION retournées dans la mémoire tampon contient les éléments suivants :

Masque d’affinité du processeur logique, qui indique les processeurs logiques auxquels s’appliquent les informations de la structure.
Masque de processeur logique de type LOGICAL_PROCESSOR_RELATIONSHIP, qui indique la relation entre les processeurs logiques dans le masque. Les applications appelant cette fonction doivent être prêtes à gérer des valeurs d’indicateur supplémentaires à l’avenir.

Notez que l’ordre dans lequel les structures sont retournées dans la mémoire tampon peut changer entre les appels à cette fonction.

La taille de la structure SYSTEM_LOGICAL_PROCESSOR_INFORMATION varie entre les architectures de processeur et les versions de Windows. Pour cette raison, les applications doivent d’abord appeler cette fonction pour obtenir la taille de mémoire tampon requise, puis allouer dynamiquement la mémoire mémoire pour la mémoire tampon.

Sur les systèmes avec plus de 64 processeurs logiques, la fonction GetLogicalProcessorInformation récupère des informations de processeur logique sur les processeurs du groupe de processeurs auquel le thread appelant est actuellement affecté. Utilisez la fonction GetLogicalProcessorInformationEx pour récupérer des informations sur les processeurs de tous les groupes de processeurs sur le système.

Notes

À compter de TBD Release Iron, le comportement de cette fonction et d’autres fonctions NUMA a été modifié pour mieux prendre en charge les systèmes avec des nœuds contenant plus de 64 processeurs. Pour plus d’informations sur cette modification, notamment sur l’activation de l’ancien comportement de cette API, consultez Prise en charge de NUMA.

Comportement commençant par le fer à libération à déterminer

Les structures de relation pour RelationNumaNode contiennent le masque d’affinité pour l’affinité du nœud au sein du groupe du thread appelant.

Exemples

L’exemple C++ suivant utilise la fonction GetLogicalProcessorInformation pour afficher des informations sur les processeurs sur le système actuel. Étant donné que GetLogicalProcessorInformation n’est pas présent sur tous les systèmes, cet exemple utilise la fonction GetProcAddress au lieu d’appeler GetLogicalProcessorInformation directement.

Cet exemple indique le nombre de cœurs de processeur actifs. Cet exemple indique également le nombre de nœuds NUMA, de packages physiques et de caches sur les systèmes qui prennent en charge ces informations. Pour plus d’informations, consultez la description du membre Relation de la structure SYSTEM_LOGICAL_PROCESSOR_INFORMATION . Windows Server 2003, Windows XP Professionnel Édition x64 et Windows XP avec SP3 : Cet exemple indique le nombre de processeurs physiques plutôt que le nombre de cœurs de processeur actifs.


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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista, Windows XP Professionnel Édition x64, Windows XP avec SP3 [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	sysinfoapi.h
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll