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

Статья
08/24/2023

Перечисляет блоки памяти в указанной куче.

Синтаксис

BOOL HeapWalk(
  [in]      HANDLE               hHeap,
  [in, out] LPPROCESS_HEAP_ENTRY lpEntry
);

Параметры

[in] hHeap

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

[in, out] lpEntry

Указатель на структуру PROCESS_HEAP_ENTRY , которая хранит сведения о состоянии для определенного перечисления кучи.

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

Чтобы инициировать перечисление кучи, задайте для поля lpData структуры PROCESS_HEAP_ENTRYзначение NULL. Чтобы продолжить перечисление определенной кучи, повторно вызывайте функцию HeapWalk без изменений в hHeap, lpEntry или любых членах структуры PROCESS_HEAP_ENTRY .

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

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

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

Если перечисление кучи завершается успешно, достигнув конца кучи, функция возвращает значение FALSE, а GetLastError возвращает код ошибки ERROR_NO_MORE_ITEMS.

Функция HeapWalk в первую очередь полезна для отладки, так как перечисление кучи потенциально занимает много времени. Блокировка кучи во время перечисления блокирует доступ других потоков к куче и может снизить производительность, особенно на симметричные многопроцессорные компьютеры (SMP). Побочные эффекты могут длиться до тех пор, пока куча не будет разблокирована. Используйте функции HeapLock и HeapUnlock для управления блокировкой кучи во время перечисления кучи.

Чтобы инициировать перечисление кучи, вызовите Метод HeapWalk с полем lpDataструктуры PROCESS_HEAP_ENTRY , на которую указывает lpEntry, для параметра lpEntry задано значение NULL.

Чтобы продолжить перечисление кучи, вызовите HeapWalk с теми же значениями hHeap и lpEntry , а PROCESS_HEAP_ENTRY структуру, не изменив по сравнению с предыдущим вызовом HeapWalk. Повторяйте эту процедуру, пока не потребуется дальнейшее перечисление или пока функция не вернет значение FALSE , а GetLastError не вернет ERROR_NO_MORE_ITEMS, указывая, что все блоки памяти кучи перечислены.

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

HeapWalk может завершиться ошибкой в многопоточных приложениях, если куча не заблокирована во время перечисления кучи.

Примеры

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

Требования


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