GetLogicalProcessorInformation-Funktion (sysinfoapi.h)

  • Artikel

Ruft Informationen zu logischen Prozessoren und zugehöriger Hardware ab.

Verwenden Sie die GetLogicalProcessorInformationEx-Funktion , um Informationen zu logischen Prozessoren und zugehöriger Hardware abzurufen, einschließlich Prozessorgruppen.

Syntax

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

Parameter

[out] Buffer

Ein Zeiger auf einen Puffer, der ein Array von SYSTEM_LOGICAL_PROCESSOR_INFORMATION Strukturen empfängt. Wenn die Funktion fehlschlägt, ist der Inhalt dieses Puffers undefiniert.

[in, out] ReturnedLength

Gibt bei der Eingabe die Länge des Puffers an, auf den puffer in Bytes verweist. Wenn der Puffer groß genug ist, um alle Daten zu enthalten, ist diese Funktion erfolgreich, und ReturnLength wird auf die Anzahl der zurückgegebenen Bytes festgelegt. Wenn der Puffer nicht groß genug ist, um alle Daten zu enthalten, schlägt die Funktion fehl, GetLastError gibt ERROR_INSUFFICIENT_BUFFER zurück, und ReturnLength ist auf die Pufferlänge festgelegt, die erforderlich ist, um alle Daten zu enthalten. Wenn die Funktion mit einem anderen Fehler als ERROR_INSUFFICIENT_BUFFER fehlschlägt, ist der Wert von ReturnLength nicht definiert.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert TRUE, und mindestens eine SYSTEM_LOGICAL_PROCESSOR_INFORMATION Struktur wird in den Ausgabepuffer geschrieben.

Wenn die Funktion fehlschlägt, ist der Rückgabewert FALSE. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

GetLogicalProcessorInformation kann verwendet werden, um Informationen über die Beziehung zwischen logischen Prozessoren im System abzurufen, einschließlich:

  • Die logischen Prozessoren, die Teil eines NUMA-Knotens sind.
  • Die logischen Prozessoren, die Ressourcen gemeinsam nutzen. Ein Beispiel für diese Art der Ressourcenfreigabe wären Hyperthreadingszenarien.
Ihre Anwendung kann diese Informationen verwenden, um Ihre Threads und Prozesse zu affinitieren, um die Hardwareeigenschaften der Plattform optimal zu nutzen oder die Anzahl der logischen und physischen Prozessoren für Lizenzierungszwecke zu bestimmen.

Jede der SYSTEM_LOGICAL_PROCESSOR_INFORMATION Strukturen, die im Puffer zurückgegeben werden, enthält Folgendes:

  • Eine Affinitätsmaske für logische Prozessoren, die die logischen Prozessoren angibt, für die die Informationen in der Struktur gelten.
  • Eine logische Prozessormaske vom Typ LOGICAL_PROCESSOR_RELATIONSHIP, die die Beziehung zwischen den logischen Prozessoren in der Maske angibt. Anwendungen, die diese Funktion aufrufen, müssen vorbereitet sein, um in Zukunft zusätzliche Indikatorwerte zu verarbeiten.
Beachten Sie, dass sich die Reihenfolge, in der die Strukturen im Puffer zurückgegeben werden, zwischen aufrufen dieser Funktion ändern kann.

Die Größe der SYSTEM_LOGICAL_PROCESSOR_INFORMATION-Struktur variiert zwischen Prozessorarchitekturen und Windows-Versionen. Aus diesem Grund sollten Anwendungen zuerst diese Funktion aufrufen, um die erforderliche Puffergröße abzurufen, und dann dynamisch Arbeitsspeicher für den Puffer zuweisen.

Auf Systemen mit mehr als 64 logischen Prozessoren ruft die GetLogicalProcessorInformation-Funktion logische Prozessorinformationen zu Prozessoren in der Prozessorgruppe ab, der der aufrufende Thread derzeit zugewiesen ist. Verwenden Sie die GetLogicalProcessorInformationEx-Funktion , um Informationen zu Prozessoren in allen Prozessorgruppen des Systems abzurufen.

Hinweis

Ab TBD Release Iron wurde das Verhalten dieser und anderer NUMA-Funktionen geändert, um Systeme mit Knoten mit mehr als 64 Prozessoren besser zu unterstützen. Weitere Informationen zu dieser Änderung, einschließlich Informationen zum Aktivieren des alten Verhaltens dieser API, finden Sie unter NUMA-Unterstützung.

Verhalten ab TBD Release Iron

Die Beziehungsstrukturen für RelationNumaNode enthalten die Affinitätsmaske für die Affinität des Knotens innerhalb der Gruppe des aufrufenden Threads.

Beispiele

Im folgenden C++-Beispiel wird die GetLogicalProcessorInformation-Funktion verwendet, um Informationen zu Prozessoren auf dem aktuellen System anzuzeigen. Da GetLogicalProcessorInformation nicht auf allen Systemen vorhanden ist, wird in diesem Beispiel die GetProcAddress-Funktion verwendet, anstatt GetLogicalProcessorInformation direkt aufzurufen.

In diesem Beispiel wird die Anzahl der aktiven Prozessorkerne gemeldet. In diesem Beispiel wird auch die Anzahl von NUMA-Knoten, physischen Paketen und Caches auf Systemen gemeldet, die diese Informationen unterstützen. Weitere Informationen finden Sie in der Beschreibung des Relationship-Members der SYSTEM_LOGICAL_PROCESSOR_INFORMATION-Struktur . Windows Server 2003, Windows XP Professional x64 Edition und Windows XP mit SP3: In diesem Beispiel wird die Anzahl der physischen Prozessoren und nicht die Anzahl der aktiven Prozessorkerne gemeldet.


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

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista, Windows XP Professional x64 Edition, Windows XP mit SP3 [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile sysinfoapi.h
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

GetLogicalProcessorInformationEx

LOGICAL_PROCESSOR_RELATIONSHIP

Prozess- und Threadfunktionen

SYSTEM_LOGICAL_PROCESSOR_INFORMATION