Un caché de páginas indexado por nombre de archivo le mostrará las páginas de ayer para un PDF que durante la noche fue sobrescrito con una revisión nueva bajo el mismo nombre. Un caché indexado por un SHA-256 completo del archivo jamás comete ese error, pero en un archivo escaneado de 400 MB el hash puede tardar más que renderizar las dos páginas que el usuario realmente abre. La clave que funciona vive entre esas dos, y elegirla obliga además a una segunda decisión: qué debe hacer una edición en memoria con las páginas que ya están en disco
Cómo el tier de disco de RenderCacheFolder se sienta detrás del caché en memoria
HotPDF RenderCacheFolder agrega un tier persistente detrás del caché de raster en memoria del componente HotPDF para Delphi, y solo participa cuando la propiedad sostiene una ruta no vacía. Una llamada a RenderLoadedPageToBitmapCached(PageIndex, DPI) revisa memoria primero, usando índice de página, DPI y la configuración de render actual como clave. Ante un fallo pregunta al disco. Un hit de disco decodifica el PNG guardado, lo promueve de vuelta a memoria y le entrega una copia. Solo cuando ambos tiers fallan la página pasa por el renderer completo descrito en renderizar una página PDF cargada a un TBitmap, y ese bitmap fresco se escribe a disco de salida
La distribución de carpetas es suficientemente simple para inspeccionarla en Explorer. Cada documento recibe una subcarpeta cuyo nombre combina una clave de documento de 16 caracteres hex con una clave de settings de render de 16 caracteres hex, y cada página aterriza ahí como <page>@<dpi>.png. Un index.txt en el root lista los documentos en orden de uso más reciente bajo un tag de schema; si el tag no coincide, la carpeta completa se limpia en el primer uso. Las escrituras de PNG e índice van primero a un archivo temporal y luego se intercambian con MoveFileExW y el flag de reemplazo, así que un crash a mitad de escritura deja el archivo anterior o ningún archivo. Un PNG que falla al decodificar se borra y cuenta como fallo
Tres límites evitan que la carpeta crezca sin control:
RenderCacheMaxDocuments(default 20) acota la cantidad de subcarpetas de documento, expulsando primero la de uso menos recienteRenderCacheMaxBytes(default 524288000, o 500 MB) acota el tamaño combinado de todos los PNG bajo el root- Cada carpeta de documento sostiene cuando mucho 200 imágenes de página; ese tope está fijo dentro de THotPDF y no tiene propiedad
RenderCacheCapacity (default 8) no tiene relación con el disco. Cuenta las páginas sostenidas en memoria
uses
SysUtils, Graphics, HPDFDoc;
procedure WarmThumbnails(const FileName: string);
var
Pdf: THotPDF;
Bmp: TBitmap;
I: Integer;
begin
Pdf := THotPDF.Create(nil);
try
// El tier de disco lee la carpeta y ambos límites una vez, en el primer
// render con caché, así que asígnelos antes de esa llamada
Pdf.RenderCacheFolder := IncludeTrailingPathDelimiter(
GetEnvironmentVariable('LOCALAPPDATA')) + 'MyViewer\PageCache';
Pdf.RenderCacheMaxDocuments := 50;
Pdf.RenderCacheMaxBytes := Int64(1024) * 1024 * 1024; // 1 GiB
Pdf.RenderCacheCapacity := 16; // páginas en memoria
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 la copia a la tira de thumbnails aquí
finally
Bmp.Free; // la llamada con caché siempre devuelve una copia propiedad del llamador
end;
end;
finally
Pdf.Free; // las entradas de disco sobreviven para la siguiente sesión
end;
end;
Corra ese procedimiento dos veces sobre el mismo archivo y la segunda pasada no rasteriza nada que quepa en los límites. El caché de disco se crea en el primer render con caché y vive lo que viva la instancia THotPDF, así que cambiar la carpeta o cualquiera de los límites después de ese momento no la mueve ni la redimensiona. Dos condiciones más mantienen una página fuera del disco. Un bitmap arriba del techo por entrada default del caché en memoria (64 MiB de píxeles de 32 bits, una página de 4096 × 4096) no se guarda. Y el tier de disco solo se consulta mientras RenderFallbackPolicy se queda en su default rfpIgnore, ya que un PNG carga píxeles pero ninguno de los diagnósticos de fallback que reporta una política más estricta
¿Por qué fallan las claves de caché obvias?
Tres claves vienen a la cabeza primero, y cada una falla de una manera distinta. La ruta de archivo falla ante una sobrescritura. Un hash de una copia en memoria de los bytes del PDF se ve seguro hasta que uno nota que un parser leyendo el archivo in situ no tiene razón para conservar tal copia; hashear un buffer que nunca se llenó produce una clave vacía, y un caché que trata una clave vacía como "sáltate el disco" deja una carpeta correctamente configurada que jamás recibe un PNG. Hashear el archivo completo desde disco funciona, al costo de leer cada byte en cada apertura
La trampa más dura es la invalidación. Un componente así tiene que limpiar sus páginas en memoria al inicio de cada carga, después de cada edición y cuando se destruye, y el movimiento tentador es borrar la carpeta de disco del documento en el mismo lugar. Hágalo y cada sesión del visor limpia su propio caché al salir, así que la mañana siguiente empieza fría igual. Recomputar la clave desde la fuente sin cambios después de una edición es peor todavía: los renders editados aterrizan bajo la clave del archivo original y se le sirven a quien abra el PDF intacto después. Identidad e invalidación tienen que diseñarse como una sola pieza. Equivoque cualquiera de las dos y distribuye un caché que jamás acierta, o uno que muestra páginas que el archivo no contiene
Cómo calcula HotPDF la huella de una fuente PDF
HotPDF identifica un PDF cargado con LoadFromFile hasheando con SHA-256 su tamaño, su hora de última escritura y sus primeros y últimos 64 KiB, e identifica un stream o fuente de acceso aleatorio por un SHA-256 del contenido completo. La identidad se captura una vez, cuando una carga tiene éxito, y los primeros 16 caracteres hex del digest (64 bits) se vuelven la clave del documento
| Fuente | Identidad | Costo | Cuándo se captura |
|---|---|---|---|
LoadFromFile | Tamaño + hora de última escritura + primeros y últimos 64 KiB, con hash SHA-256 | A lo sumo 128 KiB leídos, sea cual sea el tamaño del archivo | Toda carga con éxito, aun si RenderCacheFolder se asigna después |
LoadFromStream | SHA-256 de todo el stream | Una pasada completa sobre la fuente | Solo si RenderCacheFolder estaba asignado antes de la carga |
LoadFromRandomAccessSource | SHA-256 de toda la fuente | Una pasada completa sobre la fuente | Solo si la carpeta estaba asignada primero y cada rango de bytes está disponible |
Cualquier fuente con una entrada /Encrypt | Ninguna | Ninguno | Nunca; el tier de disco se omite |
Para un visor de escritorio la huella muestreada es el default correcto, y el hasheo completo en cada apertura es el equivocado. Las dos regiones muestreadas se eligieron de la estructura del archivo. El header vive al inicio; el trailer y la última sección de referencias cruzadas viven al final (ISO 32000-1 §7.5). Una actualización incremental agrega un body nuevo, sección de referencias cruzadas y trailer (§7.5.6), lo que cambia el tamaño y la cola juntos, y cualquier reescritura completa ordinaria mueve la hora de última escritura. Debajo de 128 KiB las dos muestras se traslapan y cubren cada byte, así que los documentos chicos se hashean completos de todas formas
Lo que se cuela es una edición del mismo tamaño en medio de un archivo grande por una herramienta que luego restaura el timestamp original. Existen editores que deliberadamente conservan las horas de modificación mientras cambian el contenido, pero son raros, y contra tal archivo el caché sirve páginas viejas. El caso contrario juega a su favor: una copia de archivos de Windows conserva la hora de última escritura, así que una copia de un documento con caché acierta en las mismas entradas, lo que es correcto porque los bytes coinciden
Un stream no tiene timestamp. El contenido es la única identidad honesta, así que HotPDF paga la pasada completa de SHA-256 solo cuando se pidió un caché de disco antes de la carga, y el código que llama LoadFromStream sin carpeta de caché no paga nada extra. Eso hace que el orden de dos líneas importe:
procedure OpenDownloadedPdf(Pdf: THotPDF; Data: TStream;
const CacheRoot: string);
begin
// Orden equivocado para streams: el hash del contenido solo se computa
// cuando el folder ya está puesto, así que este documento pasaría de largo el tier de disco
// Pdf.LoadFromStream(Data);
// Pdf.RenderCacheFolder := CacheRoot;
Pdf.RenderCacheFolder := CacheRoot; // póngalo primero
Data.Position := 0;
if Pdf.LoadFromStream(Data) <= 0 then
raise Exception.Create('The stream is not a loadable PDF');
end;
Una fuente de acceso aleatorio que aún descarga no recibe identidad alguna en vez de un hash de los rangos que hayan llegado. Si computar la identidad lanza por cualquier razón, la carga igual tiene éxito y el documento renderiza solo vía memoria
¿Qué pasa con las páginas en caché después de una edición?
Editar un documento cargado jamás borra nada del caché de render en disco de HotPDF. La edición suelta la identidad del documento en cambio, así que el resto de esa carga omite el tier de disco, y las páginas guardadas siguen válidas para el archivo sin modificar desde el que se renderizaron. Las entradas dejan el disco solo por los límites de documentos y bytes, el tope de 200 páginas, un PNG que falla al decodificar, o un cambio de schema
La clave describe un archivo en disco. Una vez que estampa una página o cambia una anotación, el documento en memoria ya no coincide con él, así que ni leer ni escribir bajo esa clave sería honesto. InvalidateRenderedPageCache y la invalidación por página que las ediciones disparan limpian ambos la identidad y dejan la carpeta tranquila. Una segunda revisión cubre los caminos de edición que jamás invalidaron nada: antes de cada búsqueda en disco, THotPDF pregunta si algún objeto cargado carga cambios sin guardar y, si alguno los carga, trata al documento como sin identidad
Los settings de render van por el otro lado. Asignar PageRenderBackend (lo que UseNativeGDIRenderBackend hace por usted), llamar ConfigureRenderICCWorkflow o llamar ClearRenderICCWorkflow vacía las páginas en memoria pero conserva la identidad, porque el documento sigue coincidiendo con su archivo. Esos settings cambian píxeles sin aparecer en la clave de memoria, así que la clave de disco pliega el nombre del backend, el flag de compensación de punto negro y digests SHA-256 de los perfiles ICC de prueba y salida. La clave de memoria ya cubre la intención de color, el dithering de salida, la vista previa de overprint, el modo de máscara de luminosidad, la política de fallback y la visibilidad de cada grupo de contenido opcional
La visibilidad de capas es un buen ejemplo de un cambio que se queda en disco. SetLoadedOptionalContentGroupVisible registra el override en memoria sin tocar ningún objeto PDF, así que el documento conserva su identidad y la vista alternada renderiza a su propia subcarpeta junto a la 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);
// Misma clave de documento, distinta clave de settings de render: esta página se lee
// de o se escribe a una segunda carpeta, y la vista default queda intacta
Bmp := Pdf.RenderLoadedPageToBitmapCached(PageIndex, 150);
end;
Un documento editado regresa al tier de disco solo volviéndose un archivo nuevo. Guárdelo y cargue el resultado:
procedure CommitEditsAndRekey(Pdf: THotPDF; const EditedFile: string);
begin
// Después de editar: refresque las páginas en memoria. La identidad de la fuente
// ya se fue, así que la carpeta del documento original no se lee
// ni se escribe
Pdf.InvalidateRenderedPageCache;
// El archivo guardado tiene su propio tamaño y hora de última escritura, y por lo
// tanto su propia identidad; los renders tras esta carga se cachean bajo la clave nueva
Pdf.SaveLoadedDocument(EditedFile);
if Pdf.LoadFromFile(EditedFile) <= 0 then
raise Exception.Create('Could not reload the edited document');
end;
La carpeta del documento original se queda donde estaba y envejece vía RenderCacheMaxDocuments y RenderCacheMaxBytes como cualquier otra entrada. Reabra el original sin editar y sus páginas siguen ahí
Fuentes cifradas, junctions y roots compartidos
El caché de render en disco de HotPDF rechaza dos entradas a propósito: las páginas de un PDF cifrado, y las subcarpetas de documento que sean junctions u otros reparse points. Ambas reglas canjean hits de caché por seguridad
Los PDF cifrados se quedan en memoria
Una página renderizada es contenido descifrado. Escribirla como un PNG plano en una carpeta de caché dejaría una copia legible de un documento protegido por contraseña en disco, fuera de la protección que su autor eligió (ISO 32000-1 §7.6). HotPDF no captura identidad para ninguna fuente cuyo trailer cargue una entrada /Encrypt, haya sido abierto con contraseña o con contraseña de usuario vacía. Esos documentos igual usan el tier de memoria, que desaparece con el proceso
Las carpetas de documento enlazadas se saltan
El root del caché lo elige usted, y apuntarlo a una junction está bien. Las subcarpetas debajo son otro asunto: el caché las crea, toca y borra por su cuenta durante la limpieza de arranque, la búsqueda, el guardado y los tres límites de expulsión. Si alguien con acceso de escritura al root cambiara una carpeta de documento por una junction a otro directorio, cada una de esas operaciones la seguiría, y la expulsión borraría archivos en otro lado. Cada punto de entrada lee primero los atributos de la carpeta y se salta cualquier cosa marcada como reparse point. Una búsqueda cuenta un fallo, un guardado cuenta una falla de escritura, y la expulsión la deja tranquila
Rutas Unicode y un root por proceso
RenderCacheFolder es un string Unicode, y el reemplazo atómico llama a la API ancha de Windows, así que una ruta de perfil fuera de la página de códigos del sistema (un nombre de usuario chino en una instalación de Windows en inglés, digamos) llega al caché intacta. Varias instancias THotPDF en un proceso que resuelven al mismo root, comparadas sin distinguir mayúsculas tras expandir la ruta, comparten un índice con conteo de referencias y un lock. Eso importa para los límites: copias separadas de index.txt impondrían cada una el presupuesto de 500 MB contra una vista parcial y dejarían crecer la carpeta varias veces más allá
El compartir termina en la frontera del proceso. Dos procesos sobre el mismo root mantienen índices en memoria separados, así que cada aplicación corriendo en paralelo debería recibir su propio root. Los worker threads dentro de un proceso están bien: PrefetchLoadedPages y la cola en renderizado en segundo plano con una cola de solicitudes pasan por el mismo camino con caché y el mismo lock
Settings que hay que acertar antes de distribuir
- Asigne la carpeta y ambos límites antes del primer render con caché, y para cargas de stream o acceso aleatorio antes de cargar
- Espere renderizado solo en memoria para PDFs cifrados, para documentos editados después de la carga, y siempre que
RenderFallbackPolicyno searfpIgnore - Dele a cada aplicación en ejecución su propio root de caché bajo una ubicación por usuario como
%LOCALAPPDATA%
Un caché de páginas persistente gana su espacio en disco en un visor que reabre los mismos documentos todo el día, que es la carga de trabajo detrás de la arquitectura de visor PDF personalizado en Delphi de este blog. El tier de disco, el caché de raster en memoria y el renderer de páginas son todos parte del componente PDF de HotPDF para Delphi, disponible para Delphi y C++Builder