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

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

Синтаксис

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

Параметры

[in] hHeap

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

[in] dwFlags

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

[in] dwBytes

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

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

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

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

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

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

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

Комментарии

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

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

Чтобы освободить блок памяти, выделенный HeapAlloc, используйте функцию HeapFree .

Память, выделенная 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.

Требования

См. также

Функции кучи

КучаFree

HeapReAlloc

Функции управления памятью

API-интерфейсы Vertdll, доступные в анклавах VBS