Heaptrc/ru

heaptrc - это модуль, который можно использовать для отладки выделения и освобождения блоков памяти. Он отслеживает вызовы getMem/freeMem и, неявно, операторы new/dispose.

Не добавляйте модуль heaptrc вручную. Модуль heaptrc необходимо загрузить до lineinfo, и только компилятор может это сделать.

Heaptrc также является диспетчером памяти, поэтому не пытайтесь использовать какой-либо диспетчер памяти, включая сам heaptrc, в разделе uses, поскольку это может привести к повреждению памяти и ложным результатам.

В этом разделе содержится примечание с примером кода для универсальной обработки такого случая.

Когда программа, использующая heaptrc, завершается, heaptrc может записать общий объем используемой памяти и список выделенных, но не освобожденных блоков в файл. При запуске в консоли (*nix или Windows) heaptrc выводит эту информацию на экран, если не указано иное. В программах Lazarus с графическим интерфейсом пользователя в Windows вывод будет отображаться во множестве небольших диалоговых окон, что может быть очень непрактичным, хотя вы можете перенаправить вывод в файл.

Standard output of heaptrc on Windows (despite of the title there is no error in the application)
Standard output of heaptrc on Windows (despite of the title there is no error in the application)

В * 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:

  1. Идем в раздел Project Options/Compiler Options/Debugging (Параметры проекта/Параметры компилятора/Отладка) и
  2. в разделе 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

edit

heaptrc инкрементально проверяет кучу на записи вне границ выделенных блоков, добавляя 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