Technischer Artikel

HotPDF RenderCacheFolder: Ein Disk-Seitencache in Delphi

Ein Seitencache, der über den Dateinamen läuft, zeigt für ein PDF, das über Nacht unter gleichem Namen mit einer neuen Revision überschrieben wurde, die Seiten von gestern. Ein Cache über einen vollen SHA-256 der Datei macht diesen Fehler nie, aber bei einem 400-MB-Scan-Archiv kann der Hash länger dauern als das Rendern der zwei Seiten, die der Nutzer tatsächlich öffnet. Der brauchbare Schlüssel sitzt zwischen beiden, und seine Wahl erzwingt eine zweite Entscheidung: was eine Bearbeitung im Speicher mit Seiten anfangen soll, die bereits auf der Disk liegen

Wie die RenderCacheFolder-Disk-Ebene hinter dem Speicher-Cache sitzt

HotPDF RenderCacheFolder ergänzt eine persistente Ebene hinter dem Raster-Cache im Speicher der HotPDF-Delphi-Komponente und spielt nur mit, wenn die Eigenschaft einen nicht leeren Pfad hält. Ein Aufruf von RenderLoadedPageToBitmapCached(PageIndex, DPI) prüft zuerst den Speicher, mit Seitenindex, DPI und den aktuellen Render-Einstellungen als Schlüssel. Bei einem Miss fragt er die Disk. Ein Disk-Treffer dekodiert das gespeicherte PNG, befördert es zurück in den Speicher und reicht Ihnen eine Kopie. Erst wenn beide Ebenen missen, läuft die Seite durch den vollen Renderer, beschrieben in das Rendern einer geladenen PDF-Seite in ein TBitmap, und diese frische Bitmap wird auf dem Weg hinaus auf die Disk geschrieben

HotPDF-Diagramm des Render-Cache-Lookups für RenderLoadedPageToBitmapCached: die im Speicher liegende, nach Seite, DPI und Render-Variante verschlüsselte Ebene wird zuerst geprüft, dann die RenderCacheFolder-Disk-Ebene aus PNG-Dateien mit atomarem Ersetzen, dann der Content-Stream-Interpreter, und jeder Treffer liefert eine Kopie in Aufruferbesitz
HotPDF schaut zuerst in den Speicher, dann auf die Disk und rastert erst danach; ein Disk-Treffer wird zurück in den Speicher befördert, und jeder Pfad gibt Ihnen eine Kopie, die Ihnen gehört und die Sie freigeben müssen

Das Ordner-Layout ist schlicht genug, um es im Explorer anzuschauen. Jedes Dokument bekommt einen Unterordner, dessen Name einen 16-Hex-Zeichen-Dokumentschlüssel mit einem 16-Hex-Zeichen-Render-Einstellungen-Schlüssel kombiniert, und jede Seite landet dort als <page>@<dpi>.png. Eine index.txt an der Wurzel listet Dokumente in Zuletzt-verwendet-Reihenfolge unter einem Schema-Tag; passt das Tag nicht, wird der ganze Ordner bei der ersten Benutzung geleert. PNG- und Index-Schreiben gehen zuerst in eine temporäre Datei und werden dann mit MoveFileExW und dem Replace-Existing-Flag eingetauscht, ein Crash mitten im Schreiben lässt also die vorherige Datei oder keine Datei zurück. Ein PNG, das sich nicht dekodieren lässt, wird gelöscht und als Miss gezählt

Drei Limits halten den Ordner davon ab, unbegrenzt zu wachsen:

  • RenderCacheMaxDocuments (Voreinstellung 20) kappt die Anzahl der Dokument-Unterordner und räumt den am längsten nicht benutzten zuerst weg
  • RenderCacheMaxBytes (Voreinstellung 524288000, also 500 MB) kappt die kombinierte Größe aller PNGs unter der Wurzel
  • Jeder Dokumentordner hält höchstens 200 Seitenbilder; diese Kappe sitzt fest in THotPDF und hat keine Eigenschaft

RenderCacheCapacity (Voreinstellung 8) hat nichts mit der Disk zu tun. Er zählt Seiten im Speicher

uses
  SysUtils, Graphics, HPDFDoc;

procedure WarmThumbnails(const FileName: string);
var
  Pdf: THotPDF;
  Bmp: TBitmap;
  I: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    // Die Disk-Ebene liest Ordner und beide Limits einmal, beim ersten
    // gecachten Render, also vor diesem Aufruf setzen
    Pdf.RenderCacheFolder := IncludeTrailingPathDelimiter(
      GetEnvironmentVariable('LOCALAPPDATA')) + 'MyViewer\PageCache';
    Pdf.RenderCacheMaxDocuments := 50;
    Pdf.RenderCacheMaxBytes := Int64(1024) * 1024 * 1024; // 1 GiB
    Pdf.RenderCacheCapacity := 16;                        // Seiten im Speicher

    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
          // Die Kopie hier an die Thumbnail-Leiste weitergeben
        finally
          Bmp.Free; // der gecachte Aufruf liefert stets eine Kopie in Aufruferbesitz
        end;
      end;
  finally
    Pdf.Free; // Disk-Einträge überleben bis zur nächsten Sitzung
  end;
end;

Führen Sie diese Prozedur zweimal auf derselben Datei aus, rastert der zweite Durchlauf nichts, was in die Limits passte. Der Disk-Cache entsteht beim ersten gecachten Render und lebt so lang wie die THotPDF-Instanz, den Ordner oder eines der Limits danach zu ändern verschiebt oder vergrößert ihn also nicht. Zwei weitere Bedingungen halten eine Seite von der Disk fern. Eine Bitmap über der Default-Eintrittsdecke des Speicher-Caches (64 MiB an 32-Bit-Pixeln, eine 4096 × 4096-Seite) wird nicht gespeichert. Und die Disk-Ebene wird nur befragt, solange RenderFallbackPolicy auf ihrer Voreinstellung rfpIgnore bleibt, denn ein PNG trägt Pixel, aber keine der Fallback-Diagnosen, die eine strengere Policy meldet

Warum scheitern die naheliegenden Cache-Schlüssel?

Drei Schlüssel kommen einem zuerst in den Sinn, und jeder scheitert auf seine Art. Der Dateipfad scheitert am Überschreiben. Ein Hash über eine Kopie der PDF-Bytes im Speicher sieht sicher aus, bis einem auffällt, dass ein Parser, der die Datei an Ort und Stelle liest, keinen Grund hat, so eine Kopie zu halten; einen nie gefüllten Buffer zu hashen ergibt einen leeren Schlüssel, und ein Cache, der einen leeren Schlüssel als „Disk überspringen" liest, hinterlässt einen korrekt konfigurierten Ordner, der nie ein PNG empfängt. Die ganze Datei von der Disk zu hashen funktioniert, zum Preis, bei jedem Öffnen jedes Byte zu lesen

Die härtere Falle ist die Invalidierung. So eine Komponente muss ihre Speicherseiten am Anfang jedes Ladens, nach jeder Bearbeitung und beim Zerstören leeren, und der verführende Zug ist, den Disk-Ordner des Dokuments an denselben Stellen zu löschen. Tut man das, wischt jede Viewer-Sitzung beim Verlassen ihren eigenen Cache weg, der nächste Morgen startet also trotzdem kalt. Den Schlüssel nach einer Bearbeitung aus der unveränderten Quelle neu zu berechnen ist noch schlimmer: Die bearbeiteten Renderungen landen unter dem Schlüssel der Originaldatei und werden dem ausgeliefert, der als Nächstes das unveränderte PDF öffnet. Identität und Invalidierung müssen als ein Stück entworfen werden. Nehmen Sie eines davon falsch vor, und Sie liefern einen Cache aus, der nie trifft, oder einen, der Seiten zeigt, die die Datei nicht enthält

Wie HotPDF eine PDF-Quelle fingerabdruckt

HotPDF identifiziert ein mit LoadFromFile geladenes PDF über den SHA-256-Hash aus Größe, Zeit des letzten Schreibens und den ersten und letzten 64 KiB, und einen Stream oder eine Random-Access-Quelle über einen SHA-256 des gesamten Inhalts. Die Identität wird einmal erfasst, wenn ein Laden gelingt, und die ersten 16 Hex-Zeichen des Digests (64 Bits) werden der Dokumentschlüssel

QuelleIdentitätKostenErfasst, wenn
LoadFromFileGröße + LastWriteTime + führende und abschließende 64 KiB, gehasht mit SHA-256Höchstens 128 KiB gelesen, unabhängig von der DateigrößeJeder erfolgreiche Ladevorgang, selbst wenn RenderCacheFolder erst später gesetzt wird
LoadFromStreamSHA-256 über den ganzen StreamEin voller Durchlauf über die QuelleNur wenn RenderCacheFolder vor dem Laden gesetzt war
LoadFromRandomAccessSourceSHA-256 über die ganze QuelleEin voller Durchlauf über die QuelleNur wenn der Ordner zuerst gesetzt war und die ganze Range verfügbar ist
Jede Quelle mit einem /Encrypt-EintragKeineKeineNie; die Disk-Ebene wird umgangen
HotPDF-Quellidentitäts-Map für den Disk-Render-Cache: LoadFromFile hasht Größe, LastWriteTime und das erste und letzte 64 KiB, LoadFromStream und LoadFromRandomAccessSource hashen den ganzen Inhalt nur, wenn RenderCacheFolder zuerst gesetzt war, und jeder /Encrypt-Trailer erfasst überhaupt keine Identität
Dateien werden an ihren Enden fingerabdruckt, weil Header, xref und Trailer dort leben, Streams zahlen nur für einen vollen Hash, wenn Sie den Cache zuerst angefragt haben, und verschlüsselte Dokumente werden nie auf die Disk geschrieben

Für einen Desktop-Viewer ist der gestrichelte Fingerabdruck der richtige Default, und volles Hashen bei jedem Öffnen ist der falsche. Die beiden gestrichelten Regionen wurden aus der Dateistruktur gewählt. Der Header sitzt am Anfang; Trailer und die letzte Cross-Reference-Sektion sitzen am Ende (ISO 32000-1 §7.5). Ein inkrementelles Update hängt einen neuen Body, eine neue Cross-Reference-Sektion und einen neuen Trailer an (§7.5.6), was Größe und Ende gemeinsam ändert, und jede gewöhnliche Voll-Rewrite hebt die Zeit des letzten Schreibens. Unter 128 KiB überlappen sich die beiden Samples und decken jedes Byte, kleine Dokumente werden also ohnehin vollständig gehasht

Durchrutschen kann eine gleich große Bearbeitung mitten in einer großen Datei, ausgeführt von einem Werkzeug, das danach den ursprünglichen Zeitstempel wiederherstellt. Editoren, die Änderungszeiten bewusst wahren, während sie den Inhalt ändern, existieren, sind aber selten, und gegen so eine Datei liefert der Cache veraltete Seiten. Der entgegengesetzte Fall spielt für Sie: Eine Windows-Dateikopie erhält die Zeit des letzten Schreibens, eine Kopie eines gecachten Dokuments trifft also dieselben Einträge, was korrekt ist, weil die Bytes übereinstimmen

Ein Stream hat keinen Zeitstempel. Der Inhalt ist die einzige ehrliche Identität, HotPDF zahlt den vollen SHA-256-Durchlauf also nur, wenn vor dem Laden ein Disk-Cache angefragt wurde, und Code, der LoadFromStream ohne Cache-Ordner ruft, zahlt nichts extra. Damit wird die Reihenfolge zweier Zeilen wichtig:

procedure OpenDownloadedPdf(Pdf: THotPDF; Data: TStream;
  const CacheRoot: string);
begin
  // Falsche Reihenfolge für Streams: Der Content-Hash wird nur berechnet, wenn
  // der Ordner bereits gesetzt ist, dieses Dokument würde die Disk-Ebene also umgehen
  //   Pdf.LoadFromStream(Data);
  //   Pdf.RenderCacheFolder := CacheRoot;

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

Eine Random-Access-Quelle, die noch lädt, bekommt gar keine Identität statt eines Hashs über die Ranges, die bisher angekommen sind. Wirft das Berechnen der Identität aus irgendeinem Grund eine Exception, gelingt das Laden trotzdem, und das Dokument rendert nur durch den Speicher

Was passiert mit gecachten Seiten nach einer Bearbeitung?

Das Bearbeiten eines geladenen Dokuments löscht nie etwas aus dem HotPDF-Disk-Render-Cache. Die Bearbeitung verwirft stattdessen die Identität des Dokuments, der Rest dieses Ladens umgeht also die Disk-Ebene, und die gespeicherten Seiten bleiben gültig für die unveränderte Datei, aus der sie gerendert wurden. Einträge verlassen die Disk nur über die Dokument- und Byte-Limits, die 200-Seiten-Kappe, ein PNG, das sich nicht dekodieren lässt, oder eine Schema-Änderung

Der Schlüssel beschreibt eine Datei auf der Disk. Stempelt man eine Seite oder ändert eine Annotation, passt das Dokument im Speicher nicht mehr dazu, unter diesem Schlüssel zu lesen oder zu schreiben wäre also nicht ehrlich. InvalidateRenderedPageCache und die pro Seite gültigmachende Invalidierung, die Bearbeitungen auslösen, räumen beide die Identität weg und lassen den Ordner in Ruhe. Eine zweite Prüfung deckt Bearbeitungswege ab, die nie etwas ungültig gemacht haben: Vor jedem Disk-Lookup fragt THotPDF, ob ein geladenes Objekt ungespeicherte Änderungen trägt, und wenn ja, behandelt es das Dokument als ohne Identität

Render-Einstellungen laufen in die andere Richtung. PageRenderBackend zuzuweisen (was UseNativeGDIRenderBackend für Sie erledigt), ConfigureRenderICCWorkflow oder ClearRenderICCWorkflow zu rufen, spült die Seiten im Speicher, behält aber die Identität, denn das Dokument passt weiterhin zu seiner Datei. Diese Einstellungen ändern Pixel, ohne im Speicherschlüssel aufzutauchen, der Disk-Schlüssel faltet also den Backend-Namen, das Black-Point-Compensation-Flag und SHA-256-Digests der ICC-Proof- und Output-Profile ein. Der Speicherschlüssel deckt bereits Color-Intent, Output-Dithering, Overprint-Preview, Luminosity-Mask-Modus, Fallback-Policy und die Sichtbarkeit jeder Optional-Content-Gruppe ab

HotPDF-Invalidierungssemantik für den RenderCacheFolder-Disk-Cache: Das Editieren des geladenen Dokuments oder eines dirty Objekts verwirft die Quellidentität, die Stufe wird also umgangen, das Wechseln des Render-Backends oder des ICC-Workflows behält die Identität unter einem neuen Variantenschlüssel, und Speichern plus Neuladen verpasst dem Dokument einen neuen Schlüssel
Eine Bearbeitung löscht nie den gespeicherten Ordner, eine Einstellungsänderung rendert unter einem anderen Schlüssel, und nur Speichern plus Neuladen verschafft dem editierten Dokument eine frische Identität

Layer-Sichtbarkeit ist ein gutes Beispiel für eine Änderung, die auf der Disk bleibt. SetLoadedOptionalContentGroupVisible vermerkt die Übersteuerung im Speicher, ohne ein PDF-Objekt anzufassen, das Dokument behält also seine Identität, und die umgeschaltete Ansicht rendert in ihren eigenen Unterordner neben dem 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);

  // Derselbe Dokument-Schlüssel, anderer Render-Einstellungen-Schlüssel: diese Seite
  // wird aus einem zweiten Ordner gelesen oder hineingeschrieben, die Default-Ansicht bleibt unangetastet
  Bmp := Pdf.RenderLoadedPageToBitmapCached(PageIndex, 150);
end;

Ein editiertes Dokument kommt nur als neue Datei wieder auf die Disk-Ebene. Speichern Sie es und laden Sie das Ergebnis:

procedure CommitEditsAndRekey(Pdf: THotPDF; const EditedFile: string);
begin
  // Nach dem Editieren des geladenen Dokuments: die Speicherseiten auffrischen.
  // Die Quellidentität ist bereits weg, aus dem Disk-Ordner des Originaldokuments
  // wird also nichts gelesen oder hineingeschrieben
  Pdf.InvalidateRenderedPageCache;

  // Eine gespeicherte Datei hat neue Größe und Last-Write-Zeit, also eine
  // neue Identität; Rendern nach diesem Laden werden unter dem neuen Schlüssel gecacht
  Pdf.SaveLoadedDocument(EditedFile);
  if Pdf.LoadFromFile(EditedFile) <= 0 then
    raise Exception.Create('Could not reload the edited document');
end;

Der Ordner des Originaldokuments bleibt, wo er war, und altert über RenderCacheMaxDocuments und RenderCacheMaxBytes aus wie jeder andere Eintrag. Öffnen Sie das unbearbeitete Original erneut, seine Seiten liegen noch dort

Verschlüsselte Quellen, Junctions und geteilte Wurzeln

Der HotPDF-Disk-Render-Cache weist zwei Eingaben mit Absicht zurück: Seiten eines verschlüsselten PDFs und Dokument-Unterordner, die Junctions oder andere Reparse Points sind. Beide Regeln tauschen Cache-Treffer gegen Sicherheit

Verschlüsselte PDFs bleiben im Speicher

Eine gerenderte Seite ist entschlüsselter Inhalt. Sie als nacktes PNG in einen Cache-Ordner zu schreiben würde eine lesbare Kopie eines passwortgeschützten Dokuments auf der Disk hinterlassen, außerhalb des Schutzes, den sein Autor gewählt hat (ISO 32000-1 §7.6). HotPDF erfasst für keine Quelle eine Identität, deren Trailer einen /Encrypt-Eintrag trägt, ob mit Passwort geöffnet oder mit leerem User-Passwort. Diese Dokumente nutzen weiter die Speicher-Ebene, die mit dem Prozess verschwindet

Verlinkte Dokumentordner werden übersprungen

Die Cache-Wurzel ist Ihre Wahl, auf eine Junction zu zeigen ist in Ordnung. Die Unterordner darunter sind etwas anderes: Der Cache erzeugt, berührt und löscht sie selbst während der Aufräumaktion beim Start, bei Lookup, Speichern und allen drei Eviction-Limits. Tauscht jemand mit Schreibrecht an der Wurzel einen Dokumentordner gegen eine Junction in ein anderes Verzeichnis, folgte jede dieser Operationen ihr hin, und die Eviction würde Dateien anderswo löschen. Jeder Einstiegspunkt liest zuerst die Attribute des Ordners und überspringt alles, was als Reparse Point markiert ist. Ein Lookup zählt einen Miss, ein Speichern zählt einen Schreibfehler, und die Eviction lässt es in Ruhe

Unicode-Pfade und eine Wurzel pro Prozess

RenderCacheFolder ist ein Unicode-string, und die atomaren Replace-Aufrufe gehen über die weite Windows-API, ein Profilpfad außerhalb der System-Codepage (etwa ein chinesischer Nutzername auf einer englischen Windows-Installation) erreicht den Cache also intakt. Mehrere THotPDF-Instanzen in einem Prozess, die auf dieselbe Wurzel auflösen — case-insensitiv verglichen nach Pfad-Auflösung —, teilen sich einen referenzzählten Index und ein Lock. Das zählt für die Limits: Getrennte Kopien der index.txt würden jede das 500-MB-Budget gegen eine Teilansicht durchsetzen lassen und den Ordner um ein Mehrfaches darüber hinaus wachsen lassen

Teilen endet an der Prozessgrenze. Zwei Prozesse auf derselben Wurzel halten getrennte Indizes im Speicher, jede gleichzeitig laufende Anwendung sollte also ihre eigene Wurzel bekommen. Worker-Threads in einem Prozess sind in Ordnung: PrefetchLoadedPages und die Queue aus Hintergrund-Rendering mit einer Request-Queue laufen über denselben gecachten Pfad und dasselbe Lock

Einstellungen, die vor dem Ausliefern sitzen müssen

  • Ordner und beide Limits vor dem ersten gecachten Render setzen, bei Stream- oder Random-Access-Laden vor dem Laden
  • Einrechnen, dass nur im Speicher gerendert wird für verschlüsselte PDFs, für nach dem Laden editierte Dokumente und immer dann, wenn RenderFallbackPolicy nicht auf rfpIgnore steht
  • Jeder laufenden Anwendung ihre eigene Cache-Wurzel unter einem nutzerspezifischen Ort wie %LOCALAPPDATA% geben

Ein persistenter Seitencache zahlt seinen Plattenplatz in einem Viewer ein, der dieselben Dokumente den ganzen Tag wieder öffnet — das ist die Workload hinter der Custom-PDF-Viewer-Architektur in Delphi auf diesem Blog. Die Disk-Ebene, der Speicher-Raster-Cache und der Seitenrenderer sind alle Teil der HotPDF Delphi PDF Component, erhältlich für Delphi und C++Builder