按檔名做鍵的頁面快取,會在一個夜裡被同名覆寫成新修訂版的 PDF 上,端出昨天的頁面。按整檔 SHA-256 做鍵的快取永遠不會犯這種錯,但對一份 400 MB 的掃描檔案庫,雜湊可能比渲染使用者實際打開的兩頁還久。可工作的鍵落在兩者之間,而選擇它也逼出第二個決定:記憶體裡的編輯該怎麼對待已經躺在磁碟上的頁面
RenderCacheFolder 磁碟層如何排在記憶體快取後面
HotPDF RenderCacheFolder 在 HotPDF Delphi 元件的記憶體內光柵快取後面加了一層持久層,且只在該屬性持有非空路徑時才參與。呼叫 RenderLoadedPageToBitmapCached(PageIndex, DPI) 先查記憶體,以頁索引、DPI 與目前渲染設定為鍵;未命中就問磁碟。磁碟命中解碼存好的 PNG、升回記憶體、交給您一份複本。兩層都未命中,頁面才走把已載入 PDF 頁渲染成 TBitmap一文描述的完整渲染器,而新鮮出爐的點陣圖在出口處寫上磁碟
資料夾版面樸素到可以在檔案總管裡直接看。每份文件一個子資料夾,名字由 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 條目的來源 | 無 | 無 | 永不擷取;磁碟層被繞過 |
對桌面檢視器,取樣指紋是正確的預設;每次開啟都全量雜湊是錯的預設。兩個取樣區域是照檔案結構挑的:檔頭在開頭,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 模式、後備政策與每個可選內容群組的可見性
圖層可見性是「變更留在磁碟上」的好例子。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 都能用