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

Статья
02/02/2024

Перераспределяет блок памяти из кучи. Эта функция позволяет изменять размер блока памяти и другие свойства блока памяти. Выделенная память не перемещается.

Синтаксис

DECLSPEC_ALLOCATOR LPVOID HeapReAlloc(
  [in] HANDLE                 hHeap,
  [in] DWORD                  dwFlags,
  [in] _Frees_ptr_opt_ LPVOID lpMem,
  [in] SIZE_T                 dwBytes
);

Параметры

[in] hHeap

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

[in] dwFlags

Параметры перераспределения кучи. При указании значения переопределяется соответствующее значение, указанное в параметре flOptions при создании кучи с помощью функции 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_REALLOC_IN_PLACE_ONLY 0x00000010	При перераспределении блока памяти не может быть никакого движения. Если это значение не указано, функция может переместить блок в новое расположение. Если это значение указано и размер блока невозможно изменить без перемещения, функция завершается сбоем, в результате чего исходный блок памяти остается без изменений.
HEAP_ZERO_MEMORY 0x00000008	Если запрос на перераспределение предназначен для большего размера, дополнительная область памяти, превышающая исходный размер, инициализируется нулевым значением. Содержимое блока памяти до его исходного размера не затрагивается.

[in] lpMem

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

[in] dwBytes

Новый размер блока памяти в байтах. Размер блока памяти можно увеличить или уменьшить с помощью этой функции.

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

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

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

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

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

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

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

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

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

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

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

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

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

Требования

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

См. также

Функции кучи

HeapAlloc

HeapFree

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

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