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

Статья
02/02/2024

Выделяет блок памяти из кучи. Выделенная память не перемещается.

Синтаксис

DECLSPEC_ALLOCATOR LPVOID HeapAlloc(
  [in] HANDLE hHeap,
  [in] DWORD  dwFlags,
  [in] SIZE_T dwBytes
);

Параметры

[in] hHeap

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

[in] dwFlags

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

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

Значение

HEAP_GENERATE_EXCEPTIONS
0x00000004

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

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

HEAP_NO_SERIALIZE
0x00000001

Сериализованный доступ не будет использоваться для этого выделения.

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

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

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

HEAP_ZERO_MEMORY
0x00000008

Выделенная память будет инициализирована нулевым значением. В противном случае память не инициализируется до нуля.

[in] dwBytes

Число выделенных байтов.

Если куча, указанная параметром hHeap , является "нерасвертываемой" кучей, значение dwBytes должно быть меньше 0x7FFF8. Чтобы создать нерастущую кучу, вызовите функцию HeapCreate с ненулевым значением.

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

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

Если функция завершается сбоем и вы не указали HEAP_GENERATE_EXCEPTIONS, возвращаемое значение равно NULL.

Если функция завершается сбоем и вы указали HEAP_GENERATE_EXCEPTIONS, функция может создать любое из исключений, перечисленных в следующей таблице. Конкретное исключение зависит от характера повреждения кучи. Дополнительные сведения см. в разделе GetExceptionCode.

Код исключения	Описание
STATUS_NO_MEMORY	Попытка выделения не удалась из-за нехватки доступной памяти или повреждения кучи.
STATUS_ACCESS_VIOLATION	Попытка выделения не удалась из-за повреждения кучи или неправильных параметров функции.

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

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

Выравнивание памяти, возвращаемой HeapAlloc, MEMORY_ALLOCATION_ALIGNMENT в WinNT.h:

#if defined(_WIN64) || defined(_M_ALPHA)
#define MEMORY_ALLOCATION_ALIGNMENT 16
#else
#define MEMORY_ALLOCATION_ALIGNMENT 8
#endif

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

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

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

Примеры

Пример см. в разделе Пример AWE.

Требования

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