技術文章

HotPDF RenderCacheFolder:Delphi 的磁碟頁面快取

按檔名做鍵的頁面快取,會在一個夜裡被同名覆寫成新修訂版的 PDF 上,端出昨天的頁面。按整檔 SHA-256 做鍵的快取永遠不會犯這種錯,但對一份 400 MB 的掃描檔案庫,雜湊可能比渲染使用者實際打開的兩頁還久。可工作的鍵落在兩者之間,而選擇它也逼出第二個決定:記憶體裡的編輯該怎麼對待已經躺在磁碟上的頁面

RenderCacheFolder 磁碟層如何排在記憶體快取後面

HotPDF RenderCacheFolder 在 HotPDF Delphi 元件的記憶體內光柵快取後面加了一層持久層,且只在該屬性持有非空路徑時才參與。呼叫 RenderLoadedPageToBitmapCached(PageIndex, DPI) 先查記憶體,以頁索引、DPI 與目前渲染設定為鍵;未命中就問磁碟。磁碟命中解碼存好的 PNG、升回記憶體、交給您一份複本。兩層都未命中,頁面才走把已載入 PDF 頁渲染成 TBitmap一文描述的完整渲染器,而新鮮出爐的點陣圖在出口處寫上磁碟

HotPDF 的 RenderLoadedPageToBitmapCached 渲染快取查找示意圖:先查以頁、DPI 與渲染變體為鍵的記憶體層,再查以 PNG 檔構成、原子替換寫入的 RenderCacheFolder 磁碟層,然後才是內容串流直譯器,每一次命中都回傳歸呼叫方所有的複本
HotPDF 先查記憶體、再查磁碟、最後才點陣化;磁碟命中會升回記憶體,每條路徑交給您的都是您自己的複本,用完要 Free

資料夾版面樸素到可以在檔案總管裡直接看。每份文件一個子資料夾,名字由 16 個十六進位字元的文件鍵與 16 個十六進位字元的渲染設定鍵組成,每一頁落成 <page>@<dpi>.png。根目錄的 index.txt 在一個 schema 標籤之下按最近使用順序列出文件;標籤對不上,整個資料夾在首次使用時清空。PNG 與 index 的寫入先落到暫存檔、再以 MoveFileExW 加 replace-existing 旗標換入,所以寫到一半崩潰,留下的要嘛是舊檔、要嘛沒有檔。解不開的 PNG 會被刪除、計為未命中

三個上限不讓資料夾無限生長:

  • RenderCacheMaxDocuments(預設 20)限制文件子資料夾數量,先驅逐最近最少使用的那個
  • RenderCacheMaxBytes(預設 524288000,即 500 MB)限制根目錄下所有 PNG 的合計大小
  • 每個文件資料夾至多放 200 張頁面影像;這個上限固定在 THotPDF 裡、沒有對應屬性

RenderCacheCapacity(預設 8)與磁碟無關:它數的是記憶體裡持有的頁面

uses
  SysUtils, Graphics, HPDFDoc;

procedure WarmThumbnails(const FileName: string);
var
  Pdf: THotPDF;
  Bmp: TBitmap;
  I: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    // 磁碟層在第一次快取渲染時一次性讀入資料夾與兩個上限,
    // 所以請在那次呼叫之前設定
    Pdf.RenderCacheFolder := IncludeTrailingPathDelimiter(
      GetEnvironmentVariable('LOCALAPPDATA')) + 'MyViewer\PageCache';
    Pdf.RenderCacheMaxDocuments := 50;
    Pdf.RenderCacheMaxBytes := Int64(1024) * 1024 * 1024; // 1 GiB
    Pdf.RenderCacheCapacity := 16;                        // 記憶體中的頁數

    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
          // 在這裡把複本交給縮圖列
        finally
          Bmp.Free; // 快取呼叫永遠回傳歸呼叫方所有的複本
        end;
      end;
  finally
    Pdf.Free; // 磁碟條目留給下一個工作階段
  end;
end;

同一份檔案把這段程序跑兩遍,第二遍不會再光柵化任何限額之內的頁面。磁碟快取在第一次快取渲染時建立、活到 THotPDF 實例為止,那之後再改資料夾或任一上限,既不搬家也不縮容。另兩個條件讓頁面進不了磁碟:超過記憶體快取預設單條目上限的點陣圖(32 位元像素的 64 MiB,即 4096 × 4096 頁)不會被存放;而且只有 RenderFallbackPolicy 維持預設 rfpIgnore 時才會諮詢磁碟層——PNG 只帶像素,沒有更嚴格政策要回報的後備診斷

直覺的快取鍵為什麼全都不行?

最先想到的三個鍵,各自以不同方式失敗。檔案路徑輸給覆寫。對 PDF 位元組的記憶體副本做雜湊看似安全,直到您注意到:原地讀檔的解析器沒有理由留這種副本;對從未填充的緩衝做雜湊得到空鍵,而把空鍵當「跳過磁碟」的快取,會留下一個設定正確、卻永遠收不到 PNG 的資料夾。從磁碟把整個檔案雜湊一遍行得通,代價是每次開啟都讀每個位元組

更難的陷阱是失效。這類元件必須在每次載入開始、每次編輯之後與銷毀時清空記憶體頁面,而誘人的做法是在同樣的地方順手刪掉文件的磁碟資料夾。這麼做,每個檢視器工作階段退出時都擦掉自己的快取,第二天早上照樣冷啟動。更糟的是編輯之後從未變動的來源重算鍵:編輯後的渲染落在原始檔案的鍵底下,下一個打開未動過的 PDF 的人收到的就是它們。身分與失效必須當成一件事設計;任何一個做錯,出貨的就是一個永遠不命中的快取,或一個端出檔案裡沒有的頁面的快取

HotPDF 怎麼為 PDF 來源建立指紋

HotPDF 對以 LoadFromFile 載入的 PDF,用 SHA-256 雜湊它的大小、最後寫入時間與頭尾各 64 KiB 來識別;對串流或隨機存取來源,則以整個內容的 SHA-256 識別。身分在載入成功的那一刻擷取一次,摘要的前 16 個十六進位字元(64 位元)成為文件鍵

來源身分成本擷取時機
LoadFromFile大小 + 最後寫入時間 + 頭尾各 64 KiB,以 SHA-256 雜湊至多讀 128 KiB,與檔案大小無關每次成功載入,即使 RenderCacheFolder 是載入後才設定
LoadFromStream整個串流的 SHA-256來源完整走一遍僅當 RenderCacheFolder 在載入之前已設定
LoadFromRandomAccessSource整個來源的 SHA-256來源完整走一遍僅當資料夾已先行設定且每個位元組區間都可得
任何帶 /Encrypt 條目的來源無無永不擷取;磁碟層被繞過
HotPDF 磁碟渲染快取的來源身分地圖:LoadFromFile 雜湊大小、LastWriteTime 與頭尾各 64 KiB,LoadFromStream 與 LoadFromRandomAccessSource 只在 RenderCacheFolder 先行設定時才雜湊整個內容,任何帶 /Encrypt 的 trailer 完全不擷取身分
檔案從頭尾取樣指紋,因為檔頭、xref 與 trailer 就住在那裡;串流只有先要求快取才付全量雜湊的成本;加密文件絕不寫上磁碟

對桌面檢視器,取樣指紋是正確的預設;每次開啟都全量雜湊是錯的預設。兩個取樣區域是照檔案結構挑的:檔頭在開頭,trailer 與最後一個交叉參考區在結尾(ISO 32000-1 §7.5)。增量更新在後面附加新的本體、交叉參考區與 trailer(§7.5.6),大小與尾巴同時改變;任何普通的整檔改寫都會動最後寫入時間。低於 128 KiB 時兩個取樣重疊、蓋住每一個位元組,小文件其實被完整雜湊

漏網的是大型檔案中段被同尺寸改寫、工具又把原始時間戳復原的情況。刻意保留修改時間、同時改內容的編輯器存在,但罕見;對這種檔案,快取端出的是舊頁面。相反的情況對您有利:Windows 的檔案複製保留最後寫入時間,快取過的文件複本命中同一批條目——這是正確的,因為位元組一致

串流沒有時間戳。內容是唯一誠實的身分,所以 HotPDF 只在載入之前被要求了磁碟快取時才付整份 SHA-256 的成本;不設快取資料夾就呼叫 LoadFromStream 的程式碼什麼都不用多付。這讓兩行程式碼的順序有了講究:

procedure OpenDownloadedPdf(Pdf: THotPDF; Data: TStream;
  const CacheRoot: string);
begin
  // 對串流而言的錯誤順序:內容雜湊只在資料夾
  // 已經設定時才計算,這份文件會因此繞過磁碟層
  //   Pdf.LoadFromStream(Data);
  //   Pdf.RenderCacheFolder := CacheRoot;

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

仍在下載中的隨機存取來源,拿不到任何身分——而不是對已到的區段做雜湊。身分計算因任何原因丟例外時,載入照樣成功,文件僅經記憶體渲染

編輯之後,快取的頁面怎麼辦?

編輯已載入的文件,從不刪除 HotPDF 磁碟渲染快取裡的任何東西。編輯丟掉的是文件本身的身分:那次載入的其餘部分繞過磁碟層,而存放的頁面對它們當初渲染自的那份未修改檔案依然有效。條目離開磁碟只有四條路:文件與位元組上限、200 頁上限、解不開的 PNG,或 schema 變更

鍵描述的是磁碟上的檔案。蓋了章的頁面或改過的註釋一旦出現,記憶體裡的文件就不再匹配它,在那個鍵下讀或寫都不誠實。InvalidateRenderedPageCache 與編輯觸發的逐頁失效都只清身分、不動資料夾。第二道檢查涵蓋從不失效任何東西的編輯路徑:每次磁碟查找之前,THotPDF 問一次有沒有任何已載入物件帶著未保存的變更,有就按無身分處理

渲染設定走另一個方向。指派 PageRenderBackend(UseNativeGDIRenderBackend 會替您做)、呼叫 ConfigureRenderICCWorkflow 或 ClearRenderICCWorkflow,沖掉的是記憶體頁面、保留的是身分——文件仍然匹配它的檔案。這些設定改變像素卻不出現在記憶體鍵裡,所以磁碟鍵把後端名稱、黑點補償旗標與 ICC proof、output profile 的 SHA-256 摘要一起摺進去。記憶體鍵已涵蓋色彩意圖、輸出抖色、疊印預覽、luminosity mask 模式、後備政策與每個可選內容群組的可見性

HotPDF 對 RenderCacheFolder 磁碟快取的失效語意示意圖:編輯已載入文件或任何 dirty 物件會丟掉來源身分、繞過該層,更換渲染後端或 ICC 工作流則在新變體鍵下保留身分,存檔再重新載入會替文件換新鍵
編輯絕不刪除已存的資料夾,設定變更在不同的鍵下渲染,只有存檔加重新載入,才讓編輯過的文件贏得新身分

圖層可見性是「變更留在磁碟上」的好例子。SetLoadedOptionalContentGroupVisible 只把覆寫記在記憶體裡、不碰任何 PDF 物件,文件保持身分,切換後的視圖渲染進預設視圖旁邊自己的子資料夾:

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

  // 同一個文件鍵、不同的渲染設定鍵:這一頁從第二個資料夾讀取或寫入,
  // 預設視圖不受打擾
  Bmp := Pdf.RenderLoadedPageToBitmapCached(PageIndex, 150);
end;

編輯過的文件回到磁碟層只有一條路:變成一份新檔案。存檔、再載入結果:

procedure CommitEditsAndRekey(Pdf: THotPDF; const EditedFile: string);
begin
  // 編輯之後:重新整理記憶體頁面。來源身分已經不在,
  // 對原文件的資料夾
  // 既不讀也不寫
  Pdf.InvalidateRenderedPageCache;

  // 存出來的檔案有自己的大小與最後寫入時間,因此有自己的身分;
  // 這次載入之後的渲染會存進新鍵底下
  Pdf.SaveLoadedDocument(EditedFile);
  if Pdf.LoadFromFile(EditedFile) <= 0 then
    raise Exception.Create('Could not reload the edited document');
end;

原文件的資料夾原地不動,像任何其他條目一樣隨 RenderCacheMaxDocuments 與 RenderCacheMaxBytes 老化淘汰。重新打開未編輯的原檔,它的頁面還在

加密來源、junction 與共享根目錄

HotPDF 的磁碟渲染快取刻意拒收兩種輸入:加密 PDF 的頁面,以及本身是 junction 或其他 reparse point 的文件子資料夾。兩條規則都是拿快取命中換安全

加密 PDF 留在記憶體

渲染出的頁面就是解密後的內容。把它當普通 PNG 寫進快取資料夾,等於把一份受密碼保護文件的可讀副本留在磁碟上、放在作者選定的保護之外(ISO 32000-1 §7.6)。trailer 帶 /Encrypt 條目的來源,HotPDF 一律不擷取身分——無論它是以密碼開啟、還是以空的使用者密碼開啟。這些文件照用記憶體層,記憶體層隨行程消失

被連結的文件資料夾一律跳過

快取根目錄由您挑,指到 junction 沒問題。它底下的子資料夾不一樣:啟動清理、查找、存放與三個淘汰上限的過程中,快取會自行建立、觸碰與刪除它們。若有對根目錄有寫入權限的人把某個文件資料夾換成指往別處的 junction,上述每個操作都會跟著走,淘汰會刪到別處的檔案。每個入口都先讀資料夾屬性、跳過任何被標為 reparse point 的東西:查找計一次未命中,存放計一次寫入失敗,淘汰則不碰它

Unicode 路徑與每行程一個根目錄

RenderCacheFolder 是 Unicode string,原子替換呼叫的是寬字元 Windows API,所以系統代碼頁之外的使用者設定檔路徑——例如英文 Windows 上的中文使用者名稱——完整抵達快取。同一行程裡解析到同一個根目錄的多個 THotPDF 實例(路徑展開後不分大小寫比較),共享一個引用計數的 index 與一把鎖。這對上限很要緊:index.txt 各留一份的話,每份都對著局部視圖執行 500 MB 預算,資料夾可以超標好幾倍

共享止於行程邊界。同一根目錄上的兩個行程各自持有記憶體內 index,所以每個並行執行的應用程式該有自己的根目錄。同一行程裡的 worker 執行緒沒問題:PrefetchLoadedPages 與以請求佇列做背景渲染裡的佇列,走的都是同一條快取路徑與同一把鎖

出貨前要設對的設定

  • 資料夾與兩個上限要在第一次快取渲染之前設定;串流或隨機存取載入則要在載入之前
  • 加密 PDF、載入後被編輯過的文件,以及 RenderFallbackPolicy 不是 rfpIgnore 時,預期只有記憶體渲染
  • 每個執行中的應用程式,在 %LOCALAPPDATA% 這類按使用者隔離的位置下有自己的快取根目錄

整天重開同一批文件的檢視器,才養得起持久頁面快取占的磁碟空間——本部落格Delphi 自訂 PDF 檢視器架構一文背後正是這種工作負載。磁碟層、記憶體光柵快取與頁面渲染器都是 HotPDF Delphi PDF component 的一部分,Delphi 與 C++Builder 都能用