同一份 PDF,從本地磁碟打開瞬間就現形,換成由回答 range 請求的 HTTP 伺服器供應同樣的位元組,出第一頁卻要花上好幾秒——檔案不過幾 MB,頻寬還很快。問題不在頻寬,在請求數量;解法是把數百個零散小讀取合併成幾十個快取區塊,然後只在存取型態維持順序時才預讀
同一份 PDF 為什麼本地秒開、走 HTTP 就慢如龜?
PDF 解析器不是從頭到尾讀檔,而是在檔案裡導航。ISO 32000-1 §7.5 的結構把入口放在檔尾:解析器跳到最後一 KB 找 startxref、跳回交叉參考表、解出 trailer 字典、循參照到 Catalog、再到頁面樹根、再到某個頁面節點、再到那頁的資源字典。每一跳都從不同偏移讀幾十個位元組,增量更新的檔案還要沿 /Prev 鏈對每個修訂重走一遍
本地檔案上這種模式幾乎免費:作業系統的檔案快取早就握著周邊的 4 KiB 頁,第二次讀取只是一次記憶體複製。網路傳輸沒有這種局部性,每次讀取都是帶著自己延遲的請求,算術很殘酷:單程 40 ms 時,300 個小讀取累積成十二秒的等待,線路大部分時間閒著。讀少一點不是選項,解析器要的位元組一個都不能少;能變的,是每次實體請求帶回多少
把傳輸層包進 THPDFCoalescingRandomAccessSource
HotPDF 從任何繼承 THPDFRandomAccessSource 的類別載入文件,而 THPDFCoalescingRandomAccessSource 坐在這個類別與解析器之間。每次讀取都對齊擴展成整個區塊,區塊留駐記憶體。BlockSize 預設 262,144 位元組、MaxCacheBytes 預設 2,097,152,八個區塊常駐,預算滿了就換掉最久未用的那個。解析器為 trailer 鍵做的 40 位元組查找,順便拉進周邊 256 KiB;接下來一打讀取(交叉參考條目、Catalog、頁面樹鍵)全部出自記憶體
你自己的類別保持精簡。必須實作的只有兩個方法:GetSize 與 ReadAt。HTTP client 能中途取消請求,就覆寫 ReadAtCancellable;來源是還在下載的檔案,就覆寫 IsRangeAvailable。wrapper 在每次抓取前都問這個問題:整塊還沒到位就只改抓請求的位元組,連那些也缺,讀取就短返回而不是阻塞
type
// TMyHttpClient 代表你自己的 HTTP client 類別
THttpRangeSource = class(THPDFRandomAccessSource)
private
FClient: TMyHttpClient;
FUrl: string;
FSize: Int64;
public
constructor Create(const AUrl: string);
function GetSize: Int64; override;
function ReadAt(Offset: Int64; var Buffer; Count: Longint): Longint; override;
function ReadAtCancellable(Offset: Int64; var Buffer; Count: Longint;
CancellationToken: THPDFCancellationToken): Longint; override;
end;
var
Raw: THttpRangeSource;
Cached: THPDFCoalescingRandomAccessSource;
Pdf: THotPDF;
begin
Raw := THttpRangeSource.Create('https://files.example.com/contract.pdf');
// OwnsSource=True:wrapper 負責釋放 Raw;256 KiB 區塊、8 MiB 額度
Cached := THPDFCoalescingRandomAccessSource.Create(Raw, True, 262144, 8388608);
Cached.MaxReadAheadBlocks := 8; // 合法範圍 1..32
Pdf := THotPDF.Create(nil);
try
// 再次 OwnsSource=True:Pdf 釋放 Cached,Cached 釋放 Raw
if Pdf.LoadFromRandomAccessSource(Cached, True) > 0 then
RenderFirstPage(Pdf); // 你自己的程式碼
finally
Pdf.Free;
end;
end;
wrapper 一建構好,非同步預取與自適應預讀就都是開著的,範例因此只碰窗口上限。建構子預先驗證引數:BlockSize 必須在 4,096 到 16,777,216 位元組之間、MaxCacheBytes 至少裝得一個區塊,否則在任何位元組移動之前就丟 ERangeError
顯式 wrapper 並非嚴格必需。把樸素來源交給 LoadFromRandomAccessSource,HotPDF 會替你包一層,用的是可透過 GetCacheAdmissionPolicy 與 SetCacheAdmissionPolicy 以 clkRawCompressed 層讀改的原始快取政策:八個條目、共 2 MiB、每條 256 KiB。傳自己的 THPDFCoalescingRandomAccessSource,它就照你配置的原樣使用。凡是過網路的東西,自己建 wrapper——你拿到預讀旋鈕與完整統計記錄;自動路徑只透過 GetCacheAdmissionStatistics 回報命中、未中、收錄與逐出計數
該預讀多遠?
自適應預讀按文件個別決策。AdaptiveReadAheadEnabled 設下之後,解析器對已載入文件的每次讀取都被分類為順序或隨機,預讀窗口跟著分數走。連續兩次前向讀取把窗口開到兩個區塊,四次開到四個,六次開到八個。窗口永不超過 MaxReadAheadBlocks,也不超過 MaxCacheBytes 裝得下的區塊數,小快取因此不會被自己的預取淹沒
向後跳的讀取,或落在前一次讀取結尾太遠之外的讀取,會把分數壓到零下。窗口關閉,任何朝別處去的預取被取消,SuppressedPrefetchCount 上升。再來兩次前向讀取,窗口以單一區塊重新打開。這個滯後是重點:交叉參考追逐中途的一次運氣連續讀取,不該重啟投機
SequentialReadToleranceBytes(預設 4,096)定義「太遠」。走訪內容串流的解析器不會產出完美連續的偏移:這裡跳過一個長度欄位、那裡跳過一個內嵌影像字典。落在前次結尾容差之內的讀取仍算前向。設太低,正常的前向掃描被歸為隨機,預讀於是永不啟動;設太高,真正的隨機存取看起來像順序,你會抓回沒人讀的幾 MB。setter 接受 0 到 BlockSize 的任何值,改動時重置分數
成長是漸進的,塌縮是立刻的,這個不對稱是刻意的。隨機負載上過度抓取燒真實頻寬,計費傳輸上燒真金白銀;順序負載上抓不夠,只多付幾個往返。讓 AdaptiveReadAheadEnabled 維持開啟。關掉之後,wrapper 不管型態、每次讀取後都預取一個區塊——解析器在交叉參考區之間跳來跳去時,這恰好是最糟的行為
分類由載入期間 HotPDF 讀取的那條串流驅動。如果你的程式碼也會透過 wrapper 拉位元組——比如算雜湊或抽附件——每次讀取後用偏移與長度呼叫 ObserveReadPattern,窗口才會對這些流量起反應。已經知道接下來要哪些位元組時,PrefetchRange 直接開一個背景抓取;IsPrefetchActive 回報它是否還在跑
快取滿了之後,留住熱區塊
樸素的 LRU 逐出有個著名弱點:一趟漫長的前向掃描——比如掃過一張大內嵌影像——會把解析器不斷回頭要的區塊全部擠出去,包括下一頁還要再用的交叉參考與 Catalog 區塊。THPDFCoalescingRandomAccessSource 記錄每個區塊被要求的次數,預算滿了之後,新區塊只有被要求次數不低於它要替換的對象才進得了快取。否則讀取直接落到你的來源、精確抓請求的位元組,並記進 RejectionCount 與 FrequencyRejectionCount
這條規則預設開啟(建構子參數 AdaptiveAdmission)。ConfigureCacheAdmission 能在活著的 wrapper 上改位元組預算、單條上限、選用的條目數上限與收錄規則;它取消進行中的預取,並當場把快取裁到新上限
真正叫得停傳輸的取消
預取跑在單一背景執行緒上,只要不值得跑完,wrapper 就取消它。前景讀取落在預取範圍之外,取消——使用者要的那頁因此永遠不必排在投機流量後面。隨機讀取,取消。銷毀 wrapper、呼叫 CancelPrefetch 或 ClearCache,取消並等執行緒退出。這些每一項都在設定預取執行緒傳進你 ReadAtCancellable 的那個 THPDFCancellationToken
位元組是不是真的停下來,取決於你的覆寫。THPDFRandomAccessSource 上的預設 ReadAtCancellable 在樸素 ReadAt 前後各查一次 token,對檔案共用足夠,卻會讓半完成的 256 KiB HTTP 回應跑完。會分塊讀回應主體的 client 可以在塊與塊之間查 token、中途夭折:
function THttpRangeSource.ReadAt(Offset: Int64; var Buffer;
Count: Longint): Longint;
begin
Result := ReadAtCancellable(Offset, Buffer, Count, nil);
end;
function THttpRangeSource.ReadAtCancellable(Offset: Int64; var Buffer;
Count: Longint; CancellationToken: THPDFCancellationToken): Longint;
var
Status: Integer;
begin
if CancellationToken <> nil then
CancellationToken.ThrowIfCancellationRequested('http range read');
// GetRange 與它的回呼是你 client 的 API:它送出
// 「Range: bytes=Offset-(Offset+Count-1)」,並在 body 區塊之間呼叫回呼
Result := FClient.GetRange(FUrl, Offset, Count, Buffer, Status,
function: Boolean
begin
Result := (CancellationToken <> nil) and
CancellationToken.IsCancellationRequested;
end);
// 回 200 而非 206,代表伺服器無視 Range、送來整份檔案
if Status <> 206 then
raise EStreamError.CreateFmt('Range request not honored (HTTP %d)', [Status]);
if CancellationToken <> nil then
CancellationToken.ThrowIfCancellationRequested('http range read');
end;
狀態碼檢查蓋住了多數 HTTP 來源第一個撞上的陷阱。RFC 9110 §14 允許伺服器無視 Range 標頭、以 200 回傳完整表示,某些 CDN 與代理設定對特定檔案幹的正是這件事。把 200 回應的前 Count 位元組抄下來的來源,不管請求哪個偏移,交給解析器的都是偏移零開始的位元組。回傳值同樣要緊:ReadAt 回報負數或超過請求數的位元組,wrapper 丟 EStreamError;零視為資料結尾
你的來源唯一會拿到的非 nil token 屬於預取執行緒。載入期間的解析器讀取以 nil token 抵達你的 ReadAtCancellable,所以停掉載入本身是另一個開關:給 THotPDF.OperationCancellationToken 指派一個 token,文件載入邊走邊查。同一套 token 模型也驅動以請求佇列做背景渲染描述的佇列,檢視器因此能從一個關閉 handler 一次取消載入、渲染與投機網路流量
讀懂範圍快取統計
GetStatistics 填一份 THPDFRangeCacheStatistics 記錄,把傳輸做了什麼與快取做了什麼分開記。SourceReadCount 與 SourceBytesRead 是實體流量;CacheHitCount 與 CacheMissCount 是邏輯流量;SequentialReadCount 與 RandomReadCount 顯示存取型態被怎麼分類,CurrentReadAheadBlocks 與 PeakReadAheadBlocks 顯示窗口開到多遠,四個預取計數說明投機划不划算。CachedRangeCount、CachedBytes、EvictionCount 與 RejectionCount 描述快取本身
var
S: THPDFRangeCacheStatistics;
begin
Cached.GetStatistics(S);
Log(Format('physical %d reads / %d bytes, hits %d, misses %d',
[S.SourceReadCount, S.SourceBytesRead, S.CacheHitCount, S.CacheMissCount]));
Log(Format('pattern: %d sequential, %d random, peak window %d blocks',
[S.SequentialReadCount, S.RandomReadCount, S.PeakReadAheadBlocks]));
Log(Format('prefetch: %d issued, %d completed, %d canceled, %d suppressed',
[S.PrefetchRequestCount, S.PrefetchCompletedCount,
S.PrefetchCancelledCount, S.SuppressedPrefetchCount]));
Log(Format('cache: %d blocks / %d bytes, %d evicted, %d rejected',
[S.CachedRangeCount, S.CachedBytes, S.EvictionCount, S.RejectionCount]));
// 大致順序型的文件上拒絕不斷堆積:給它更多空間
if S.RejectionCount > S.CacheHitCount then
Cached.ConfigureCacheAdmission(16 * 1024 * 1024, Cached.BlockSize, 0);
end;
三個讀數告訴你該動什麼。取消的預取很多、隨機讀取計數又高,代表文件被亂序走訪,調低 MaxReadAheadBlocks,別再為你扔掉的頻寬付錢。未中很多、峰值窗口卡在 1,代表容差把實質順序的型態拒了,調高 SequentialReadToleranceBytes。SourceBytesRead 遠超檔案大小,代表區塊在再次被用到之前就被逐出;先調高 MaxCacheBytes,其他都先別動。範例裡那個拒絕門檻是我們自己的起始啟發式,對著你的流量調
線性化檔案改寫這道算術
產生端在你手裡的話,把文件線性化是換掉問題本身而不是調參。ISO 32000-1 附錄 F 把第一頁的物件與提示表放在檔案開頭,檢視器於是能從開頭位元組渲染第一頁、完全不碰其餘部分。HotPDF 透過 GetProgressiveLinearizedLoadInfo 與 ReadProgressiveLinearizedFirstPageSection 暴露這條路,兩者收的正是你為合併包裝的那個 THPDFRandomAccessSource;寫入端見產生帶提示表的線性化 PDF
兩種技術可以疊加。合併讓任何文件在慢連結上變得可忍受,包括你無法重新存檔的第三方檔案;線性化讓自己產出的文件第一頁快速抵達。本地磁碟上大到裝不進記憶體的檔案是另一個問題,沒有往返延遲可供攤提,直接檔案 API 工作流程裡的映射檔與懶串流路徑更適合它們
隨機存取來源類別、合併 wrapper、快取收錄政策與漸進線性化載入呼叫都隨 HotPDF 出貨——一支帶完整源碼的原生 Delphi 與 C++Builder PDF 元件。授權與完整 API 參考見HotPDF Delphi PDF 元件頁