Artigo Técnico

HotPDF: encontre consumidores de memória em PDFs

Para um relatório de 400 páginas que incorpora uma única fonte de 2 MB, cobrar de cada página tudo o que ela referencia produz um total estranho: as páginas somam 800 MB de fonte em um arquivo que pode ter 30 MB em disco. Divida a fonte igualmente entre elas e cada página custa cerca de 5 KB, assim nada parece caro e a memória parece surgir do nada. Nenhum dos dois números responde à pergunta real, que é quantos bytes seriam liberados se um determinado objeto fosse removido

Esse número tem nome na análise de heap — tamanho retido — e a teoria dos grafos tem uma forma limpa de calculá-lo. Um objeto é cobrado ao seu dominador, o objeto mais próximo pelo qual todo caminho a partir da raiz precisa passar para chegar até ele. Objetos compartilhados sobem na hierarquia até chegar a um nó que realmente os domina, os exclusivos ficam onde estão, e os totais se somam sem contagem dupla

Tamanho raso, tamanho retido e a regra do dominador no HotPDF

O HotPDF calcula isso para um documento carregado por meio de THotPDF.BuildLoadedObjectDependencyGraph. A chamada retorna um THPDFObjectDependencyNode por objeto indireto carregado e um THPDFObjectDependencyEdge por referência indireta, e então executa uma análise de dominadores enraizada no Catalog do documento, o objeto apontado pela entrada /Root do trailer (ISO 32000-1 §7.7.2). Cada nó carrega dois tamanhos. EstimatedShallowBytes é o que o objeto custa por si só. EstimatedRetainedBytes é o próprio custo mais o custo raso de todos os objetos que ele domina

Voltando à fonte. Toda página a referencia, então nenhuma página sozinha a domina; os caminhos só convergem no nó da árvore de páginas acima delas, que em uma árvore plana é o objeto raiz /Pages. Os 2 MB da fonte ficam ali e depois sobem para o Catalog. Um XObject de imagem desenhado apenas na página 12 é o caso oposto: todo caminho até ele passa pela página 12, então o tamanho retido da página 12 inclui a imagem inteira. O topo da lista de retidos é, portanto, uma lista de objetos cuja remoção liberaria memória

HotPDF: grafo de dependências em que um dominador atribui bytes retidos: um image XObject mantido por uma página cobra dessa página, enquanto uma fonte compartilhada por todas as páginas cobra do Catalog
Pela regra do dominador, um XObject de imagem mantido vivo por uma única página é cobrado dessa página, enquanto uma fonte referenciada por todas as páginas se acumula no Catalog — os totais retidos, portanto, somam sem contagem dupla

A mesma aritmética entrega uma verificação cruzada de graça. THPDFObjectDependencyGraphInfo.CatalogRetainedBytes é igual à soma dos tamanhos rasos de todos os objetos alcançáveis a partir do Catalog, e TotalEstimatedBytes é a soma dos tamanhos rasos de todos os objetos carregados, alcançáveis ou não. A diferença entre os dois é a memória retida por objetos que o documento não referencia mais

Executando o grafo e interpretando um resultado fracassado

O método retorna True apenas quando a análise inteira terminou, e esse valor de retorno é o que você precisa checar. Um resultado False ainda preenche o record de informações, mas os arrays não são algo para relatar. Quando a contagem de objetos excede MaxObjects (padrão de 250.000), o método para antes de construir qualquer nó e define ObjectCount como um valor a mais que o limite, então você descobre que o limite era pequeno demais, não quão grande o documento é. Quando o orçamento de arestas (padrão de 2.000.000) ou o limite de aninhamento de 256 níveis para objetos diretos é atingido durante a varredura, os nós voltam com tamanhos rasos parciais e sem tamanhos retidos ou alcançabilidade alguma

uses
  SysUtils, HPDFDoc;

procedure ProfileLoadedPdf(const FileName: string);
var
  Pdf: THotPDF;
  Nodes: THPDFObjectDependencyNodeArray;
  Edges: THPDFObjectDependencyEdgeArray;
  Info: THPDFObjectDependencyGraphInfo;
begin
  Pdf := THotPDF.Create(nil);
  try
    // LoadFromFile retorna a contagem de páginas; 0 significa que o carregamento falhou
    if Pdf.LoadFromFile(FileName) = 0 then
      Exit;

    // Limites elevados para uma execução forense offline
    if not Pdf.BuildLoadedObjectDependencyGraph(Nodes, Edges, Info,
      1000000, 8000000) then
    begin
      // Log é a sua própria rotina de logging
      Log(Format('graph incomplete: %s (limit %s, invalid %s, objects %d)',
        [string(Info.Diagnostic), BoolToStr(Info.LimitExceeded, True),
         BoolToStr(Info.InvalidObjectGraph, True), Info.ObjectCount]));
      Exit; // não ranqueie nem some um array de nós parcial
    end;

    Log(Format('%d objects, %d edges (%d unresolved), %d reachable',
      [Info.ObjectCount, Info.EdgeCount, Info.UnresolvedReferenceCount,
       Info.ReachableObjectCount]));
    Log(Format('estimated %d bytes, Catalog retains %d, unreachable %d',
      [Info.TotalEstimatedBytes, Info.CatalogRetainedBytes,
       Info.TotalEstimatedBytes - Info.CatalogRetainedBytes]));

    LogTopRetained(Nodes, Edges, 10);
  finally
    Pdf.Free;
  end;
end;

Dois outros flags merecem uma olhada nesse ramo de falha. InvalidObjectGraph é definido quando o objeto Catalog não pode ser encontrado entre os objetos carregados, ou quando um objeto direto acaba contendo a si mesmo, o que só acontece em entradas malformadas. LimitExceeded também cobre uma análise de dominadores que não convergiu após 128 passadas. Diagnostic explica cada caso em uma linha. Passar zero ou um valor negativo para MaxObjects, ou um MaxEdges negativo, levanta EArgumentOutOfRangeException em vez de retornar False

Quando a chamada falha por um limite, descarte os arrays e execute-a novamente com limites maiores. Tamanhos rasos parciais parecem plausíveis em um log e estão errados exatamente da forma que manda as pessoas atrás do objeto errado. Os limites existem porque o grafo tem um custo próprio: cada aresta armazena uma string Path, então uma execução com oito milhões de arestas aloca oito milhões de strings pequenas por cima do documento que ela está medindo. Isso pertence a um caminho de diagnóstico que alguém dispara de propósito

O que o EstimatedShallowBytes realmente contabiliza?

EstimatedShallowBytes estima memória residente, não bytes no arquivo. Para cada objeto ele soma o tamanho de instância do objeto analisado e de seus filhos diretos, os slots mantidos pelas listas de dicionário e array, o comprimento de cada chave, nome e string, e o payload de um stream se esse payload estiver na RAM: um memory stream, ou um stream carregado sob demanda que já foi lido para a memória. Um stream cujos bytes ainda estão no arquivo de origem, ou que foi descarregado para um arquivo temporário, contribui apenas com sua sobrecarga de objeto

Isso tem uma consequência prática. Um arquivo pesado em digitalizações analisado logo após o carregamento pode mostrar tamanhos retidos modestos para suas imagens, porque nada as decodificou ainda. Execute o grafo depois do passo que fez o processo crescer (renderização, extração de texto, uma mesclagem) e os streams materializados aparecem com seu peso real. Para uma checagem reprodutível, analise o mesmo arquivo duas vezes, uma logo após LoadFromFile e outra depois da operação cara, e compare as entradas do topo

ObjectType é grosseiro. Ele reporta o tipo de valor PDF, otStream ou otDictionary e assim por diante, então uma imagem, um programa de fonte e um content stream de página aparecem todos como otStream. A aresta de entrada é onde o papel aparece. THPDFObjectDependencyEdge.Path registra onde no objeto de origem a referência foi encontrada, começando com $, com /Key para entradas de dicionário, [n] para itens de array e /dictionary para o dicionário de um stream. Um caminho $/Resources/XObject/Im3 vindo de uma página, ou $/XObject/Im3 vindo de um dicionário de recursos separado, significa que o objeto é usado como um XObject chamado Im3; $/FontFile2 vindo de um descritor de fonte significa um programa TrueType incorporado; $/Contents[0] significa conteúdo de página

// Helper seu, não faz parte da biblioteca: ranqueia os top Count nós por
// tamanho retido e imprime o caminho de uma referência de entrada para cada
procedure LogTopRetained(const Nodes: THPDFObjectDependencyNodeArray;
  const Edges: THPDFObjectDependencyEdgeArray; Count: Integer);
var
  Taken: array of Boolean;
  I, J, Best: Integer;
  Via: AnsiString;
begin
  SetLength(Taken, Length(Nodes));
  for I := 1 to Count do
  begin
    Best := -1;
    for J := 0 to High(Nodes) do
      if (not Taken[J]) and ((Best < 0) or
         (Nodes[J].EstimatedRetainedBytes >
          Nodes[Best].EstimatedRetainedBytes)) then
        Best := J;
    if Best < 0 then
      Break;
    Taken[Best] := True;

    Via := '(no incoming reference)';
    for J := 0 to High(Edges) do
      if Edges[J].Resolved and
         (Edges[J].TargetObjectNumber = Nodes[Best].ObjectNumber) and
         (Edges[J].TargetGenerationNumber = Nodes[Best].GenerationNumber) then
      begin
        Via := Edges[J].Path;
        Break;
      end;

    Log(Format('%d %d obj  shallow %d  retained %d  refs in %d  via %s',
      [Nodes[Best].ObjectNumber, Nodes[Best].GenerationNumber,
       Nodes[Best].EstimatedShallowBytes, Nodes[Best].EstimatedRetainedBytes,
       Nodes[Best].IncomingReferenceCount, string(Via)]));
  end;
end;

Um caminho de entrada basta para classificar a maioria dos objetos. Para um objeto compartilhado, IncomingReferenceCount diz quantas referências existem, e ImmediateDominatorObjectNumber com seu número de geração diz qual objeto o domina após a análise de dominadores. Esse campo é -1 para o Catalog e para todo objeto que o Catalog não alcança. Uma aresta cujo flag Resolved é False aponta para um número de objeto que não está carregado; essas são contadas em UnresolvedReferenceCount, e uma contagem alta em um arquivo de resto saudável geralmente significa uma seção de referência cruzada danificada

De onde vêm os objetos inalcançáveis?

Um nó com ReachableFromCatalog definido como False está carregado e custa memória, mas nenhuma cadeia de referências a partir do Catalog chega até ele, então nada na estrutura do documento leva um visualizador até ele. Seu tamanho retido é igual ao seu tamanho raso, porque a análise de dominadores roda apenas sobre objetos alcançáveis. Somar EstimatedRetainedBytes pelos nós inalcançáveis dá, portanto, a mesma resposta que TotalEstimatedBytes - CatalogRetainedBytes

Atualizações incrementais são uma fonte comum, embora não da forma como as pessoas costumam assumir. Quando uma revisão posterior redefine o objeto 2120, a entrada de referência cruzada mais recente vence e a definição antiga nunca é carregada, então cópias substituídas do mesmo número de objeto não aparecem no grafo. O que aparece é um objeto que uma revisão posterior simplesmente deixou de referenciar: uma anotação descartada de um array /Annots reescrito, uma imagem substituída por um novo número de objeto, um campo de formulário removido do AcroForm. Nada na ISO 32000-1 §7.5.6 obriga uma atualização a marcar essas entradas como livres, e enquanto os dados de referência cruzada as listarem como em uso o carregador as trata como objetos vivos. O artigo sobre object streams e atualizações incrementais cobre como as revisões se empilham

HotPDF: atualização incremental que redireciona uma referência para um novo objeto e deixa o objeto referenciado anteriormente carregado, porém inalcançável a partir do Catalog
Uma atualização que aponta o documento para um novo objeto deixa o objeto referenciado anteriormente listado e carregado, mas fora do alcance do Catalog, e seus bytes ainda são contados no TotalEstimatedBytes

As outras duas fontes são produtores que gravam objetos e depois falham em vinculá-los, e arquivos danificados cujos dados de referência cruzada precisaram ser reconstruídos por varredura, o que pode capturar definições de objeto que nada referencia. Quando uma grande fração do total estimado está em nós inalcançáveis, uma reescrita limpa do arquivo ganha de anexar mais uma revisão, e o grafo lhe dá a contagem de bytes para justificar o salvamento mais lento

É o parser que está segurando a memória?

Antes de culpar o documento, verifique como o próprio carregamento se comportou. Duas chamadas descrevem o parser e não o conteúdo, e ambas se reiniciam no início de cada LoadFromFile ou LoadFromStream, então elas sempre descrevem o carregamento mais recente

GetLastParserArenaStatistics preenche um record THPDFParserArenaStatistics para a arena de blocos que guarda tokens e buffers de curta duração durante a análise. Os blocos têm 64 KiB (BlockSize), e uma alocação maior que um bloco recebe um bloco de tamanho próprio. AllocationCount menos ReusedAllocationCount é igual a BlockAllocationCount, o número de vezes que a arena precisou pedir um novo bloco ao gerenciador de memória. Os blocos são mantidos pela vida da instância THotPDF e liberados quando ela é destruída. Se uma instância processa um lote inteiro, RetainedBytes reflete aproximadamente o maior working set que qualquer arquivo do lote precisou, o que explica um platô que dura até o componente ser liberado. TemporaryObjectElisionCount conta chaves de dicionário lidas direto para a arena em vez de serem construídas como objetos de nome temporários

GetDocumentStringInternStatistics descreve o pool por documento que deduplica nomes PDF, operadores de content stream e strings curtas. Strings de 1 a 64 bytes são elegíveis. O pool mantém no máximo 65.536 entradas e 4 MiB, e esses tetos voltam no record como MaxStringLength, MaxEntryCount e MaxRetainedBytes. Uma string vazia, maior que 64 bytes, ou nova quando o pool está cheio é contada em BypassCount e mantida como uma string comum. Um arquivo que gera enormes quantidades de nomes únicos custa, portanto, aproximadamente o que custaria sem o pool, e nada mais

var
  Arena: THPDFParserArenaStatistics;
  Intern: THPDFDocumentStringInternStatistics;
begin
  if Pdf.GetLastParserArenaStatistics(Arena) then
    Log(Format('arena: %d blocks, %d bytes held, peak %d, ' +
      '%d new blocks for %d allocations, %d tokens',
      [Arena.RetainedBlockCount, Arena.RetainedBytes, Arena.PeakUsedBytes,
       Arena.BlockAllocationCount, Arena.AllocationCount, Arena.TokenCount]));

  if Pdf.GetDocumentStringInternStatistics(Intern) then
  begin
    Log(Format('intern: %d of %d requests hit, %d bypassed, %d bytes reused',
      [Intern.HitCount, Intern.RequestCount, Intern.BypassCount,
       Intern.ReusedBytes]));
    // Checagem sua, não é uma chamada da biblioteca: sinaliza um pool que bateu nos tetos
    if (Intern.EntryCount >= Intern.MaxEntryCount) or
       (Intern.RetainedBytes + Intern.MaxStringLength >
        Intern.MaxRetainedBytes) then
      Log('intern pool at its cap: later strings were not deduplicated');
  end;
end;
HotPDF: estatísticas de arena do parser e pool de internamento de strings com reutilização de alocações e um contador de bypass limitado
O registro de arena mostra quanto do tráfego do parser reutilizou blocos reciclados, enquanto o registro de intern mostra o pool justificando sua existência antes que seus tetos forcem desvios — alta reutilização com baixa contagem de desvios livra o carregador de suspeita

PDFs típicos repetem um vocabulário pequeno de nomes e operadores, então HitCount fica perto de RequestCount e ReusedBytes cresce com a contagem de páginas. Um BypassCount que se aproxima de RequestCount em um arquivo modesto é incomum. Em um caminho de entrada para uploads não confiáveis, registre em log

Uma ordem de triagem para uma reclamação de memória

Comece pelo CatalogRetainedBytes. Se ele estiver próximo do crescimento que você mediu no processo, a memória está no documento e o topo da lista de retidos vai nomeá-la. Se estiver bem abaixo, a memória vive em algum lugar que o grafo não mede, como seus próprios caches, bitmaps renderizados ou a arena do parser, e o record da arena é a próxima coisa a ler

  1. Ranqueie os nós por EstimatedRetainedBytes e leia o Path de entrada dos dez primeiros. Alvos XObject no topo geralmente apontam para conteúdo pesado em digitalizações, onde downsampling se paga; alvos /FontFile, /FontFile2 ou /FontFile3 apontam para programas de fonte completos incorporados onde subsets bastariam; streams /Contents grandes geralmente vêm de saída vetorial gerada, como mapas ou exportações de CAD
  2. Subtraia CatalogRetainedBytes de TotalEstimatedBytes. Um resto grande é objeto abandonado, então a correção pertence ao passo de salvamento
  3. Leia os records de arena e intern por último. Eles raramente explicam gigabytes, mas explicam um processo que permanece grande depois que todo documento é fechado

Execute esses passos nessa ordem. O primeiro resolve a maioria das reclamações, e para documentos muito grandes a resposta estrutural geralmente é parar de manter o grafo de objetos inteiro na memória de uma vez, que é para o que o workflow da API de arquivo direto foi construído

Os três diagnósticos são chamadas de método ordinárias que retornam records simples, então se encaixam em qualquer logging ou telemetria que um aplicativo Delphi ou C++Builder já tenha. O HotPDF é distribuído como um componente VCL nativo com código-fonte completo; a documentação e um download de teste estão na página do componente HotPDF Delphi para PDF