GetLogicalProcessorInformation 函式 (sysinfoapi.h)

發行項
03/02/2024

擷取邏輯處理器和相關硬體的相關信息。

若要擷取邏輯處理器和相關硬體的相關信息，包括處理器群組，請使用 GetLogicalProcessorInformationEx 函式。

語法

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

參數

[out] Buffer

接收 SYSTEM_LOGICAL_PROCESSOR_INFORMATION 結構陣列之緩衝區的指標。如果函式失敗，則未定義此緩衝區的內容。

[in, out] ReturnedLength

在輸入時，以位元組為單位指定 Buffer 所指向的緩衝區長度。如果緩衝區夠大，足以包含所有數據，則此函式會成功， 而 ReturnLength 會設定為傳回的位元組數目。如果緩衝區不足以包含所有數據，則函式會失敗， GetLastError 會傳回ERROR_INSUFFICIENT_BUFFER，而 ReturnLength 會設定為包含所有數據所需的緩衝區長度。如果函式失敗，並出現ERROR_INSUFFICIENT_BUFFER以外的錯誤， 則 ReturnLength 的值是未定義的。

傳回值

如果函式成功，則傳回值為TRUE，且至少將一個SYSTEM_LOGICAL_PROCESSOR_INFORMATION 結構寫入輸出緩衝區。

如果函式失敗，傳回值為 FALSE。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

GetLogicalProcessorInformation 可用來取得系統中邏輯處理器之間關聯性的相關信息，包括：

屬於 NUMA 節點一部分的邏輯處理器。
共用資源的邏輯處理器。這種類型的資源分享範例是超線程案例。

您的應用程式可以在將線程和進程親和化時使用這項資訊，以充分利用平臺的硬體屬性，或判斷用於授權用途的邏輯和實體處理器數目。

緩衝區中傳回的每個 SYSTEM_LOGICAL_PROCESSOR_INFORMATION 結構都包含下列各項：

邏輯處理器親和性遮罩，表示結構中資訊所套用的邏輯處理器。
類型為 LOGICAL_PROCESSOR_RELATIONSHIP 的邏輯處理器遮罩，表示遮罩中邏輯處理器之間的關聯性。呼叫此函式的應用程式必須準備好在未來處理其他指標值。

請注意，緩衝區中傳回結構的順序可能會在呼叫此函式之間變更。

SYSTEM_LOGICAL_PROCESSOR_INFORMATION結構的大小會因處理器架構和 Windows 版本而異。因此，應用程式應該先呼叫此函式以取得所需的緩衝區大小，然後動態配置緩衝區的記憶體。

在具有超過 64 個邏輯處理器的系統上， GetLogicalProcessorInformation 函式會擷取目前指派呼叫線程之處理器群組中處理器的邏輯處理器資訊。使用 GetLogicalProcessorInformationEx 函式來擷取系統上所有處理器群組中處理器的相關信息。

注意

從 TBD Release Iron 開始，已修改此和其他 NUMA 函式的行為，以更妥善地支援包含更多 64 個處理器節點的系統。如需這項變更的詳細資訊，包括啟用此 API 舊行為的相關信息，請參閱 NUMA 支援。

從 TBD Release Iron 開始的行為

RelationNumaNode 的關聯性結構包含呼叫線程群組內節點親和性的親和性遮罩。

範例

下列 C++ 範例會使用 GetLogicalProcessorInformation 函式 來顯示目前系統上處理器的相關信息。由於 GetLogicalProcessorInformation 不存在於所有系統上，因此此範例會使用 GetProcAddress 函式，而不是直接呼叫 GetLogicalProcessorInformation 。

此範例會報告使用中處理器核心的數目。此範例也會報告支援這項資訊的系統上 NUMA 節點、實體套件和快取的數目。如需詳細資訊，請參閱 SYSTEM_LOGICAL_PROCESSOR_INFORMATION 結構的 Relationship 成員描述。 Windows Server 2003、Windows XP Professional x64 Edition 和 Windows XP with SP3： 此範例會報告實體處理器數目，而不是使用中處理器核心的數目。


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

規格需求

需求	值
最低支援的用戶端	Windows Vista、Windows XP Professional x64 Edition、Windows XP with SP3 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	sysinfoapi.h
程式庫	Kernel32.lib
DLL	Kernel32.dll