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 结构的关系成员的说明。 Windows Server 2003、Windows XP Professional x64 Edition 和带有 SP3 的 Windows XP： 此示例报告物理处理器数，而不是活动处理器核心数。


#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、带 SP3 的 Windows XP [桌面应用 \|UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	sysinfoapi.h
Library	Kernel32.lib
DLL	Kernel32.dll