heaptrc - это модуль, который можно использовать для отладки выделения и освобождения блоков памяти. Он отслеживает вызовы getMem/freeMem и, неявно, операторы new/dispose.
Не добавляйте модуль heaptrc вручную. Модуль heaptrc необходимо загрузить до lineinfo, и только компилятор может это сделать.
Heaptrc также является диспетчером памяти, поэтому не пытайтесь использовать какой-либо диспетчер памяти, включая сам heaptrc, в разделе uses, поскольку это может привести к повреждению памяти и ложным результатам.
В этом разделе содержится примечание с примером кода для универсальной обработки такого случая.
Когда программа, использующая heaptrc, завершается, heaptrc может записать общий объем используемой памяти и список выделенных, но не освобожденных блоков в файл. При запуске в консоли (*nix или Windows) heaptrc выводит эту информацию на экран, если не указано иное. В программах Lazarus с графическим интерфейсом пользователя в Windows вывод будет отображаться во множестве небольших диалоговых окон, что может быть очень непрактичным, хотя вы можете перенаправить вывод в файл.
В * nix (включая BSD, Linux и macOS) по умолчанию для программ с графическим интерфейсом ничего не отображается (прим.перев.: для вывода в консоль под *nix необходимо подключить окно в разделе View/Debug Window/Console In/Output).

См. Leakview для получения подробной информации о том, как эффективно использовать heaptrc.
Использование
editИспользование heaptrc в FPC
editДобавьте параметр -gh в командную строку компиляции или в fpc.cfg.
fpc -gh helloworld.pas
или обычно в сочетании с информацией о строке:
fpc -glh helloworld.pas
Это добавит heaptrc неявно, как скрытый первый модуль раздела uses программы.
Все примеры, приведенные на этой странице, могут быть использованы только в главном файле проекта, т.е. в файле, начинающемся с Program ..., а не Unit .... Обычно этот файл имеет расширение .lpr или .pp. Вы можете открыть его в Lazarus через меню Проект > Просмотреть исходный код проекта.
Не путайте использование {$if declared(UseHeapTrace)}} с {$if defined(UseHeapTrace)}} или {$ifdef UseHeapTrace}}. Для проверки heaptrc вам нужен первый вариант, т.к. остальные всегда будут ложными.
Вы можете проверить в коде, активен ли heaptrc, проверив глобальную константу useHeapTrace на наличие heaptrc и ее статус следующим образом:
program possiblyHeaptraced(input, output, stdErr);
begin
{$if declared(useHeapTrace)}
writeLn('Heaptrc is used.');
// отчеты heaptrc могут быть отключены при связывании в ... true или false
writeLn('Heaptrc is active: ', useHeaptrace);
// впоследствии вы можете протестировать/задать любые параметры отчетов heaptrc
{$else}
writeLn('No trace of heaptrc.');
{$endIf}
end.
Обратите внимание, что {$if declared(useHeapTrace)} работает только в программе, а не в модуле.
Heaptrc не работает, если вы используете его с FPC 3.0.4 в Linux и ваша программа вызывает функцию system.get_cmdline, и в этом случае вы получите в конце программы много сообщений об ошибках EAccessViolation. Это похоже на ошибку, например в FPC 3.2.0-beta rev 43824 эта проблема не возникает.
Использование heaptrc в Lazarus
editЧтобы включить это в вашем проекте Lazarus:
- Идем в раздел Project Options/Compiler Options/Debugging (Параметры проекта/Параметры компилятора/Отладка) и
- в разделе Other debugging info (Прочая отладочная информация) включаем Use Heaptrc unit (check for mem-leaks) (-gh) (Использовать модуль Heaptrc (проверка на наличие утечек памяти) (-gh))
Вы можете проверить наличие heaptrc таким же образом, как в приведенном выше примере, проверив наличие useHeapTrace в вашем файле project.lpr.
{$if declared(useHeapTrace)}
// ... что-то делаем
// проверяем активность
if useHeapTrace then
begin
// ...
end;
{$endIf}
Показывать отчет только об утечке
editЕсли вы хотите отображать диалоговое окно отчета heaptrc только в том случае, если в вашем приложении были утечки, поместите это присвоение где-нибудь в исходный файл основного проекта:
{$if declared(useHeapTrace)}
globalSkipIfNoLeaks := true; // поддерживается начиная с версии отладчика 3.2.0
{$endIf}
Программное отключение отчета
editЕсли вы хотите отключить отчет из своего кода, вы можете напрямую управлять константой useHeapTrace при запуске программы:
useHeapTrace := false;
Это фактически изменит поведение на нормальный менеджер памяти.
Продолжать выполнение даже при ошибке кучи
editЕсли вы хотите, чтобы ваше приложение продолжало выполнение даже в случае ошибки кучи, манипулируйте константой haltOnError constant при запуске программы:
haltOnError := false;
Перенаправление вывода в файл
editЕсли вы хотите перенаправить отчет об утечке в файл, добавьте его в начало основного файла проекта:
setHeapTraceOutput('trace.log'); // поддерживается начиная с версии отладчика 3.2.0
Почему heaptrc не следует добавлять в раздел uses вручную
editНикогда не следует добавлять heaptrc вручную в обычную программу, потому что модуль heaptrc должен быть загружен до lineinfo для правильной работы отладки.
Для эффективного декодирования отладочной информации dwarf требуется работающий менеджер кучи, а это означает, что heaptrc необходимо загрузить до модуля декодирования dwarf line info, который загружается с помощью -gl, поэтому heaptrc не может использоваться явно.
Только сам компилятор может вставить модуль в нужное место в качестве скрытого первого модуля в разделе uses. Добавление модуля вручную может вызвать всевозможные нежелательные побочные эффекты. Например, информациях о сбоях, сообщаемая lineinfo, не является надежной, и не обо всех утечках сообщения будут достоверны.
Так было всегда, но правильно задокументировано только в FPC версии 3.0.2. Так что, если вы увидите heaptrc в своем разделе uses, удалите его! для правильной работы отладки и отчетов.
Если ваша программа предназначена для использования альтернативного менеджера памяти, вы можете адаптировать раздел uses вашей программы следующим образом:
program alternativeMemoryManager(input, output, stdErr);
{$mode objFPC}
uses
// Это условно переключит диспетчер памяти
// на основе наличия heaptrc
{$if not declared(useHeapTrace)}
cMem,
{$endIf}
sysUtils, classes; // два последних предназначены для тестирования.
begin
{$if declared(useHeapTrace)}
writeLn('Heaptrc is used.', ' Heaptrc is active: ', useHeaptrace);
{$else}
writeLn('No trace of heaptrc.');
{$endIf}
end.
В приведенном выше примере условное выражение в разделе uses гарантирует, что диспетчер памяти cmem компилируется только в том случае, если параметр heaptrc не используется.
Экспериментальные возможности 3.3.1
editВ разрабатываемой версии 3.3.1 heaptrc был переработан и обзавёлся некоторыми новыми возможностями. Почитать подробнее можно здесь: MR !1278 💀 REWRITE HEAPTRC.PP 💀.
AutoCheckHeapStep & CheckHeap
editheaptrc инкрементально проверяет кучу на записи вне границ выделенных блоков, добавляя head_size-байтовые головы (по умолчанию: 0) и tail_size-байтовые хвосты (по умолчанию: 4) ко всем блокам и проверяя до AutoCheckHeapStep (по умолчанию: 3) блоков при каждой операции (GetMem, FreeMem, ReallocMem, MemSize). Увеличьте AutoCheckHeapStep, чтобы сделать этот процесс агрессивнее, или установите в 0, чтобы выключить. Аллокации всё равно будут проверяться в момент своего освобождения / перевыделения, но это с большей вероятностью окажется слишком поздно.
CheckHeap([step]) также можно вызвать вручную; step по умолчанию равен High(SizeUint), что означает проверку всей кучи.
Если вы наблюдаете переполнение буфера, но не можете найти виновника, попробуйте локализовать его двоичным поиском с помощью CheckHeap: если код
CheckHeap;
P[5] := 25;
работает, а код
P[5] := 25;
CheckHeap;
— нет, то P[5] := 25; было записью за конец P.
Также, если вы получаете ошибку сегментации при доступе по указателю P, предварительное выполнение CheckPointer(P) может дать больше информации на этот счёт, особенно в связке с KeepReleased*. Однако учтите, что CheckHeap(High(SizeUint)) и CheckPointer крайне медленные, т. к. сканируют всю кучу, поэтому не разбрасывайтесь ими.
KeepReleasedBytes & KeepReleasedPercents
editУдерживание освобождённой памяти позволяет heaptrc обнаруживать записи-после-освобождения и сообщать больше информации в случае двойных освобождений или CheckPointer, указывающего в освобождённую память. Например,
var
p: pointer;
begin
p := GetMem(100);
FreeMem(p);
FreeMem(p); // или CheckPointer(p + 10);
end.
может сообщить только:
pointer <...> does not point to valid memory block
тогда как
var
p: pointer;
begin
KeepReleased := true;
p := GetMem(100);
FreeMem(p);
FreeMem(p); // или CheckPointer(p + 10);
end.
способен указать конкретнее:
pointer <...> (size 100) was freed at
$main, line 6
and touched again at
$main, line 7
Однако, KeepReleased := true; удерживает всю освобождённую память, что не всегда практично или вообще возможно.
В качестве компромисса, вы можете предпочесть удерживание до KeepReleasedBytes + KeepReleasedPercents%.
От чего именно отсчитываются проценты, не уточняется :D, но на данный момент это проценты от максимального количества использованной приложением памяти.
Заметьте, что KeepReleased := true; — это просто (и технически) эквивалент для KeepReleasedBytes := High(SizeUint);.
Их также можно задать параметром KeepReleased переменной окружения HEAPTRC, со следующим синтаксисом:
HEAPTRC=KeepReleased,...— соответствуетKeepReleased := true;HEAPTRC=KeepReleased=10%+100k,...— соответствуетKeepReleasedPercents := 10; KeepReleasedBytes := 100 * 1024;
Суффиксы:10(без суффикса) — десять байт,10k— десять килобайт,10m— десять мегабайт,10g— десять гигабайт,10%или10pc(если вы используете Windows и боитесь эскейпать%) — десять процентов.
Поддерживается произвольное число слагаемых, но не какая-либо другая математика (это не парсер выражений).
TraceDepth
editГлобальное свойство TraceDepth управляет максимальной глубиной стектрейсов. Значение по умолчанию — 16, предел — 64. Установка в 0 улучшает производительность; 999 (как простой способ написать 64) выдаёт лучшие стректрейсы.
Может быть установлено из окружения: HEAPTRC=TraceDepth=999,....
WalkHeap
editФункция WalkHeap похожа на WalkAllocatedBlocks из FastMM4 и подобные: она обходит все блоки, выделенные через heaptrc. Например, этот код строит гистограмму аллокаций:
{$modeswitch anonymousfunctions}
uses
heaptrc;
var
histogram: array[0 .. 127] of record count, size: SizeUint; end;
i: SizeInt;
begin
GetMem(100);
GetMem(200);
GetMem(300);
GetMem(3000);
FillChar(histogram, sizeof(histogram), 0);
WalkHeap(
procedure {WalkBlock}(const bi: TWalkBlockInfo; param: pointer)
var
hi: SizeUint;
begin
if bi.isInternalHeaptrcAllocation then exit;
hi := bi.size div 16;
if hi > High(histogram) then hi := High(histogram);
inc(histogram[hi].count);
inc(histogram[hi].size, bi.size);
end, nil);
writeln('Количества живых аллокаций по размерам:');
for i := 0 to High(histogram) do
if histogram[i].count <> 0 then
begin
if i < High(histogram) then
write(16 * i:4, ' ~ ', 16 * i + 15:4)
else
write(16 * i:4, ' ~ ', '+Inf':4);
writeln(': ', histogram[i].count, ' (', histogram[i].size, ' байт суммарно).');
end;
end.
Вы можете выделять память внутри коллбэка. Делать этого не рекомендуется, а трогание аллокаций, сделанных до вызова WalkHeap, может привести к непредсказуемым результатам (если вы освободите блок, который обходится в данный момент), но аллокации коллбэками с нуля полностью безопасны (всё равно не злоупотребляйте этой возможностью).
См.также
edit- https://bugs.freepascal.org/view.php?id=30637
- leakview: Примеры включения heaptrc в Lazarus и Free Pascal.
- RTL Reference for unit 'heaptrc' (эта ссылка еще не обновлена)