Функция HeapReAlloc (heapapi.h)
Перераспределяет блок памяти из кучи. Эта функция позволяет изменять размер блока памяти и другие свойства блока памяти. Выделенная память не перемещается.
Синтаксис
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 . Этот параметр может иметь одно или несколько из следующих значений.
| Значение | Значение |
|---|---|
|
Операционная система создает исключение, указывающее на сбой функции, например нехватку памяти, а не возвращает значение NULL.
Чтобы обеспечить создание исключений для всех вызовов этой функции, укажите HEAP_GENERATE_EXCEPTIONS в вызове HeapCreate. В этом случае не нужно дополнительно указывать HEAP_GENERATE_EXCEPTIONS в этом вызове функции. |
|
Сериализованный доступ не будет использоваться. Дополнительные сведения см. в подразделе "Примечания".
Чтобы убедиться, что сериализованный доступ отключен для всех вызовов этой функции, укажите HEAP_NO_SERIALIZE в вызове HeapCreate. В этом случае не нужно дополнительно указывать HEAP_NO_SERIALIZE в этом вызове функции. Это значение не следует указывать при доступе к куче процесса. Система может создавать дополнительные потоки в процессе приложения, такие как обработчик CTRL+C, которые одновременно обращаются к куче процесса. |
|
При перераспределении блока памяти не может быть никакого движения. Если это значение не указано, функция может переместить блок в новое расположение. Если это значение указано и размер блока невозможно изменить без перемещения, функция завершается сбоем, в результате чего исходный блок памяти остается без изменений. |
|
Если запрос на перераспределение предназначен для большего размера, дополнительная область памяти, превышающая исходный размер, инициализируется нулевым значением. Содержимое блока памяти до его исходного размера не затрагивается. |
[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 исходная память не освобождается, а исходный дескриптор и указатель остаются действительными.
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 |