Artículo técnico

HotPDF RenderCacheFolder: la caché de páginas en disco

Una caché de páginas indexada por nombre de archivo mostrará las páginas de ayer para un PDF que se sobrescribió durante la noche con una revisión nueva bajo el mismo nombre. Una caché indexada por un SHA-256 completo del archivo jamás comete ese error, pero sobre un archivo escaneado de 400 MB el hash puede tardar más que renderizar las dos páginas que el usuario abre de verdad. La clave trabajable se sienta entre ambas, y escogerla fuerza además una segunda decisión: qué debería hacer una edición en memoria con las páginas que ya están en disco

Cómo se sienta el nivel de disco RenderCacheFolder detrás de la caché en memoria

HotPDF RenderCacheFolder añade un nivel persistente detrás de la caché raster en memoria del componente Delphi de HotPDF, y solo toma parte cuando la propiedad sostiene una ruta no vacía. Una llamada a RenderLoadedPageToBitmapCached(PageIndex, DPI) comprueba primero la memoria, usando índice de página, DPI y los ajustes de render actuales como clave. Ante un fallo pregunta al disco. Un acierto en disco decodifica el PNG guardado, lo asciende de vuelta a memoria y le entrega una copia. Solo cuando ambos niveles fallan pasa la página por el renderer completo descrito en renderizar una página PDF cargada a un TBitmap, y ese bitmap fresco se escribe a disco a la salida

Diagrama de HotPDF de la búsqueda en la caché de renderizado para RenderLoadedPageToBitmapCached: primero se comprueba el nivel en memoria indexado por página, DPI y variante de render, luego el nivel de disco RenderCacheFolder de archivos PNG con reemplazo atómico, luego el intérprete de content stream, y cada acierto devuelve una copia propiedad del llamador
HotPDF mira primero en memoria, luego en disco, y solo entonces rasteriza; un acierto en disco se asciende de vuelta a memoria y cada camino le entrega una copia que es suya y debe liberar

La disposición de la carpeta es bastante simple para inspeccionarla en el Explorer. Cada documento recibe una subcarpeta cuyo nombre combina una clave de documento de 16 caracteres hexadecimales con una clave de ajustes de render de otros 16, y cada página aterriza allí como <page>@<dpi>.png. Un index.txt en la raíz lista los documentos en orden de uso más reciente bajo una etiqueta de esquema; si la etiqueta no casa, la carpeta entera se limpia en el primer uso. Las escrituras de PNG e índice van primero a un archivo temporal y luego se intercambian a su sitio con MoveFileExW y el flag de reemplazar-el-existente, así que un crash a mitad de escritura deja el archivo anterior o ningún archivo. Un PNG que falla al decodificarse se borra y cuenta como fallo

Tres límites evitan que la carpeta crezca sin cota:

  • RenderCacheMaxDocuments (por defecto 20) acota el número de subcarpetas de documento; la carpeta usada hace más tiempo se expulsa primero
  • RenderCacheMaxBytes (por defecto 524288000, que son 500 MB) acota el tamaño total de todos los PNG bajo la raíz
  • Cada carpeta de documento guarda como mucho 200 imágenes de página; ese tope lo fija THotPDF por dentro y no tiene propiedad

RenderCacheCapacity (por defecto 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 nivel de disco lee la carpeta y ambos límites una vez, en el primer
    // render cacheado, así que fíjelos 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 aquí la copia a la tira de miniaturas
        finally
          Bmp.Free; // la llamada cacheada 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 cupiera en los límites. La caché de disco se crea en el primer render cacheado y vive tanto como la instancia THotPDF, así que cambiar la carpeta o cualquiera de los dos 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 por encima del techo por entrada por defecto de la caché en memoria (64 MiB de píxeles de 32 bits, una página de 4096 × 4096) no se guarda. Y el nivel de disco solo se consulta mientras RenderFallbackPolicy se queda en su rfpIgnore por defecto, porque un PNG lleva píxeles pero ninguno de los diagnósticos de fallback que una política más estricta reporta

¿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 del archivo falla ante la sobrescritura. Un hash de una copia en memoria de los bytes del PDF parece seguro hasta que usted nota que un parser que lee el archivo en el sitio no tiene razón alguna para conservar semejante copia; hashear un buffer que jamás se rellenó da una clave vacía, y una 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 entero desde disco funciona, al precio de leer cada byte en cada apertura

La trampa más dura es la invalidación. Un componente como este tiene que limpiar sus páginas en memoria al inicio de cada carga, tras cada edición y cuando se destruye, y el movimiento tentador es borrar la carpeta de disco del documento en el mismo sitio. Hágalo y cada sesión del visor limpia su propia caché al salir, así que la mañana siguiente arranca fría de todos modos. Recalcular la clave desde la fuente sin cambios tras una edición es peor todavía: los renders editados aterrizan bajo la clave del archivo original y se 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 despacha una caché que jamás acierta, o una que muestra páginas que el archivo no contiene

Cómo huella HotPDF una fuente PDF

HotPDF identifica un PDF cargado con LoadFromFile hasheando con SHA-256 su tamaño, su fecha de última escritura y sus primeros y últimos 64 KiB, e identifica un stream o una fuente de acceso aleatorio por un SHA-256 del contenido entero. La identidad se captura una vez, cuando una carga tiene éxito, y los primeros 16 caracteres hexadecimales del digest (64 bits) se convierten en la clave de documento

FuenteIdentidadCosteCuándo se captura
LoadFromFileTamaño + LastWriteTime + primeros y últimos 64 KiB, hasheados con SHA-256Como mucho 128 KiB leídos, sea cual sea el tamaño del archivoCada carga con éxito, aunque RenderCacheFolder se fije después
LoadFromStreamSHA-256 del stream enteroUna pasada completa por el fuenteSolo si RenderCacheFolder se fijó antes de la carga
LoadFromRandomAccessSourceSHA-256 de la fuente enteraUna pasada completa por la fuenteSolo si la carpeta se fijó primero y cada rango de bytes está disponible
Cualquier fuente con una entrada /EncryptNingunaNingunoNunca; el nivel de disco se omite
Mapa de identidad de fuentes de HotPDF para la caché de render en disco: LoadFromFile hashea tamaño, LastWriteTime y los primeros y últimos 64 KiB, LoadFromStream y LoadFromRandomAccessSource hashean el contenido entero solo cuando RenderCacheFolder se fijó primero, y cualquier trailer /Encrypt no captura identidad alguna
los archivos se huellan desde sus extremos porque la cabecera, el xref y el trailer viven ahí, los streams solo pagan un hash completo cuando usted pidió la caché primero, y los documentos cifrados jamás se escriben a disco

Para un visor de escritorio la huella muestreada es el valor por defecto correcto, y el hash completo en cada apertura es el equivocado. Las dos regiones muestreadas se escogieron desde la estructura del archivo. La cabecera se sienta al principio; el trailer y la última sección de cross-reference se sientan al final (ISO 32000-1 §7.5). Un incremental update añade un cuerpo, una sección de cross-reference y un trailer nuevos (§7.5.6), lo que cambia el tamaño y la cola a la vez, y cualquier reescritura completa ordinaria cambia la fecha de última escritura. Por debajo de 128 KiB las dos muestras se solapan y cubren cada byte, así que los documentos pequeños quedan hasheados por completo de todos modos

Lo que se cuela es una edición del mismo tamaño en medio de un archivo grande por una herramienta que luego restaura la marca de tiempo original. Los editores que preservan deliberadamente las marcas de modificación mientras cambian el contenido existen, pero son raros, y contra semejante archivo la caché sirve páginas caducadas. El caso contrario juega a su favor: una copia de archivo de Windows conserva la fecha de última escritura, así que una copia de un documento cacheado acierta en las mismas entradas, lo cual es correcto porque los bytes coinciden

Un stream no tiene marca de tiempo. El contenido es la única identidad honesta, así que HotPDF paga la pasada completa de SHA-256 solo cuando se pidió una caché de disco antes de la carga, y el código que llama a 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 calcula
  // cuando la carpeta ya está fijada, así que este documento omitiría el nivel
  //   Pdf.LoadFromStream(Data);
  //   Pdf.RenderCacheFolder := CacheRoot;

  Pdf.RenderCacheFolder := CacheRoot; // fije 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 sigue descargándose no recibe identidad alguna en lugar de un hash de los rangos que hayan llegado. Si calcular la identidad lanza por cualquier motivo, la carga tiene éxito igualmente y el documento renderiza solo a través de memoria

¿Qué pasa con las páginas cacheadas tras una edición?

Editar un documento cargado jamás borra nada de la caché de render en disco de HotPDF. La edición suelta en su lugar la identidad del documento, así que el resto de esa carga omite el nivel de disco, y las páginas guardadas siguen siendo 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 decodificarse, o un cambio de esquema

La clave describe un archivo en disco. En cuanto usted estampa una página o cambia una anotación, el documento en memoria ya no casa con ella, así que ni leer ni escribir bajo esa clave sería honesto. InvalidateRenderedPageCache y la invalidación por página que las ediciones disparan borran ambos la identidad y dejan la carpeta en paz. Un segundo check 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 lleva cambios sin guardar y, si lo lleva, trata el documento como sin identidad

Los ajustes de render van al revés. Asignar PageRenderBackend (lo que UseNativeGDIRenderBackend hace por usted), llamar a ConfigureRenderICCWorkflow o llamar a ClearRenderICCWorkflow vacía las páginas en memoria pero conserva la identidad, porque el documento sigue casando con su archivo. Esos ajustes cambian píxeles sin aparecer en la clave de memoria, así que la clave de disco incorpora el nombre del backend, el flag de compensación de punto negro y digests SHA-256 de los perfiles ICC de prueba y de 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

Semántica de invalidación de HotPDF para la caché de disco RenderCacheFolder: editar el documento cargado o cualquier objeto sucio suelta la identidad de fuente así que el nivel se omite, cambiar el backend de render o el flujo ICC conserva la identidad bajo una clave de variante nueva, y guardar más recargar recambia la clave del documento
una edición jamás borra la carpeta guardada, un cambio de ajustes renderiza bajo una clave distinta, y solo guardar más recargar le gana al documento editado una identidad fresca

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 de por defecto:

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 ajustes de render: esta página se lee
  // de o se escribe en una segunda carpeta, y la vista por defecto queda intacta
  Bmp := Pdf.RenderLoadedPageToBitmapCached(PageIndex, 150);
end;

Un documento editado vuelve al nivel de disco solo convirtiéndose en un archivo nuevo. Guárdelo y cargue el resultado:

procedure CommitEditsAndRekey(Pdf: THotPDF; const EditedFile: string);
begin
  // Tras 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 fecha de última escritura, de ahí 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 a través de RenderCacheMaxDocuments y RenderCacheMaxBytes como cualquier otra entrada. Reabra el original sin editar y sus páginas siguen allí

Fuentes cifradas, junctions y raíces compartidas

La 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 cambian aciertos 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 el disco, fuera de la protección que escogió su autor (ISO 32000-1 §7.6). HotPDF no captura identidad para ninguna fuente cuyo trailer lleve una entrada /Encrypt, ya se abriera con contraseña o con una contraseña de usuario vacía. Esos documentos siguen usando el nivel en memoria, que desaparece con el proceso

Las carpetas de documento enlazadas se saltan

La raíz de la caché la escoge usted, y apuntarla a un junction está bien. Las subcarpetas debajo son distintas: la caché las crea, toca y borra por su cuenta durante la limpieza de arranque, la búsqueda, el almacenamiento y los tres límites de expulsión. Si alguien con acceso de escritura a la raíz cambiara una carpeta de documento por un junction a otro directorio, cada una de esas operaciones lo seguiría, y la expulsión borraría archivos en otra parte. Cada punto de entrada lee primero los atributos de la carpeta y se salta todo lo marcado como reparse point. Una búsqueda cuenta un fallo, un almacenamiento cuenta un fallo de escritura, y la expulsión la deja en paz

Rutas Unicode y una raíz 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 code page del sistema (un nombre de usuario chino en una instalación de Windows en inglés, por ejemplo) llega a la caché intacta. Varias instancias THotPDF en un proceso que resuelvan a la misma raíz, comparada sin distinguir mayúsculas tras expandir la ruta, comparten un índice con recuento de referencias y un lock. Eso importa para los límites: copias separadas de index.txt aplicarían cada una el presupuesto de 500 MB contra una vista parcial y dejarían que la carpeta creciera varias veces por encima

El compartimiento termina en la frontera del proceso. Dos procesos sobre la misma raíz sostienen índices en memoria separados, así que cada aplicación corriendo en paralelo debería recibir su propia raíz. Los worker threads dentro de un proceso están bien: PrefetchLoadedPages y la cola de renderizado en segundo plano con una cola de peticiones pasan por el mismo camino cacheado y el mismo lock

Ajustes que dejar bien antes de despachar

  • Fije la carpeta y ambos límites antes del primer render cacheado, y para cargas por stream o de acceso aleatorio antes de cargar
  • Espere renderizado solo en memoria para PDFs cifrados, para documentos editados tras la carga, y siempre que RenderFallbackPolicy no esté en rfpIgnore
  • Dele a cada aplicación en ejecución su propia raíz de caché bajo una ubicación por usuario como %LOCALAPPDATA%

Una caché de páginas persistente se 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 a medida en Delphi de este blog. El nivel de disco, la caché raster en memoria y el renderer de páginas son todos parte del componente Delphi PDF de HotPDF, disponible para Delphi y C++Builder