Функция HeapSize (heapapi.h)

Статья
02/02/2024

Извлекает размер блока памяти, выделенного из кучи функцией HeapAlloc или HeapReAlloc .

Синтаксис

SIZE_T HeapSize(
  [in] HANDLE  hHeap,
  [in] DWORD   dwFlags,
  [in] LPCVOID lpMem
);

Параметры

[in] hHeap

Дескриптор кучи, в которой находится блок памяти. Этот дескриптор возвращается функцией HeapCreate или GetProcessHeap .

[in] dwFlags

Параметры размера кучи. При указании следующего значения переопределяется соответствующее значение, указанное в параметре flOptions при создании кучи с помощью функции HeapCreate .

Значение	Значение
HEAP_NO_SERIALIZE 0x00000001	Сериализованный доступ не будет использоваться. Дополнительные сведения см. в подразделе "Примечания". Чтобы убедиться, что сериализованный доступ отключен для всех вызовов этой функции, укажите HEAP_NO_SERIALIZE в вызове HeapCreate. В этом случае необязательно дополнительно указывать HEAP_NO_SERIALIZE в вызове функции. Это значение не следует указывать при доступе к куче процесса. Система может создавать дополнительные потоки в процессе приложения, такие как обработчик CTRL+C, которые одновременно обращаются к куче процесса.

Значение

HEAP_NO_SERIALIZE
0x00000001

Сериализованный доступ не будет использоваться. Дополнительные сведения см. в подразделе "Примечания".

Чтобы убедиться, что сериализованный доступ отключен для всех вызовов этой функции, укажите HEAP_NO_SERIALIZE в вызове HeapCreate. В этом случае необязательно дополнительно указывать HEAP_NO_SERIALIZE в вызове функции.

Это значение не следует указывать при доступе к куче процесса. Система может создавать дополнительные потоки в процессе приложения, такие как обработчик CTRL+C, которые одновременно обращаются к куче процесса.

[in] lpMem

Указатель на блок памяти, размер которого будет получен функцией. Это указатель, возвращаемый функцией HeapAlloc или HeapReAlloc . Блок памяти должен находиться из кучи, заданной параметром hHeap .

Возвращаемое значение

Если функция выполняется успешно, возвращается запрошенный размер выделенного блока памяти в байтах.

Если функция завершается сбоем, возвращается (SIZE_T)-1значение . Функция не вызывает SetLastError. Приложение не может вызвать GetLastError для получения расширенных сведений об ошибке.

Если параметр lpMem ссылается на выделение кучи, которое не находится в куче, заданной параметром hHeap , поведение функции HeapSize не определено.

Сериализация обеспечивает взаимное исключение, когда два или более потоков пытаются одновременно выделить или освободить блоки из одной кучи. Сериализация имеет небольшие затраты на производительность, но ее необходимо использовать всякий раз, когда несколько потоков выделяют и освобождают память из одной кучи. Установка значения HEAP_NO_SERIALIZE исключает взаимное исключение в куче. Без сериализации два или более потоков, использующих один и тот же дескриптор кучи, могут попытаться выделить или освободить память одновременно, что может привести к повреждению кучи. Таким образом, значение HEAP_NO_SERIALIZE можно безопасно использовать только в следующих ситуациях:

Процесс содержит только один поток.
Процесс содержит несколько потоков, но только один поток вызывает функции кучи для определенной кучи.
Процесс состоит из нескольких потоков, и приложение предоставляет собственный механизм для взаимного исключения из определенной кучи.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	heapapi.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll