技術記事

リモートPDFをDelphiでストリーミング:HotPDFの範囲結合

ローカルディスクなら即座に開くPDFも、同じバイト列が範囲リクエストに答えるHTTPサーバーから来ると、最初のページが出るまでに数秒かかることがあります。ファイルは数メガバイトしかなく、回線が速くてもです。問題は帯域幅ではありません。リクエスト数であり、処方箋は、数百の微小で散在する読み取りを数十のキャッシュ済みブロックへ変え、アクセスパターンがシーケンシャルである間だけ先読みすることです

同じPDFがローカルでは瞬時に開き、ネットワーク経由では這うように遅くなるのはなぜか

PDFパーサーはファイルを前から後ろへ読みません。たどります。ISO 32000-1 §7.5の構造は入り口を末尾に置きます。パーサーはstartxrefを求めて最後のキロバイトへシークし、相互参照テーブルへ戻り、トレーラー辞書を解決し、Catalogへの参照をたどり、ページツリーのルート、ページノード、そしてそのページのリソース辞書へ進みます。ホップごとに、別のオフセットから数十バイトを読み、増分更新されたファイルは/Prevチェーンを通じて、リビジョンごとにこのたどりをもう1度繰り返します

ローカルファイルではこのパターンはほぼ無償です。OSがすでに周囲の4 KiBページをファイルキャッシュに抱えており、2回目の読み取りはメモリコピーで済むからです。ネットワークトランスポートには、こうした局所性がありません。すべての読み取りが、それぞれのレイテンシを持つリクエストになり、算術は容赦ありません。1ラウンドトリップ40ミリ秒で、300の小さな読み取りは12秒の待ちに積み上がり、回線はほとんど遊んでいます。読む量を減らすのは選択肢ではありません。パーサーは自分が求めたバイトをそのまま必要とするのです。変えられるのは、1回の物理リクエストがどれだけ持ち帰るかです

トランスポートをTHPDFCoalescingRandomAccessSourceで包む

HotPDFは、THPDFRandomAccessSourceを継承する任意のクラスからドキュメントをロードしますが、THPDFCoalescingRandomAccessSourceはそのクラスとパーサーの間に座ります。すべての読み取りは整列したブロックへ切り上げられ、ブロックはメモリに保持されます。BlockSizeのデフォルトは262,144バイト、MaxCacheBytesのデフォルトは2,097,152で、8ブロックが常駐し、予算が満杯になると最も使われていないものから出ていきます。トレーラーキーを探すパーサーの40バイトの読み取りは、その周囲の256 KiBを引き込み、その近隣での次の十数回の読み取り(相互参照エントリー、Catalog、ページツリーのキー)はメモリから出ます

あなたのクラスは薄いままで構いません。必須のメソッドはGetSizeとReadAtの2つです。HTTPクライアントが飛行中のリクエストを中断できるならReadAtCancellableをオーバーライドし、ソースがまだ進行中のダウンロードならIsRangeAvailableをオーバーライドします。ラッパーはfetchの前にその質問を投げます。ブロック全体がまだそこにないときは要求されたバイトだけで再試行し、それも無ければ、読み取りはブロックする代わりに短く戻ります

HotPDF ブロック統合の図。散在するパーサーシークがキャッシュ済み 256 KiB ブロックへ切り上げられ、同じ近傍の後続読み取りはネットワークに触れない
すべての読み取りはキャッシュ済みの 256 KiB ブロックから供給されるため、パーサーの散在は近隣ごとに 1 回のネットワーク転送で済みます
type
  // TMyHttpClientはあなた自身のHTTPクライアントクラスの代わり
  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:ラッパーが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;

非同期プリフェッチと適応的先読みは、ラッパーを構築した時点でどちらも有効なので、サンプルが触れるのは窓の天井だけです。コンストラクターは引数を前もって検証します。BlockSizeは4,096から16,777,216バイトの間になければならず、MaxCacheBytesは少なくとも1ブロックを収めなければなりません。さもないと、1バイトも動く前にERangeErrorを受け取ります

明示的なラッパーは厳密には不要です。素のソースをLoadFromRandomAccessSourceへ渡すと、HotPDFがあなたの代わりにラップし、その生キャッシュポリシーはGetCacheAdmissionPolicyとSetCacheAdmissionPolicyで、clkRawCompressed層として読み、変えられます。8エントリー、合計2 MiB、エントリーあたり256 KiBです。自分のTHPDFCoalescingRandomAccessSourceを渡せば、設定どおりにそのまま使われます。ネットワークを越えるものには、ラッパーを自分で組み立ててください。先読みのつまみと完全な統計レコードが得られます。一方、自動経路が報告するのは、GetCacheAdmissionStatisticsを通じたヒット、ミス、採用、追い出しのカウントだけです

どこまで先読みすべきか

適応的先読みはドキュメントごとに決めます。AdaptiveReadAheadEnabledが立っていると、ロード済みドキュメントを通るパーサーの読み取りはすべて、シーケンシャルかランダムかに分類され、プリフェッチ窓はスコアに追従します。前方への連続2読み取りで窓は2ブロックへ開き、4で4、6で8へ開きます。窓はMaxReadAheadBlocksを超えず、MaxCacheBytesに収まるブロック数も超えません。小さなキャッシュが自分のプリフェッチに水没することはないのです

後ろ向きの読み取りや、前の読み取りの終端から遠すぎる場所へ着地する読み取りは、スコアをゼロ未満へ落とします。窓は閉じ、別の場所へ向かっていたプリフェッチはキャンセルされ、SuppressedPrefetchCountが登ります。その2つ先の前方読み取りで、窓は1ブロックで再開します。この遅れこそが肝です。相互参照を追いかける途中の1回の幸運な連続読み取りが、推測を再開させたりしないのです

SequentialReadToleranceBytes(デフォルト4,096)が「遠すぎる」を定義します。コンテンツストリームを歩くパーサーは完璧に連続したオフセットを作りません。ここで長さフィールドを飛ばし、あそこでインライン画像辞書を飛ばします。前の終端の許容内に着地した読み取りは、依然として前方と数えられます。低く設定しすぎると、普通の前方スキャンがランダムと分類され、先読みは決して動きません。高く設定しすぎると、本物のランダムアクセスがシーケンシャルに見え、誰にも読まれないメガバイトをfetchします。セッターはゼロからBlockSizeまでの任意の値を受け付け、変わったときはスコアをリセットします

成長は徐々に、崩壊は即座に。この非対称は意図的です。ランダムなワークロードでの取りすぎは実際の帯域を燃やし、従量制のトランスポートでは実際の金を使います。シーケンシャルなワークロードでの取り足りない代償は、数回の余分なラウンドトリップです。AdaptiveReadAheadEnabledは有効のままにしてください。切ると、ラッパーはパターンに関係なく、すべての読み取りの後に1ブロックをプリフェッチします。パーサーが相互参照セクションの間を跳んでいるとき、これはまさに間違った振る舞いです

HotPDF の適応型リードアヘッドの階段図。持続する順方向読み取りで 1、2、4、8 ブロックへ成長し、順序外アクセスで即座に収縮
成長はラダーを 1 段ずつ登りますが、縮小は即座です。従量課金の回線では、安価な側の間違いを選ぶのです

分類を駆動するのは、ロードの間にHotPDFが読むストリームです。自分のコードもラッパーを通ってバイトを引き寄せるなら、たとえばファイルをハッシュしたり添付を取り出したりするなら、各読み取りの後にオフセットと長さをObserveReadPatternへ渡し、窓をそのトラフィックにも反応させてください。次にどのバイトが欲しくなるかをすでに知っているなら、PrefetchRangeがバックグラウンドfetchを直接始めます。IsPrefetchActiveが、まだ走っているかどうかを報告します

キャッシュが満杯のときホットなブロックを守る

素のLRU追い出しには、既知の弱点があります。1回の長い前方パス、たとえば大きな埋め込み画像の読み通しが、パーサーが何度も戻ってくるブロックすべてを押し出します。次のページでまた必要になる相互参照やCatalogのブロックも含めてです。THPDFCoalescingRandomAccessSourceは各ブロックが何回求められたかを数え、予算が満杯のとき、新しいブロックは、置き換えるブロックと同じ以上に要求されていない限りキャッシュに入りません。さもなければ、読み取りは要求されたバイトだけをあなたのソースへまっすぐ取りに行き、RejectionCountとFrequencyRejectionCountがそれを記録します

この規則はデフォルトで有効です(コンストラクター引数のAdaptiveAdmission)。ConfigureCacheAdmissionは、稼働中のラッパーでバイト予算、エントリーあたりの上限、任意のエントリー数上限、採用規則を変えます。走行中のプリフェッチをキャンセルし、その場でキャッシュを新しい上限へ切り詰めます

転送を実際に止めるキャンセル処理

プリフェッチは単一のバックグラウンドスレッドで走り、ラッパーは終わらせる価値がなくなった途端にキャンセルします。プリフェッチ中の範囲の外のバイトへのフォアグラウンド読み取りはそれをキャンセルするため、ユーザーが頼んだページが投機的トラフィックの後ろで待たされることはありません。ランダムな読み取りはそれをキャンセルします。ラッパーの破棄、CancelPrefetchやClearCacheの呼び出しは、それをキャンセルし、スレッドの終了を待ちます。どれも、プリフェッチスレッドがあなたのReadAtCancellableへ渡すTHPDFCancellationTokenを立てます

バイトが実際に止まるかどうかは、あなたのオーバーライド次第です。THPDFRandomAccessSourceのデフォルトのReadAtCancellableは、素のReadAtの前後でトークンを検査します。ファイル共有には十分ですが、半分終わった256 KiBのHTTPレスポンスは完走させます。レスポンスボディをチャンクで読むクライアントは、チャンクの合間にトークンを検査して中断できます:

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とそのコールバックはクライアントのAPI:
  // "Range: bytes=Offset-(Offset+Count-1)"を送り、ボディチャンクの合間にコールバックを呼ぶ
  Result := FClient.GetRange(FUrl, Offset, Count, Buffer, Status,
    function: Boolean
    begin
      Result := (CancellationToken <> nil) and
        CancellationToken.IsCancellationRequested;
    end);
  // 206の代わりに200は、サーバーが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が負のカウントや要求超過のバイト数を報告するとEStreamErrorを上げ、ゼロはデータ終端として扱います

あなたのソースが受け取る唯一の非nilトークンは、プリフェッチスレッドのものです。ロード中のパーサー読み取りは、nilトークンであなたのReadAtCancellableへ届きます。したがってロードそのものを止めるのは別のスイッチです。トークンをTHotPDF.OperationCancellationTokenへ割り当てると、ドキュメントロードは進みながらそれを検査します。同じトークンモデルが、リクエストキューによるバックグラウンドレンダリングで述べるキューも駆動するため、ビューアーは1つのクローズハンドラーから、ロード、レンダー、投機的なネットワークトラフィックをキャンセルできます

範囲キャッシュ統計を読み解く

GetStatisticsは、トランスポートがしたこととキャッシュがしたことを切り分けたTHPDFRangeCacheStatisticsレコードを満たします。SourceReadCountとSourceBytesReadは物理トラフィックです。CacheHitCountとCacheMissCountは論理トラフィックです。SequentialReadCountとRandomReadCountはアクセスパターンの分類を示し、CurrentReadAheadBlocksとPeakReadAheadBlocksは窓がどこまで開いたかを示し、4つのプリフェッチカウンターは推測が報われたかを示します。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;

何を変えるべきかは、3つの読み取りが教えます。高いランダム読み取り数に並ぶ多数のキャンセル済みプリフェッチは、ドキュメントが順不同で歩かれていることを意味するので、MaxReadAheadBlocksを下げて、捨てる帯域への支払いを止めてください。ピーク窓が1のままでの多数のミスは、許容値が実質シーケンシャルなパターンを拒否していることを意味するので、SequentialReadToleranceBytesを上げてください。ファイルサイズを大きく上回るSourceBytesReadは、ブロックが再利用される前に追い出されていることを意味するので、他に手を付ける前にMaxCacheBytesを上げてください。サンプルの拒否しきい値は私たち自身の出発ヒューリスティックなので、あなたのトラフィックに合わせて調整してください

HotPDF のパネル。THPDFRangeCacheStatistics の 3 つの読み取り値を MaxReadAheadBlocks、SequentialReadToleranceBytes、MaxCacheBytes の調整に対応付け
各症状の読み取りがその対処を名指しします。ランダムアクセスにはウィンドウを狭めること、ブロックがスラッシングするならキャッシュを広げること

リニアライズされたファイルは計算そのものを変える

プロデューサーを自分で握っているなら、ドキュメントを線形化することは、問題を調整する代わりに問題そのものを変えます。ISO 32000-1 附属書Fは最初のページのオブジェクトとヒントテーブルをファイルの先頭に置くため、ビューアーは残りに触れずに、冒頭のバイトから1ページ目をレンダリングできます。HotPDFはその経路をGetProgressiveLinearizedLoadInfoとReadProgressiveLinearizedFirstPageSectionとして公開します。どちらも、結合のためにラップするのと同じTHPDFRandomAccessSourceを受け取ります。書き出し側は、ヒントテーブル付きリニアライズPDFの生成で扱います

2つの技法は組み合わさります。結合は、再保存できない第三者のファイルを含め、どんなドキュメントも遅い回線の上で耐えられるものにします。線形化は、自分で作るドキュメントの最初のページを速く届けます。ローカルディスク上でメモリに抱えきれないファイルは、償却すべきラウンドトリップレイテンシのない別の問題で、直接ファイルAPIのワークフローにあるマップドファイルと遅延ストリームの経路が向いています

ランダムアクセスソースクラス、結合ラッパー、キャッシュ採用ポリシー、プログレッシブ線形化ロードの呼び出しは、フルソース付きのネイティブなDelphiとC++Builder PDFコンポーネントであるHotPDFに同梱されます。ライセンスと完全なAPIリファレンスは、HotPDF Delphi PDFコンポーネントページにあります