Artigo Técnico

HotPDF RenderCacheFolder: um page cache em disco no Delphi

Um page cache chaveado por file name vai mostrar as páginas de ontem para um PDF que foi sobrescrito durante a noite com uma nova revisão sob o mesmo nome. Um cache chaveado por um SHA-256 completo do arquivo nunca comete esse erro, mas num arquivo escaneado de 400 MB o hash pode demorar mais que renderizar as duas páginas que o usuário realmente abre. A key viável senta entre esses dois, e escolhê-la também força uma segunda decisão: o que uma edição em memória deve fazer com páginas que já estão no disco

Como o disk tier do RenderCacheFolder senta atrás do cache de memória

O RenderCacheFolder do HotPDF adiciona um tier persistente atrás do cache de rasters em memória do componente Delphi da HotPDF, e ele só entra em cena quando a propriedade segura um path não vazio. Uma chamada a RenderLoadedPageToBitmapCached(PageIndex, DPI) confere a memória primeiro, usando page index, DPI e as configurações de render correntes como key. Num miss ela pergunta ao disco. Um disk hit decodifica o PNG armazenado, o promove de volta para a memória e entrega a você uma cópia. Só quando os dois tiers erram é que a página passa pelo renderer completo descrito em renderizar uma página PDF carregada para um TBitmap, e esse bitmap fresco é escrito no disco na saída

Diagrama do HotPDF da lookup do render cache para RenderLoadedPageToBitmapCached: o tier em memória chaveado por página, DPI e variante de render é conferido primeiro, depois o disk tier do RenderCacheFolder de arquivos PNG com replace atômico, depois o interpretador de content streams, e todo hit devolve uma cópia de propriedade do caller
O HotPDF olha na memória primeiro, depois no disco, e só então rasteriza; um disk hit é promovido de volta para a memória e todo caminho entrega uma cópia que é sua e que você precisa liberar

O layout da pasta é simples o bastante para inspecionar no Explorer. Cada documento ganha uma subpasta cujo nome combina uma document key de 16 caracteres hex com uma render-settings key de 16 caracteres hex, e toda página pousa lá como <page>@<dpi>.png. Um index.txt na raiz lista documentos em ordem most-recently-used sob uma tag de schema; se a tag não casa, a pasta inteira é limpa no primeiro uso. Escritas de PNG e do index vão primeiro para um arquivo temporário e depois são trocadas com MoveFileExW e a flag replace-existing, então um crash no meio de uma escrita deixa o arquivo anterior ou nenhum arquivo. Um PNG que falha ao decodificar é apagado e contado como miss

Três limites mantêm a pasta de crescer sem fim:

  • RenderCacheMaxDocuments (default 20) limita o número de subpastas de documento, despejando a least recently used primeiro
  • RenderCacheMaxBytes (default 524288000, ou 500 MB) limita o tamanho combinado de todo PNG sob a raiz
  • Cada pasta de documento segura no máximo 200 imagens de página; esse cap é fixo dentro do THotPDF e não tem propriedade

RenderCacheCapacity (default 8) não tem relação com o disco. Ele conta páginas seguradas em memória

uses
  SysUtils, Graphics, HPDFDoc;

procedure WarmThumbnails(const FileName: string);
var
  Pdf: THotPDF;
  Bmp: TBitmap;
  I: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    // O disk tier lê a pasta e os dois limites uma vez, no primeiro
    // cached render, então defina-os antes dessa chamada
    Pdf.RenderCacheFolder := IncludeTrailingPathDelimiter(
      GetEnvironmentVariable('LOCALAPPDATA')) + 'MyViewer\PageCache';
    Pdf.RenderCacheMaxDocuments := 50;
    Pdf.RenderCacheMaxBytes := Int64(1024) * 1024 * 1024; // 1 GiB
    Pdf.RenderCacheCapacity := 16;                        // páginas na memória

    if Pdf.LoadFromFile(FileName) > 0 then
      for I := 0 to Pdf.LoadedPageCount - 1 do
      begin
        Bmp := Pdf.RenderLoadedPageToBitmapCached(I, 96);
        if Bmp <> nil then
        try
          // Entregue a cópia à thumbnail strip aqui
        finally
          Bmp.Free; // a chamada cached sempre retorna uma cópia de propriedade do caller
        end;
      end;
  finally
    Pdf.Free; // entradas de disco sobrevivem para a próxima sessão
  end;
end;

Rode esse procedimento duas vezes no mesmo arquivo e a segunda passada não rasteriza nada que coubesse nos limites. O disk cache é criado no primeiro cached render e vive enquanto a instância THotPDF viver, então mudar a pasta ou qualquer um dos limites depois desse momento não move nem redimensiona ele. Mais duas condições mantêm uma página longe do disco. Um bitmap acima do teto por entrada default do cache de memória (64 MiB de pixels de 32 bits, uma página de 4096 × 4096) não é armazenado. E o disk tier só é consultado enquanto o RenderFallbackPolicy fica no default dele rfpIgnore, já que um PNG carrega pixels mas nenhum dos diagnósticos de fallback que uma política mais estrita reporta

Por que as keys de cache óbvias falham?

Três keys vêm à mente primeiro, e cada uma falha de um jeito diferente. O file path falha em overwrite. Um hash de uma cópia em memória dos bytes do PDF parece seguro até você notar que um parser lendo o arquivo in place não tem razão para guardar tal cópia; hashear um buffer que nunca foi preenchido rende uma key vazia, e um cache que trata key vazia como "pule o disco" deixa uma pasta corretamente configurada que nunca recebe um PNG. Hashear o arquivo inteiro do disco funciona, ao custo de ler todo byte a cada abertura

A armadilha mais difícil é invalidação. Um componente assim precisa limpar as páginas em memória dele no início de toda carga, depois de toda edição e quando é destruído, e o movimento tentador é apagar a pasta de disco do documento no mesmo lugar. Faça isso e toda sessão de viewer limpa o próprio cache dela na saída, então a manhã seguinte começa fria mesmo assim. Recalcular a key da fonte não modificada depois de uma edição é pior ainda: os renders editados pousam sob a key do arquivo original e são servidos a quem abrir o PDF intocado em seguida. Identidade e invalidação precisam ser desenhadas como uma peça única. Erre em qualquer uma e você shipa um cache que nunca acerta, ou um que mostra páginas que o arquivo não contém

Como o HotPDF tira a impressão digital de uma fonte PDF

O HotPDF identifica um PDF carregado com LoadFromFile hasheando o tamanho dele, o last-write time dele e os primeiros e últimos 64 KiB dele com SHA-256, e identifica um stream ou fonte random-access por um SHA-256 do conteúdo inteiro. A identidade é capturada uma vez, quando uma carga tem sucesso, e os primeiros 16 caracteres hex do digest (64 bits) viram a document key

FonteIdentidadeCustoCapturada quando
LoadFromFileTamanho + last-write time + primeiros e últimos 64 KiB, hasheados com SHA-256No máximo 128 KiB lidos, qualquer que seja o tamanho do arquivoToda carga com sucesso, mesmo que o RenderCacheFolder seja definido depois
LoadFromStreamSHA-256 do stream inteiroUma passada completa sobre a fonteSó se o RenderCacheFolder estava definido antes da carga
LoadFromRandomAccessSourceSHA-256 da fonte inteiraUma passada completa sobre a fonteSó se a pasta foi definida primeiro e toda faixa de bytes está disponível
Qualquer fonte com uma entrada /EncryptNenhumaNenhumNunca; o disk tier é contornado
Mapa de identidade de fontes do HotPDF para o disk render cache: LoadFromFile hasheia tamanho, LastWriteTime e os primeiros e últimos 64 KiB, LoadFromStream e LoadFromRandomAccessSource hasheiam o conteúdo inteiro só quando RenderCacheFolder foi definido primeiro, e qualquer trailer /Encrypt não captura identidade nenhuma
arquivos recebem fingerprint das extremidades porque o header, o xref e o trailer vivem lá, streams só pagam um hash completo quando você pediu o cache primeiro, e documentos criptografados nunca são escritos no disco

Para um viewer desktop o fingerprint amostrado é o default certo, e hash completo a cada abertura é o errado. As duas regiões amostradas foram escolhidas da estrutura do arquivo. O header senta no início; o trailer e a última seção de cross-reference sentam no fim (ISO 32000-1 §7.5). Um incremental update anexa um body novo, seção de cross-reference e trailer (§7.5.6), o que muda o tamanho e a cauda juntos, e qualquer rewrite completo comum bumpa o last-write time. Abaixo de 128 KiB as duas amostras se sobrepõem e cobrem todo byte, então documentos pequenos são hasheados por completo de qualquer forma

O que escapa é uma edição de mesmo tamanho no meio de um arquivo grande por uma ferramenta que depois restaura o timestamp original. Editors que deliberadamente preservam modification times enquanto mudam conteúdo existem, mas são raros, e contra tal arquivo o cache serve páginas velhas. O caso oposto joga a seu favor: uma cópia de arquivo do Windows mantém o last-write time, então uma cópia de um documento em cache acerta as mesmas entradas, o que é correto já que os bytes batem

Um stream não tem timestamp. Conteúdo é a única identidade honesta, então o HotPDF paga a passada SHA-256 completa só quando um disk cache foi pedido antes da carga, e código que chama LoadFromStream sem pasta de cache não paga nada extra. Isso faz a ordem de duas linhas importar:

procedure OpenDownloadedPdf(Pdf: THotPDF; Data: TStream;
  const CacheRoot: string);
begin
  // Ordem errada para streams: o content hash só é computado quando a
  // pasta já está definida, então este documento contornaria o disk tier
  //   Pdf.LoadFromStream(Data);
  //   Pdf.RenderCacheFolder := CacheRoot;

  Pdf.RenderCacheFolder := CacheRoot; // defina primeiro
  Data.Position := 0;
  if Pdf.LoadFromStream(Data) <= 0 then
    raise Exception.Create('The stream is not a loadable PDF');
end;

Uma fonte random-access que ainda está baixando não recebe identidade nenhuma em vez de um hash das faixas que chegaram. Se computar a identidade levanta exceção por qualquer razão, a carga mesmo assim tem sucesso e o documento renderiza só pela memória

O que acontece com as páginas em cache depois de uma edição?

Editar um documento carregado nunca apaga nada do disk render cache do HotPDF. A edição descarta a identidade do documento em vez disso, então o resto daquela carga contorna o disk tier, e as páginas armazenadas ficam válidas para o arquivo não modificado de que foram renderizadas. Entradas saem do disco só pelos limites de documento e bytes, o cap de 200 páginas, um PNG que falha ao decodificar, ou uma mudança de schema

A key descreve um arquivo no disco. Uma vez que você estampa uma página ou muda uma annotation, o documento em memória não casa mais com ela, então nem ler nem escrever sob essa key seria honesto. O InvalidateRenderedPageCache e a invalidação por página que edições disparam ambos limpam a identidade e deixam a pasta em paz. Uma segunda checagem cobre caminhos de edição que nunca invalidaram nada: antes de cada disk lookup, o THotPDF pergunta se algum objeto carregado carrega mudanças não salvas e, se um carrega, trata o documento como sem identidade

Configurações de render vão para o outro lado. Atribuir PageRenderBackend (o que o UseNativeGDIRenderBackend faz por você), chamar ConfigureRenderICCWorkflow ou chamar ClearRenderICCWorkflow esvazia as páginas em memória mas mantém a identidade, porque o documento ainda casa com o arquivo dele. Essas configurações mudam pixels sem aparecer na key de memória, então a key de disco dobra o nome do backend, a flag de black-point compensation e digests SHA-256 dos perfis ICC de proof e output. A key de memória já cobre o color intent, output dithering, overprint preview, modo de luminosity mask, política de fallback e a visibilidade de todo optional content group

Semântica de invalidação do HotPDF para o disk cache RenderCacheFolder: editar o documento carregado ou qualquer objeto dirty descarta a identidade da fonte para que o tier seja contornado, mudar o render backend ou o ICC workflow mantém a identidade sob uma nova key de variante, e salvar mais recarregar re-keya o documento
uma edição nunca apaga a pasta armazenada, uma mudança de configurações renderiza sob uma key diferente, e só salvar mais recarregar rende ao documento editado uma identidade fresca

Visibilidade de layers é um bom exemplo de mudança que fica no disco. O SetLoadedOptionalContentGroupVisible registra o override em memória sem tocar em nenhum objeto PDF, então o documento mantém a identidade dele e a view alternada renderiza na própria subpasta dela ao lado da default:

procedure ShowLayer(Pdf: THotPDF; const LayerName: AnsiString;
  PageIndex: Integer; out Bmp: TBitmap);
var
  I: Integer;
begin
  for I := 0 to Pdf.GetLoadedOptionalContentGroupCount - 1 do
    if Pdf.GetLoadedOptionalContentGroupName(I) = LayerName then
      Pdf.SetLoadedOptionalContentGroupVisible(I, True);

  // Mesma document key, render-settings key diferente: esta página é lida
  // de ou escrita para uma segunda pasta, e a view default fica intocada
  Bmp := Pdf.RenderLoadedPageToBitmapCached(PageIndex, 150);
end;

Um documento editado volta ao disk tier só virando um arquivo novo. Salve-o e carregue o resultado:

procedure CommitEditsAndRekey(Pdf: THotPDF; const EditedFile: string);
begin
  // Depois de editar: atualize as páginas em memória. A identidade da fonte
  // já se foi, então a pasta do documento original não é lida
  // nem escrita
  Pdf.InvalidateRenderedPageCache;

  // O arquivo salvo tem o próprio tamanho e last-write time dele, logo a própria
  // identidade dele; renders depois dessa carga são cacheados sob a nova key
  Pdf.SaveLoadedDocument(EditedFile);
  if Pdf.LoadFromFile(EditedFile) <= 0 then
    raise Exception.Create('Could not reload the edited document');
end;

A pasta do documento original fica onde estava e envelhece pelos RenderCacheMaxDocuments e RenderCacheMaxBytes como qualquer outra entrada. Reabra o original não editado e as páginas dele continuam lá

Fontes criptografadas, junctions e raízes compartilhadas

O disk render cache do HotPDF recusa dois inputs de propósito: páginas de um PDF criptografado, e subpastas de documento que sejam junctions ou outros reparse points. As duas regras trocam cache hits por segurança

PDFs criptografados ficam na memória

Uma página renderizada é conteúdo descriptografado. Escrevê-la como um PNG comum numa pasta de cache deixaria uma cópia legível de um documento protegido por senha no disco, fora da proteção que o autor dele escolheu (ISO 32000-1 §7.6). O HotPDF não captura identidade nenhuma para qualquer fonte cujo trailer carregue uma entrada /Encrypt, quer ela tenha sido aberta com senha ou com uma user password vazia. Esses documentos continuam usando o tier de memória, que desaparece com o processo

Pastas de documento linkadas são puladas

A raiz do cache é sua para escolher, e apontá-la para uma junction está OK. As subpastas sob ela são diferentes: o cache as cria, toca e apaga por conta própria durante a limpeza de startup, lookup, store e os três limites de eviction. Se alguém com acesso de escrita à raiz trocasse uma pasta de documento por uma junction para outro diretório, cada uma dessas operações a seguiria, e a eviction apagaria arquivos em outro lugar. Cada entry point lê primeiro os attributes da pasta e pula qualquer coisa flagada como reparse point. Um lookup conta um miss, um store conta uma falha de escrita, e a eviction a deixa em paz

Paths Unicode e uma raiz por processo

RenderCacheFolder é uma string Unicode, e o replace atômico chama a API wide do Windows, então um profile path fora da code page do sistema (um nome de usuário chinês numa instalação Windows em inglês, digamos) chega ao cache intacto. Várias instâncias THotPDF num processo que resolvem para a mesma raiz, comparadas case-insensitively depois de expansão de path, dividem um índice reference-counted e um lock. Isso importa para os limites: cópias separadas de index.txt cada uma forçaria o budget de 500 MB contra uma visão parcial e deixariam a pasta crescer várias vezes além dele

O compartilhamento termina na fronteira do processo. Dois processos na mesma raiz mantêm índices em memória separados, então cada aplicação rodando concorrentemente deveria ganhar a própria raiz dela. Worker threads dentro de um processo estão OK: o PrefetchLoadedPages e a fila em renderização em background com uma fila de requests passam pelo mesmo caminho cached e pelo mesmo lock

Configurações para acertar antes de shipar

  • Defina a pasta e os dois limites antes do primeiro cached render, e para cargas de stream ou random-access antes de carregar
  • Espere rendering só em memória para PDFs criptografados, para documentos editados depois da carga, e sempre que o RenderFallbackPolicy não for rfpIgnore
  • Dê a cada aplicação rodando a própria raiz de cache dela sob um local por usuário como %LOCALAPPDATA%

Um page cache persistente rende o espaço de disco dele num viewer que reabre os mesmos documentos o dia inteiro, que é o workload por trás da arquitetura de viewer PDF customizado no Delphi neste blog. O disk tier, o cache de rasters em memória e o page renderer são todos parte do HotPDF Delphi PDF component, disponível para Delphi e C++Builder