Articolo tecnico

RenderCacheFolder HotPDF: cache di pagine su disco in Delphi

Una cache di pagine chiavata per nome file mostrerà le pagine di ieri per un PDF sovrascritto durante la notte con una nuova revisione sotto lo stesso nome. Una cache chiavata su una SHA-256 completa del file non commette mai quello sbaglio, ma su un archivio scansionato da 400 MB l'hash può costare più del renderizzare le due pagine che l'utente apre davvero. La chiave funzionante siede tra le due, e sceglierla costringe anche a una seconda decisione: cosa deve fare una modifica in memoria alle pagine già appoggiate su disco

Come il tier disco di RenderCacheFolder siede dietro la cache in memoria

HotPDF RenderCacheFolder aggiunge un tier persistente dietro la cache raster in memoria del componente HotPDF Delphi, e prende parte solo quando la proprietà contiene un percorso non vuoto. Una chiamata a RenderLoadedPageToBitmapCached(PageIndex, DPI) controlla prima la memoria, usando indice di pagina, DPI e le impostazioni di render correnti come chiave. Su un mancato, chiede al disco. Un successo dal disco decodifica il PNG conservato, lo promuove di nuovo in memoria e ti consegna una copia. Solo quando entrambi i tier mancano la pagina passa per l'intero renderer descritto in renderizzare una pagina PDF caricata in una TBitmap, e quel bitmap fresco viene scritto su disco durante l'uscita

Diagramma HotPDF della ricerca nella cache di render per RenderLoadedPageToBitmapCached: il tier in memoria indicizzato per pagina, DPI e variante di render viene controllato per primo, poi il tier disco RenderCacheFolder di file PNG con sostituzione atomica, poi l'interprete dei content stream, e ogni successo restituisce una copia di proprietà del chiamante
HotPDF guarda prima in memoria, poi su disco, e solo allora rasterizza; un successo dal disco viene promosso di nuovo in memoria e ogni via ti consegna una copia che possiedi e devi liberare

Il layout della cartella è abbastanza piatto da ispezionarlo in Explorer. Ogni documento riceve una sottocartella il cui nome combina una chiave documento di 16 caratteri esadecimali con una chiave di impostazioni di render di 16 caratteri esadecimali, e ogni pagina atterra lì come <page>@<dpi>.png. Un index.txt alla radice elenca i documenti in ordine di uso più recente sotto un tag di schema; se il tag non combacia, l'intera cartella viene svuotata al primo uso. Le scritture di PNG e indice vanno prima su un file temporaneo e poi vengono scambiate sul posto con MoveFileExW e il flag di sostituzione del file esistente, così un crash a metà scrittura lascia il file precedente oppure nessun file. Un PNG che non si decodifica viene cancellato e contato come mancato

Tre limiti impediscono alla cartella di crescere senza freno:

  • RenderCacheMaxDocuments (default 20) limita il numero di sottocartelle documento, espellendo prima quella usata meno di recente
  • RenderCacheMaxBytes (default 524288000, cioè 500 MB) limita la dimensione combinata di ogni PNG sotto la radice
  • Ogni cartella documento tiene al massimo 200 immagini di pagina; quel tetto è fisso dentro THotPDF e non ha una proprietà

RenderCacheCapacity (default 8) non c'entra nulla con il disco. Conta le pagine tenute in memoria

uses
  SysUtils, Graphics, HPDFDoc;

procedure WarmThumbnails(const FileName: string);
var
  Pdf: THotPDF;
  Bmp: TBitmap;
  I: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    // Il tier disco legge la cartella e entrambi i limiti una volta, al primo
    // render in cache, quindi impostateli prima di quella chiamata
    Pdf.RenderCacheFolder := IncludeTrailingPathDelimiter(
      GetEnvironmentVariable('LOCALAPPDATA')) + 'MyViewer\PageCache';
    Pdf.RenderCacheMaxDocuments := 50;
    Pdf.RenderCacheMaxBytes := Int64(1024) * 1024 * 1024; // 1 GiB
    Pdf.RenderCacheCapacity := 16;                        // pagine in 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
          // Passa la copia alla striscia di miniature qui
        finally
          Bmp.Free; // la chiamata in cache restituisce sempre una copia del chiamante
        end;
      end;
  finally
    Pdf.Free; // le voci su disco sopravvivono per la sessione successiva
  end;
end;

Esegui quella procedura due volte sullo stesso file e la seconda passata non rasterizza nulla che stia nei limiti. La cache disco viene creata al primo render in cache e vive quanto l'istanza THotPDF, quindi cambiare la cartella o uno dei due limiti dopo quel momento non la sposta né la ridimensiona. Altre due condizioni tengono una pagina fuori dal disco. Un bitmap sopra il tetto per voce di default della cache in memoria (64 MiB di pixel a 32 bit, una pagina 4096 × 4096) non viene conservato. E il tier disco viene consultato solo finché RenderFallbackPolicy resta al suo default rfpIgnore, dato che un PNG porta pixel ma nessuna delle diagnostiche di fallback che una politica più severa riporta

Perché le chiavi di cache ovvie falliscono?

Tre chiavi vengono in mente per prime, e ognuna fallisce in un modo diverso. Il percorso del file fallisce sulla sovrascrittura. Un hash di una copia in memoria dei byte del PDF sembra sicuro finché non noti che un parser che legge il file sul posto non ha alcun motivo di conservare una tale copia; fare l'hash di un buffer mai riempito produce una chiave vuota, e una cache che tratta una chiave vuota come "salta il disco" lascia una cartella correttamente configurata che non riceve mai un PNG. Fare l'hash dell'intero file dal disco funziona, al costo di leggere ogni byte a ogni apertura

La trappola più ostica è l'invalidazione. Un componente così deve azzerare le proprie pagine in memoria all'inizio di ogni caricamento, dopo ogni modifica e quando viene distrutto, e la mossa allettante è cancellare la cartella disco del documento nello stesso punto. Fallo e ogni sessione del viewer si cancella la propria cache all'uscita, così la mattina dopo riparte comunque fredda. Ricalcolare la chiave dalla sorgente invariata dopo una modifica è peggio ancora: i render modificati atterrano sotto la chiave del file originale e vengono serviti a chiunque apra dopo il PDF intatto. Identità e invalidazione vanno progettate come un pezzo unico. Sbagliane una delle due e spedisci una cache che non colpisce mai, o una che mostra pagine che il file non contiene

Come HotPDF impronta una sorgente PDF

HotPDF identifica un PDF caricato con LoadFromFile facendo l'hash della sua dimensione, del suo orario di ultima scrittura e dei suoi primi e ultimi 64 KiB con SHA-256, e identifica una sorgente stream o ad accesso casuale con una SHA-256 dell'intero contenuto. L'identità viene catturata una volta sola, quando un caricamento riesce, e i primi 16 caratteri esadecimali del digest (64 bit) diventano la chiave documento

SorgenteIdentitàCostoCatturata quando
LoadFromFileDimensione + orario di ultima scrittura + primi e ultimi 64 KiB, sottoposti a hash con SHA-256Al massimo 128 KiB letti, qualunque sia la dimensione del fileOgni caricamento riuscito, anche se RenderCacheFolder viene impostato dopo
LoadFromStreamSHA-256 dell'intero streamUn passaggio completo sulla sorgenteSolo se RenderCacheFolder era stato impostato prima del caricamento
LoadFromRandomAccessSourceSHA-256 dell'intera sorgenteUn passaggio completo sulla sorgenteSolo se la cartella era stata impostata prima e ogni intervallo di byte è disponibile
Qualsiasi sorgente con una voce /EncryptNessunaNessunoMai; il tier disco viene bypassato
Mappa dell'identità delle sorgenti per la cache di render su disco di HotPDF: LoadFromFile sottopone a hash dimensione, LastWriteTime e primi e ultimi 64 KiB, LoadFromStream e LoadFromRandomAccessSource sottopongono a hash l'intero contenuto solo quando RenderCacheFolder era impostato prima, e qualsiasi trailer /Encrypt non cattura alcuna identità
i file prendono l'impronta dalle proprie estremità perché header, xref e trailer vivono lì, gli stream pagano un hash completo solo quando hai chiesto prima la cache, e i documenti cifrati non vengono mai scritti su disco

Per un viewer desktop l'impronta campionata è il default giusto, e fare l'hash completo a ogni apertura è quello sbagliato. Le due regioni campionate sono state scelte dalla struttura del file. L'header sta all'inizio; il trailer e l'ultima sezione di riferimenti incrociati stanno alla fine (ISO 32000-1 §7.5). Un aggiornamento incrementale accoda un nuovo corpo, una nuova sezione di riferimenti incrociati e un nuovo trailer (§7.5.6), il che cambia insieme dimensione e coda, e qualsiasi ordinaria riscrittura completa cambia l'orario di ultima scrittura. Sotto i 128 KiB i due campioni si sovrappongono e coprono ogni byte, quindi i documenti piccoli vengono comunque sottoposti a hash per intero

Ciò che sfugge è una modifica alla stessa dimensione in mezzo a un file grande da parte di un tool che poi ripristina l'orario originale. Editor che preservano deliberatamente i tempi di modifica mentre cambiano il contenuto esistono, ma sono rari, e contro un file simile la cache serve pagine stantie. Il caso opposto gioca a tuo favore: una copia file su Windows conserva l'orario di ultima scrittura, quindi una copia di un documento in cache colpisce le stesse voci, il che è corretto dato che i byte combaciano

Uno stream non ha orario. Il contenuto è l'unica identità onesta, quindi HotPDF paga il passaggio SHA-256 completo solo quando una cache disco è stata richiesta prima del caricamento, e il codice che chiama LoadFromStream senza una cartella di cache non paga nulla in più. Questo rende l'ordine di due righe qualcosa che conta:

procedure OpenDownloadedPdf(Pdf: THotPDF; Data: TStream;
  const CacheRoot: string);
begin
  // Ordine sbagliato per gli stream: l'hash del contenuto viene calcolato solo
  // quando la cartella è già impostata, così questo documento bypasserebbe il tier disco
  //   Pdf.LoadFromStream(Data);
  //   Pdf.RenderCacheFolder := CacheRoot;

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

Una sorgente ad accesso casuale ancora in scaricamento non riceve nessuna identità anziché un hash degli intervalli arrivati fin lì. Se il calcolo dell'identità solleva per qualsiasi motivo, il caricamento riesce comunque e il documento renderizza solo attraverso la memoria

Cosa accade alle pagine in cache dopo una modifica?

Modificare un documento caricato non cancella mai nulla dalla cache disco di render di HotPDF. La modifica fa cadere l'identità del documento invece, così il resto di quel caricamento bypassa il tier disco, e le pagine conservate restano valide per il file non modificato da cui erano state renderizzate. Le voci lasciano il disco solo attraverso i limiti di documenti e byte, il tetto delle 200 pagine, un PNG che non si decodifica, o un cambio di schema

La chiave descrive un file su disco. Appena timbri una pagina o cambi un'annotazione, il documento in memoria non corrisponde più ad esso, quindi né leggere né scrivere sotto quella chiave sarebbe onesto. InvalidateRenderedPageCache e l'invalidazione per pagina che le modifiche innescano azzerano entrambe l'identità e lasciano la cartella in pace. Un secondo controllo copre i percorsi di modifica che non hanno mai invalidato nulla: prima di ogni ricerca su disco, THotPDF chiede se qualche oggetto caricato porta modifiche non salvate e, se ce n'è una, tratta il documento come privo di identità

Le impostazioni di render lavorano nell'altra direzione. Assegnare PageRenderBackend (cosa che UseNativeGDIRenderBackend fa per te), chiamare ConfigureRenderICCWorkflow o chiamare ClearRenderICCWorkflow svuota le pagine in memoria ma conserva l'identità, perché il documento continua a combaciare con il proprio file. Quelle impostazioni cambiano i pixel senza comparire nella chiave in memoria, quindi la chiave disco incorpora il nome del backend, il flag di compensazione del punto nero e i digest SHA-256 dei profili ICC di prova e di uscita. La chiave in memoria copre già l'intento di colore, il dithering di uscita, l'anteprima overprint, la modalità luminosity mask, la politica di fallback e la visibilità di ogni gruppo di contenuto opzionale

Semantica di invalidazione di HotPDF per la cache disco RenderCacheFolder: modificare il documento caricato o qualsiasi oggetto dirty fa cadere l'identità della sorgente così il tier viene bypassato, cambiare il backend di render o il workflow ICC conserva l'identità sotto una nuova chiave di variante, e salvare più ricaricare ridà una nuova chiave al documento
una modifica non cancella mai la cartella conservata, un cambio di impostazioni renderizza sotto una chiave diversa, e solo salvare più ricaricare fa guadagnare al documento modificato una identità fresca

La visibilità dei layer è un buon esempio di modifica che resta sul disco. SetLoadedOptionalContentGroupVisible registra l'override in memoria senza toccare alcun oggetto PDF, così il documento conserva la propria identità e la vista commutata renderizza nella propria sottocartella accanto a quella di 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);

  // Stessa chiave documento, diversa chiave impostazioni di render: questa pagina viene
  // letta da o scritta in una seconda cartella, e la vista di default resta intatta
  Bmp := Pdf.RenderLoadedPageToBitmapCached(PageIndex, 150);
end;

Un documento modificato torna sul tier disco solo diventando un file nuovo. Salvalo e carica il risultato:

procedure CommitEditsAndRekey(Pdf: THotPDF; const EditedFile: string);
begin
  // Dopo una modifica: rinfresca le pagine in memoria. L'identità della sorgente è
  // già andata, così la cartella del documento originale non viene né letta
  // né scritta
  Pdf.InvalidateRenderedPageCache;

  // Il file salvato ha la propria dimensione e il proprio last-write time, quindi la propria
  // identità; i render dopo questo caricamento finiscono in cache con la nuova chiave
  Pdf.SaveLoadedDocument(EditedFile);
  if Pdf.LoadFromFile(EditedFile) <= 0 then
    raise Exception.Create('Could not reload the edited document');
end;

La cartella del documento originale resta dov'era e invecchia attraverso RenderCacheMaxDocuments e RenderCacheMaxBytes come qualsiasi altra voce. Riapri l'originale non modificato e le sue pagine sono ancora lì

Sorgenti cifrate, junction e radici condivise

La cache disco di render di HotPDF rifiuta due input di proposito: le pagine di un PDF cifrato, e le sottocartelle documento che sono junction o altri reparse point. Entrambe le regole scambiano successi di cache per sicurezza

I PDF cifrati restano in memoria

Una pagina renderizzata è contenuto decifrato. Scriverla come PNG in chiaro in una cartella di cache lascerebbe sul disco una copia leggibile di un documento protetto da password, fuori dalla protezione che il suo autore ha scelto (ISO 32000-1 §7.6). HotPDF non cattura nessuna identità per qualsiasi sorgente il cui trailer porti una voce /Encrypt, che sia stata aperta con una password o con una password utente vuota. Quei documenti continuano a usare il tier in memoria, che sparisce con il processo

Le cartelle documento collegate vengono saltate

La radice della cache è una tua scelta, e puntarla a una junction va bene. Le sottocartelle sotto di lei sono un'altra storia: la cache le crea, ne tocca i tempi e le cancella per conto proprio durante la pulizia all'avvio, la ricerca, la conservazione e tutti e tre i limiti di espulsione. Se qualcuno con accesso in scrittura alla radice scambia una cartella documento con una junction verso un'altra directory, ognuna di quelle operazioni la seguirebbe, e l'espulsione cancellerebbe file altrove. Ogni punto d'ingresso legge prima gli attributi della cartella e salta tutto ciò che è marcato come reparse point. Una ricerca conta un mancato, una conservazione conta un fallimento di scrittura, e l'espulsione la lascia in pace

Percorsi Unicode e una radice per processo

RenderCacheFolder è una string Unicode, e la sostituzione atomica chiama la Windows API wide, così un percorso di profilo fuori dalla code page di sistema (un nome utente cinese su un'installazione Windows inglese, per dire) raggiunge la cache intatto. Diverse istanze THotPDF in un processo che risolvono alla stessa radice, confrontate senza distinzione di maiuscole dopo l'espansione del percorso, condividono un indice con reference counting e un lock. Questo conta per i limiti: copie separate di index.txt applicherebbero ognuna il budget di 500 MB alla propria vista parziale e lascerebbero la cartella crescere parecchie volte oltre

La condivisione finisce al confine del processo. Due processi sulla stessa radice tengono indici in memoria separati, quindi a ogni applicazione in esecuzione concorrente dai la propria radice. I worker thread dentro un processo stanno bene: PrefetchLoadedPages e la coda in render in background con una coda di richieste passano per la stessa via in cache e lo stesso lock

Impostazioni da azzeccare prima della consegna

  • Imposta la cartella e entrambi i limiti prima del primo render in cache, e per caricamenti da stream o ad accesso casuale prima del caricamento
  • Aspettati rendering solo in memoria per i PDF cifrati, per i documenti modificati dopo il caricamento, e ogni volta che RenderFallbackPolicy non è rfpIgnore
  • Dai a ogni applicazione in esecuzione la propria radice di cache sotto una posizione per utente come %LOCALAPPDATA%

Una cache di pagine persistente si guadagna il proprio spazio disco in un viewer che riapre gli stessi documenti tutto il giorno, che è il carico di lavoro dietro l'architettura di un viewer PDF personalizzato in Delphi su questo blog. Il tier disco, la cache raster in memoria e il renderer di pagine fanno tutti parte dell'HotPDF Delphi PDF component, disponibile per Delphi e C++Builder