Artykuł techniczny

HotPDF RenderCacheFolder: cache stron PDF na dysku w Delphi

Cache stron kluczowany nazwą pliku pokaże wczorajsze strony dla PDF nadpisanej nocą nową rewizją pod tą samą nazwą. Cache kluczowany pełnym SHA-256 pliku nigdy nie zrobi tej pomyłki, ale przy 400 MB zeskanowanym archiwum hash może zająć dłużej niż wyrenderowanie dwóch stron, które użytkownik faktycznie otwiera. Pracowity klucz siedzi między tymi dwoma, a jego wybór wymusza też drugą decyzję: co edycja w pamięci powinna zrobić ze stronami już siedzącymi na dysku

Jak dyskowa warstwa RenderCacheFolder siedzi za cache'em w pamięci

HotPDF RenderCacheFolder dokłada trwałą warstwę za rasterowym cache w pamięci komponentu HotPDF Delphi i bierze udział tylko, gdy właściwość trzyma niepustą ścieżkę. Wywołanie RenderLoadedPageToBitmapCached(PageIndex, DPI) sprawdza najpierw pamięć, używając indeksu strony, DPI i bieżących ustawień renderowania jako klucza. Przy chybieniu pyta dysk. Trafienie dyskowe dekoduje przechowany PNG, awansuje go z powrotem do pamięci i wręcza Ci kopię. Dopiero gdy obie warstwy chybią, strona przechodzi przez pełny renderer opisany w renderowaniu załadowanej strony PDF do TBitmap, i ta świeża bitmapa jest zapisywana na dysk przy wyjściu

Diagram HotPDF wyszukiwania w cache renderowania dla RenderLoadedPageToBitmapCached: najpierw sprawdzana jest warstwa w pamięci kluczowana stroną, DPI i wariantem renderowania, potem dyskowa warstwa RenderCacheFolder z plikami PNG i atomową podmianą, na końcu interpreter strumienia treści, a każde trafienie zwraca kopię należącą do wołającego
HotPDF zagląda najpierw do pamięci, potem na dysk i dopiero wtedy rasteryzuje; trafienie na dysku wraca do pamięci, a każda ścieżka wręcza ci kopię, która jest twoja i którą musisz zwolnić

Układ folderu jest prosty na tyle, by objrzeć go w Explorerze. Każdy dokument dostaje podfolder, którego nazwa składa 16-znakowy hex klucz dokumentu z 16-znakowym hex kluczem ustawień renderowania, i każda strona ląduje tam jako <page>@<dpi>.png. index.txt przy korzeniu wypisuje dokumenty w kolejności ostatnio używanych pod tagiem schematu; jeśli tag nie pasuje, cały folder jest czyszczony przy pierwszym użyciu. Zapisy PNG i indeksu idą najpierw do pliku tymczasowego, po czym są podmieniane przez MoveFileExW z flagą zamiany istniejącego, więc crash w połowie zapisu zostawia poprzedni plik albo żaden. PNG, który nie chce się zdekodować, jest kasowany i liczony jako chybienie

Trzy limity trzymają folder przed rośnięciem bez granic:

  • RenderCacheMaxDocuments (domyślnie 20) ogranicza liczbę podfolderów dokumentów, wysiedlając najpierw najdawniej użyty
  • RenderCacheMaxBytes (domyślnie 524288000, czyli 500 MB) ogranicza łączny rozmiar wszystkich PNG pod korzeniem
  • Każdy folder dokumentu trzyma najwyżej 200 obrazów stron; ten sufit jest zaszyty w THotPDF i nie ma właściwości

RenderCacheCapacity (domyślnie 8) nie ma nic do dysku. Liczy strony trzymane w pamięci

uses
  SysUtils, Graphics, HPDFDoc;

procedure WarmThumbnails(const FileName: string);
var
  Pdf: THotPDF;
  Bmp: TBitmap;
  I: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    // Warstwa dyskowa czyta folder i oba limity raz, przy pierwszym
    // cacheowanym renderze, więc ustaw je przed tym wywołaniem
    Pdf.RenderCacheFolder := IncludeTrailingPathDelimiter(
      GetEnvironmentVariable('LOCALAPPDATA')) + 'MyViewer\PageCache';
    Pdf.RenderCacheMaxDocuments := 50;
    Pdf.RenderCacheMaxBytes := Int64(1024) * 1024 * 1024; // 1 GiB
    Pdf.RenderCacheCapacity := 16;                        // strony w pamięci

    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
          // Wręcz kopię paskowi miniatur tutaj
        finally
          Bmp.Free; // cacheowane wywołanie zawsze zwraca kopię należącą do wołającego
        end;
      end;
  finally
    Pdf.Free; // wpisy dyskowe przeżywają do następnej sesji
  end;
end;

Odpal tę procedurę dwa razy na tym samym pliku, a drugi przebieg nie rasteryzuje niczego, co mieści się w limitach. Dyskowy cache jest tworzony przy pierwszym cacheowanym renderze i żyje tak długo, jak instancja THotPDF, więc zmiana folderu albo któregokolwiek limitu po tej chwili go nie przenosi ani nie przemieszcza. Dwa dalsze warunki trzymają stronę z dala od dysku. Bitmapa powyżej domyślnego sufitu per wpis cache'a pamięci (64 MiB pikseli 32-bit, strona 4096 × 4096) nie jest przechowywana. I warstwa dyskowa jest konsultowana tylko, dopóki RenderFallbackPolicy zostaje na domyślnym rfpIgnore, bo PNG niesie piksele, ale żadnej z diagnostyk fallbacku, które surowsza polityka raportuje

Czemu oczywiste klucze cache padają?

Trzy klucze przychodzą do głowy pierwsze i każdy pada inaczej. Ścieżka pliku pada przy nadpisaniu. Hash kopii w pamięci bajtów PDF wygląda bezpiecznie, dopóki nie zauważysz, że parser czytający plik na miejscu nie ma powodu trzymać taką kopię; hashowanie bufora, który nigdy nie został wypełniony, daje pusty klucz, a cache traktujący pusty klucz jako „omiń dysk” zostawia poprawnie skonfigurowany folder, który nigdy nie dostaje PNG. Hashowanie całego pliku z dysku działa, za koszt czytania każdego bajtu przy każdym otwarciu

Trudniejsza pułapka to unieważnianie. Komponent taki musi czyścić swoje strony w pamięci na starcie każdego wczytania, po każdej edycji i przy swojej destrukcji, a kuszącym ruchem jest skasowanie dyskowego folderu dokumentu w tym samym miejscu. Zrób to, a każda sesja przeglądarki wyciera własny cache przy wyjściu, więc następnego ranka i tak startuje się na zimno. Przeliczanie klucza z niezmienionego źródła po edycji jest jeszcze gorsze: zedytowane rendery lądują pod kluczem oryginalnego pliku i są serwowane temu, kto następny otworze nietknięty PDF. Tożsamość i unieważnianie muszą być zaprojektowane jako jedna całość. Pomyłka w którejkolwiek wysyła cache, który nigdy nie trafia, albo taki, który pokazuje stron, których plik nie zawiera

Jak HotPDF odciska PDF źródła

HotPDF identyfikuje PDF wczytany przez LoadFromFile, hashując jego rozmiar, czas ostatniego zapisu i pierwsze oraz ostatnie 64 KiB przez SHA-256, a stream albo źródło o dostępie losowym identyfikuje przez SHA-256 całej treści. Tożsamość jest przechwytywana raz, gdy wczytanie się uda, a pierwsze 16 znaków hex skrótu (64 bity) staje się kluczem dokumentu

ŹródłoTożsamośćKosztPrzechwytywane kiedy
LoadFromFileRozmiar + czas ostatniego zapisu + pierwsze i ostatnie 64 KiB, haszowane SHA-256Najwyżej 128 KiB odczytu, cokolwiek rozmiaru plikuKażde udane wczytanie, nawet gdy RenderCacheFolder zostanie ustawiony później
LoadFromStreamSHA-256 całego streamaJeden pełny przebieg po źródleTylko, jeśli RenderCacheFolder był ustawiony przed wczytaniem
LoadFromRandomAccessSourceSHA-256 całego źródłaJeden pełny przebieg po źródleTylko, jeśli folder był ustawiony najpierw i każdy zakres bajtów jest dostępny
Dowolne źródło z wpisem /EncryptBrakBrakNigdy; warstwa dyskowa jest omijana
Mapa tożsamości źródeł dla dyskowego cache renderowania w HotPDF: LoadFromFile hashuje rozmiar, LastWriteTime i pierwsze oraz ostatnie 64 KiB, LoadFromStream i LoadFromRandomAccessSource hashują całą treść tylko, gdy RenderCacheFolder był ustawiony najpierw, a każdy trailer z /Encrypt nie przechwytuje żadnej tożsamości
pliki dostają odcisk palca ze swoich końców, bo tam mieszkają nagłówek, xref i trailer, strumienie płacą za pełny hash tylko, gdy najpierw poprosisz o cache, a dokumenty zaszyfrowane nigdy nie lądują na dysku

Dla desktopowej przeglądarki próbkowany odcisk palca to właściwy domyślny wybór, a pełne hashowanie przy każdym otwarciu to niewłaściwy. Dwa próbkowane regiony zostały wybrane ze struktury pliku. Nagłówek siedzi na starcie; trailer i ostatnia sekcja odsyłaczy krzyżowych siedzą na końcu (ISO 32000-1 §7.5). Aktualizacja przyrostowa dokleja nowe ciało, sekcję odsyłaczy i trailer (§7.5.6), co zmienia razem rozmiar i ogon, a każdy zwykły pełny zapis podbija czas ostatniego zapisu. Poniżej 128 KiB dwie próbki nachodzą na siebie i pokrywają każdy bajt, więc małe dokumenty i tak są haszowane w całości

Prześlizguje się edycja tej samej wielkości w środku dużego pliku, zrobiona przez narzędzie, które potem odtwarza oryginalny znacznik czasu. Edytory celowo zachowujące czasy modyfikacji przy zmianie treści istnieją, ale są rzadkie, i przeciwko takiemu plikowi cache serwuje stare strony. Przeciwny przypadek gra na Twoją korzyść: windowsowa kopia pliku trzyma czas ostatniego zapisu, więc kopia cache'owanego dokumentu trafia w te same wpisy, co jest poprawne, bo bajty się zgadzają

Stream nie ma znacznika czasu. Treść to jedyna uczciwa tożsamość, więc HotPDF płaci za pełny przebieg SHA-256 tylko, gdy dyskowy cache został poproszony przed wczytaniem, a kod wołający LoadFromStream bez folderu cache nie płaci nic ponad. To sprawia, że kolejność dwóch linii ma znaczenie:

procedure OpenDownloadedPdf(Pdf: THotPDF; Data: TStream;
  const CacheRoot: string);
begin
  // Zła kolejność dla strumieni: hash treści jest liczony tylko, gdy
  // folder jest już ustawiony, więc ten dokument ominąłby warstwę dyskową
  //   Pdf.LoadFromStream(Data);
  //   Pdf.RenderCacheFolder := CacheRoot;

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

Źródło o dostępie losowym, które wciąż się pobiera, nie dostaje żadnej tożsamości zamiast hasha tego, jakie zakresy dotarły. Jeśli liczenie tożsamości rzuci z jakiegokolwiek powodu, wczytanie nadal się udaje i dokument renderuje się wyłącznie przez pamięć

Co się dzieje z cache'owanymi stronami po edycji?

Edytowanie załadowanego dokumentu nigdy niczego nie kasuje z dyskowego cache renderowania HotPDF. Edycja zrzuca tożsamość dokumentu, więc reszta tego wczytania omija warstwę dyskową, a przechowane strony pozostają ważne dla niezmodyfikowanego pliku, z którego zostały wyrenderowane. Wpisy schodzą z dysku wyłącznie przez limity dokumentów i bajtów, sufit 200 stron, PNG, który nie chce się zdekodować, albo zmianę schematu

Klucz opisuje plik na dysku. Skoro ostemplujesz stronę albo zmienisz adnotację, dokument w pamięci przestaje mu odpowiadać, więc ani czytanie, ani pisanie pod tym kluczem nie byłoby uczciwe. InvalidateRenderedPageCache i per-stronicowe unieważnianie wyzwalane edycjami oba czyszczą tożsamość i zostawiają folder w spokoju. Druga kontrola pokrywa ścieżki edycji, które niczego nie unieważniły: przed każdym lookupem dyskowym THotPDF pyta, czy którykolwiek załadowany obiekt niesie niezapisane zmiany, i jeśli tak, traktuje dokument jako bez tożsamości

Ustawienia renderowania idą w drugą stronę. Przypisanie PageRenderBackend (co robi za Ciebie UseNativeGDIRenderBackend), wołanie ConfigureRenderICCWorkflow albo ClearRenderICCWorkflow wypłukuje strony w pamięci, ale trzyma tożsamość, bo dokument nadal odpowiada swojemu plikowi. Te ustawienia zmieniają piksele, nie pojawiając się w kluczu pamięci, więc klucz dyskowy składa w sobie nazwę backendu, flagę kompensacji czerni i skróty SHA-256 profili proof i output ICC. Klucz pamięci już pokrywa intencję koloru, dithering wyjścia, preview overprint, tryb masek luminancji, politykę fallbacku i widoczność każdej opcjonalnej grupy treści

Semantyka unieważniania dla dyskowego cache RenderCacheFolder w HotPDF: edycja wczytanego dokumentu albo jakiegokolwiek brudnego obiektu zrzuca tożsamość źródła, więc warstwa jest omijana, zmiana backendu renderowania albo workflow ICC trzyma tożsamość pod nowym kluczem wariantu, a zapis plus ponowne wczytanie daje dokumentowi nowy klucz
edycja nigdy nie kasuje przechowanego folderu, zmiana ustawień renderuje pod innym kluczem, a świeżą tożsamość edytowany dokument zdobywa dopiero zapisem i ponownym wczytaniem

Widoczność warstw to dobry przykład zmiany, która zostaje na dysku. SetLoadedOptionalContentGroupVisible zapisuje nadpisanie w pamięci, nie dotykając żadnego obiektu PDF, więc dokument trzyma tożsamość, a przełączony widok renderuje do własnego podfolderu obok domyślnego:

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);

  // Ten sam klucz dokumentu, inny klucz ustawień renderowania: ta strona jest czytana
  // z drugiego folderu albo do niego zapisywana, a widok domyślny zostaje nietknięty
  Bmp := Pdf.RenderLoadedPageToBitmapCached(PageIndex, 150);
end;

Edytowany dokument wraca na warstwę dyskową tylko przez stanięcie nowym plikiem. Zapisz go i wczytaj wynik:

procedure CommitEditsAndRekey(Pdf: THotPDF; const EditedFile: string);
begin
  // Po edycji: odśwież strony w pamięci. Tożsamość źródła już
  // zniknęła, więc folder oryginalnego dokumentu nie jest ani czytany,
  // ani zapisywany
  Pdf.InvalidateRenderedPageCache;

  // Zapisany plik ma własny rozmiar i czas ostatniego zapisu, czyli własną
  // tożsamość; rendery po tym wczytaniu są cacheowane pod nowym kluczem
  Pdf.SaveLoadedDocument(EditedFile);
  if Pdf.LoadFromFile(EditedFile) <= 0 then
    raise Exception.Create('Could not reload the edited document');
end;

Folder oryginalnego dokumentu zostaje, gdzie był, i starzeje się przez RenderCacheMaxDocuments i RenderCacheMaxBytes jak każdy inny wpis. Otwórz ponownie nieedytowany oryginał, a jego strony wciąż tam siedzą

Źródła zaszyfrowane, junctiony i współdzielone korzenie

Dyskowy cache renderowania HotPDF odmawia dwóch wejść celowo: stron zaszyfrowanego PDF i podfolderów dokumentów będących junctionami albo innymi punktami reparse. Obie reguły handlują trafienia cache za bezpieczeństwo

Zaszyfrowane PDF-y zostają w pamięci

Wyrenderowana strona to odszyfrowana treść. Zapisanie jej jako gołego PNG do folderu cache zostawiłoby czytelna kopię dokumentu chronionego hasłem na dysku, poza ochroną, którą wybrał jego autor (ISO 32000-1 §7.6). HotPDF nie przechwytuje tożsamości dla żadnego źródła, którego trailer niesie wpis /Encrypt — czy otwarte hasłem, czy z pustym hasłem użytkownika. Te dokumenty nadal używają warstwy pamięci, która znika z procesem

Podlinkowane foldery dokumentów są pomijane

Korzeń cache wybierasz sam, i wskazanie go na junction jest w porządku. Podfoldery pod nim są co innego: cache tworzy, dotyka i kasuje je sam w trakcie sprzątania przy starcie, lookupu, zapisu i wszystkich trzech limitów wysiedlania. Gdyby ktoś z prawem zapisu do korzenia zamienił folder dokumentu na junction do innego katalogu, każda z tych operacji poszłaby za nim, a wysiedlanie kasowałoby pliki gdzie indziej. Każdy punkt wejścia czyta najpierw atrybuty folderu i pomija cokolwiek oflagowanego jako punkt reparse. Lookup liczy chybienie, zapis liczy porażkę zapisu, a wysiedlanie zostawia go w spokoju

Ścieżki Unicode i jeden korzeń na proces

RenderCacheFolder to Unicode string, a atomowa podmiana woła szerokie API Windows, więc ścieżka profilu poza systemową stroną kodową (chińska nazwa użytkownika przy angielskiej instalacji Windows, powiedzmy) dociera do cache nietknięta. Kilka instancji THotPDF w jednym procesie rozwiązujących się do tego samego korzenia, porównywanych bez rozróżniania wielkości liter po rozwinięciu ścieżki, dzieli jeden indeks zliczający referencje i jeden lock. To ma znaczenie dla limitów: osobne kopie index.txt egzekwowałyby każdy budżet 500 MB względem częściowego widoku i pozwoliłyby folderowi urosnąć kilka razy ponad

Dzielenie kończy się na granicy procesu. Dwa procesy na tym samym korzeniu trzymają osobne indeksy w pamięci, więc każda równolegle biegnąca aplikacja powinna dostać własny korzeń. Wątki robocze wewnątrz jednego procesu są w porządku: PrefetchLoadedPages i kolejka w renderowaniu w tle z kolejką żądań idą przez tę samą cacheowaną ścieżkę i ten sam lock

Ustawienia do poprawienia przed wysyłką

  • Ustaw folder i oba limity przed pierwszym cacheowanym renderem, a dla wczytań streamem albo źródłem losowym — przed wczytaniem
  • Oczekuj renderowania wyłącznie w pamięci dla zaszyfrowanych PDF, dokumentów edytowanych po wczytaniu i za każdym razem, gdy RenderFallbackPolicy nie jest rfpIgnore
  • Daj każdej biegnącej aplikacji własny korzeń cache w lokalizacji per użytkownik, jak %LOCALAPPDATA%

Trwały cache stron zarabia swoje miejsce na dysku w przeglądarce, która otwiera te same dokumenty cały dzień — to obciążenie za architekturą własnej przeglądarki PDF w Delphi na tym blogu. Warstwa dyskowa, rasterowy cache pamięci i renderer stron są wszystkie częścią komponentu HotPDF Delphi PDF, dostępnego dla Delphi i C++Builder