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
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 primeiroRenderCacheMaxBytes(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
| Fonte | Identidade | Custo | Capturada quando |
|---|---|---|---|
LoadFromFile | Tamanho + last-write time + primeiros e últimos 64 KiB, hasheados com SHA-256 | No máximo 128 KiB lidos, qualquer que seja o tamanho do arquivo | Toda carga com sucesso, mesmo que o RenderCacheFolder seja definido depois |
LoadFromStream | SHA-256 do stream inteiro | Uma passada completa sobre a fonte | Só se o RenderCacheFolder estava definido antes da carga |
LoadFromRandomAccessSource | SHA-256 da fonte inteira | Uma passada completa sobre a fonte | Só se a pasta foi definida primeiro e toda faixa de bytes está disponível |
Qualquer fonte com uma entrada /Encrypt | Nenhuma | Nenhum | Nunca; o disk tier é contornado |
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
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
RenderFallbackPolicynão forrfpIgnore - 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