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

Статья
02/02/2024

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

Синтаксис

HANDLE HeapCreate(
  [in] DWORD  flOptions,
  [in] SIZE_T dwInitialSize,
  [in] SIZE_T dwMaximumSize
);

Параметры

[in] flOptions

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

Значение	Значение
HEAP_CREATE_ENABLE_EXECUTE 0x00040000	Все блоки памяти, выделенные из этой кучи, позволяют выполнять код, если оборудование обеспечивает предотвращение выполнения данных. Используйте эту кучу флагов в приложениях, выполняющих код из кучи. Если HEAP_CREATE_ENABLE_EXECUTE не указан и приложение пытается выполнить код с защищенной страницы, приложение получает исключение с кодом состояния STATUS_ACCESS_VIOLATION.
HEAP_GENERATE_EXCEPTIONS 0x00000004	Система создает исключение, указывающее на сбой (например, состояние нехватки памяти) для вызовов HeapAlloc и HeapReAlloc вместо возврата NULL.
HEAP_NO_SERIALIZE 0x00000001	Сериализованный доступ не используется, когда функции кучи обращаются к этой куче. Этот параметр применяется ко всем последующим вызовам функции кучи. Кроме того, этот параметр можно указать для отдельных вызовов функции кучи. Кучи с низким уровнем фрагментации (LFH) нельзя включить для кучи, созданной с помощью этого параметра. Кучу, созданную с помощью этого параметра, невозможно заблокировать. Дополнительные сведения о сериализованном доступе см. в разделе Примечания этого раздела.

Значение

HEAP_CREATE_ENABLE_EXECUTE
0x00040000

Все блоки памяти, выделенные из этой кучи, позволяют выполнять код, если оборудование обеспечивает предотвращение выполнения данных. Используйте эту кучу флагов в приложениях, выполняющих код из кучи. Если HEAP_CREATE_ENABLE_EXECUTE не указан и приложение пытается выполнить код с защищенной страницы, приложение получает исключение с кодом состояния STATUS_ACCESS_VIOLATION.

HEAP_GENERATE_EXCEPTIONS
0x00000004

Система создает исключение, указывающее на сбой (например, состояние нехватки памяти) для вызовов HeapAlloc и HeapReAlloc вместо возврата NULL.

HEAP_NO_SERIALIZE
0x00000001

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

Кучи с низким уровнем фрагментации (LFH) нельзя включить для кучи, созданной с помощью этого параметра.

Кучу, созданную с помощью этого параметра, невозможно заблокировать.

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

[in] dwInitialSize

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

Если этот параметр равен 0, функция фиксирует одну страницу. Чтобы определить размер страницы на главном компьютере, используйте функцию GetSystemInfo .

[in] dwMaximumSize

Максимальный размер кучи в байтах. Функция HeapCreate округляет dwMaximumSize до кратного размера системной страницы, а затем резервирует блок этого размера в виртуальном адресном пространстве процесса для кучи. Если запросы на выделение, выполняемые функциями HeapAlloc или HeapReAlloc , превышают размер, заданный dwInitialSize, система фиксирует дополнительные страницы памяти для кучи вплоть до максимального размера кучи.

Если dwMaximumSize не равен нулю, размер кучи является фиксированным и не может превышать максимальный размер. Кроме того, самый большой блок памяти, который можно выделить из кучи, составляет чуть меньше 512 КБ для 32-разрядного процесса и чуть меньше 1024 КБ для 64-разрядного процесса. Запросы на выделение больших блоков завершаются ошибкой, даже если максимальный размер кучи достаточно велик, чтобы вместить блок.

Если dwMaximumSize имеет значение 0, размер кучи может увеличиваться. Размер кучи ограничен только доступной памятью. Запросы на выделение блоков памяти, превышающих ограничение для кучи фиксированного размера, не завершаются автоматически. Вместо этого система вызывает функцию VirtualAlloc , чтобы получить память, необходимую для больших блоков. Приложения, которым необходимо выделить большие блоки памяти, должны задать dwMaximumSize значение 0.

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

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

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

Функция HeapCreate создает частный объект кучи, из которого вызывающий процесс может выделить блоки памяти с помощью функции HeapAlloc . Начальный размер определяет количество зафиксированных страниц, выделенных изначально для кучи. Максимальный размер определяет общее количество зарезервированных страниц. Эти страницы создают блок в виртуальном адресном пространстве процесса, в который может расти куча. Если запросы От HeapAlloc превышают текущий размер зафиксированных страниц, дополнительные страницы автоматически фиксируются из этого зарезервированного пространства, если доступно физическое хранилище.

Windows Server 2003 и Windows XP: По умолчанию только что созданная частная куча является стандартной кучей. Чтобы включить кучу с низкой фрагментацией, вызовите функцию HeapSetInformation с дескриптором частной кучи.

Память частного объекта кучи доступна только процессу, создав его. Если библиотека динамической компоновки (DLL) создает частную кучу, куча создается в адресном пространстве процесса, который вызывает библиотеку DLL, и она доступна только для этого процесса.

Система использует память из частной кучи для хранения структур поддержки кучи, поэтому не весь указанный размер кучи доступен для процесса. Например, если функция HeapAlloc запрашивает 64 килобайта (K) из кучи с максимальным размером 64 КБ, запрос может завершиться ошибкой из-за системных накладных расходов.

Если HEAP_NO_SERIALIZE не указан (простое значение по умолчанию), куча сериализует доступ в вызывающем процессе. Сериализация обеспечивает взаимное исключение, когда два или более потоков пытаются одновременно выделить или освободить блоки из одной кучи. Сериализация имеет небольшие затраты на производительность, но ее необходимо использовать всякий раз, когда несколько потоков выделяют и освобождают память из одной кучи. Функции HeapLock и HeapUnlock можно использовать для блокировки и разрешения доступа к сериализованной куче.

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

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

Если функции HeapLock и HeapUnlock вызываются в куче, созданной с флагом HEAP_NO_SERIALIZE , результаты не определены.

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

Примеры

Перечисление кучи

Требования


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