技術記事

HotPDF RenderCacheFolder:Delphiのディスクページキャッシュ

ファイル名を鍵にしたページキャッシュは、同じ名前のまま夜中に新しいリビジョンで上書きされたPDFに、昨日のページを見せます。ファイル全体のSHA-256を鍵にしたキャッシュはその間違いを決してしませんが、400 MBのスキャンアーカイブでは、ハッシュがユーザーが実際に開く2ページのレンダリングより長くかかり得ます。実用的な鍵はその2つの間にあり、それを選ぶことは2つ目の決定も強制します。メモリー内の編集が、すでにディスクに座っているページに何をすべきか、です

RenderCacheFolderディスク層はメモリーキャッシュの背後でどう座るのか

HotPDF RenderCacheFolderはHotPDF Delphiコンポーネントのメモリー内ラスタキャッシュの背後に永続層を足し、プロパティが空でないパスを保持するときにだけ参加します。RenderLoadedPageToBitmapCached(PageIndex, DPI)の呼び出しは最初にメモリーを確認し、ページインデックス、DPI、現在のレンダリング設定を鍵に使います。ミスならディスクに尋ねます。ディスクヒットは保存されたPNGをデコードし、メモリーへ戻してプロモートし、あなたにコピーを渡します。両層ともミスのときだけ、ページはロード済みPDFページをTBitmapへレンダリングする記事のフルレンダラーを通り、その新しいビットマップは出口でディスクへ書かれます

RenderLoadedPageToBitmapCachedに対するHotPDFの描画キャッシュ探索を示す図。ページ、DPI、描画バリアントをキーとするメモリ内層が最初に検査され、次にアトミック置換付きのPNGファイルからなるRenderCacheFolderディスク層、最後にコンテンツストリームインタープリターが検査され、すべてのヒットは呼び出し側所有のコピーを返します
HotPDFはまずメモリを見て、次にディスクを見て、それでもなければラスタライズします。ディスクヒットはメモリへ戻されてプロモートされ、どの経路もあなたが所有し解放すべきコピーを手渡します

フォルダーレイアウトはExplorerで覗けるほど素朴です。各ドキュメントは、16桁の16進ドキュメントキーと16桁の16進レンダリング設定キーを組み合わせた名前のサブフォルダーを受け取り、各ページは<page>@<dpi>.pngとしてそこに着地します。ルートのindex.txtがスキーマタグの下でドキュメントを最終使用順に列挙し、タグが一致しなければ、フォルダー全体が最初の使用でクリアされます。PNGとindexの書き込みは最初に一時ファイルへ行き、それから置換既存フラグ付きのMoveFileExWで入れ替わるので、書き込みの途中のクラッシュは前のファイルかファイルなしを残します。デコードに失敗したPNGは削除され、ミスとして数えられます

3つの上限がフォルダーが無限に育つのを防ぎます

  • 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
    // ディスク層はフォルダーと両上限を最初のキャッシュ付き
    // レンダリングで1度読む。だからその呼び出しの前に設定する
    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;

同じファイルでこの手続きを2回走らせると、2回目のパスは上限に収まったものを何もラスタライズしません。ディスクキャッシュは最初のキャッシュ付きレンダリングで作られ、THotPDFインスタンスと同じ寿命を持つので、その時点の後にフォルダーやどちらかの上限を変えても、移動もリサイズもされません。ページをディスクから外す条件がもう2つあります。メモリーキャッシュのデフォルトのエントリーあたり天井(32ビットピクセルで64 MiB、4096×4096ページ)を超えるビットマップは保存されません。そしてディスク層が相談されるのはRenderFallbackPolicyがデフォルトのrfpIgnoreに留まっている間だけです。PNGはピクセルを運びますが、より厳しいポリシーが報告するフォールバック診断は1つも運ばないからです

自明なキャッシュキーはなぜ失敗するのか

3つのキーがまず頭に浮かび、それぞれ別のやり方で失敗します。ファイルパスは上書きで失敗します。PDFバイトのメモリー内コピーのハッシュは、ファイルをその場で読むパーサがそういうコピーを保持する理由はないと気付くまで安全に見えます。決して満たされなかったバッファをハッシュすると空のキーが得られ、空のキーを「ディスクをスキップ」と扱うキャッシュは、正しく設定されたフォルダーに1枚もPNGを届けません。ディスクからファイル全体をハッシュするのは機能しますが、オープンのたびに全バイトを読む代償を払います

より手強い罠は無効化です。こういうコンポーネントは、メモリー内ページをすべてのロードの冒頭、すべての編集の後、破棄のときにクリアしなければならず、魅力的な手は同じ場所でドキュメントのディスクフォルダーを削除することです。それをやると、すべてのビューアセッションが出口で自分のキャッシュを拭き、翌朝はとにかく冷えた状態から始まります。編集の後に変わっていないソースからキーを再計算するのはさらに悪いです。編集済みのレンダリングが元ファイルのキーの下に着地し、次に無傷のPDFを開く人へ供給されます。アイデンティティと無効化は一体として設計されねばなりません。どちらかを間違えると、決してヒットしないキャッシュか、ファイルが含まないページを見せるキャッシュを出荷することになります

HotPDFはPDFソースをどうフィンガープリントするのか

HotPDFはLoadFromFileでロードしたPDFを、サイズ、最終書き込み時刻、最初と最後の64 KiBをSHA-256でハッシュすることで識別し、ストリームやランダムアクセスソースはコンテンツ全体のSHA-256で識別します。アイデンティティはロードが成功したときに1回捕捉され、ダイジェストの最初の16桁の16進(64ビット)がドキュメントキーになります

ソースアイデンティティコスト捕捉される時
LoadFromFileサイズ+最終書き込み時刻+先頭と末尾の64 KiBをSHA-256でハッシュファイルサイズに関係なく最大128 KiBの読みすべての成功したロード。RenderCacheFolderが後から設定されていても
LoadFromStreamストリーム全体のSHA-256ソースの1回の完全パスRenderCacheFolderがロードの前に設定されていたときだけ
LoadFromRandomAccessSourceソース全体のSHA-256ソースの1回の完全パスフォルダーが先に設定され、全バイトレンジが利用可能なときだけ
/Encryptエントリーを持つ任意のソースなしなし決してない。ディスク層はバイパスされる
ディスク描画キャッシュに対するHotPDFのソースアイデンティティマップを示す図。LoadFromFileはサイズ、LastWriteTime、先頭と末尾の64 KiBをハッシュし、LoadFromStreamとLoadFromRandomAccessSourceはRenderCacheFolderが先に設定されていたときにだけコンテンツ全体をハッシュし、/Encryptトレーラーを持つソースはいかなるアイデンティティも取得しません
ファイルは両端からフィンガープリントされます。ヘッダー、xref、トレーラーはそこに住んでいるからです。ストリームは先にキャッシュを要求したときにだけ全体ハッシュの代金を払い、暗号化ドキュメントは決してディスクへ書かれません

デスクトップビューアにはサンプリングフィンガープリントが正しいデフォルトであり、オープンのたびの完全ハッシュは間違ったデフォルトです。2つのサンプル領域はファイル構造から選ばれました。ヘッダーは冒頭に座り、トレーラーと最後のcross-referenceセクションは終端に座ります(ISO 32000-1 §7.5)。インクリメンタル更新は新しいボディ、cross-referenceセクション、トレーラーを追記し(§7.5.6)、サイズと末尾を一緒に変え、通常の完全リライトは最終書き込み時刻を押し上げます。128 KiB未満では2つのサンプルが重なり全バイトをカバーするので、小さなドキュメントはどのみち全体がハッシュされます

すり抜けるのは、大きなファイルの中ほどの同サイズ編集を、その後元のタイムスタンプを復元するツールが行う場合です。内容を変えながら変更時刻を保つことにしたエディターは存在しますが、希であり、そういうファイルに対してキャッシュは古いページを供給します。逆のケースは自分の味方です。Windowsのファイルコピーは最終書き込み時刻を保つので、キャッシュ済みドキュメントのコピーは同じエントリーにヒットします。バイトが一致しているのだから正しい挙動です

ストリームにタイムスタンプはありません。コンテンツだけが正直なアイデンティティなので、HotPDFが完全SHA-256パスの代金を払うのは、ロードの前にディスクキャッシュが要求されたときだけです。キャッシュフォルダーなしでLoadFromStreamを呼ぶコードは追加の代金を払いません。だから2行の順序が効いてきます

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、スキーマ変更のときだけです

キーはディスク上のファイルを記述します。ページにスタンプを押したり注釈を変えたりしたら、メモリー内のドキュメントはそれともう一致しないので、そのキーの下での読みも書きも正直ではありません。InvalidateRenderedPageCacheと、編集が引き起こすページごとの無効化は、どちらもアイデンティティをクリアし、フォルダーには触れません。何も無効化しなかった編集経路には2つ目の検査が効きます。各ディスク参照の前に、THotPDFはロード済みオブジェクトのどれかが未保存の変更を運ぶか尋ね、1つでも運んでいれば、ドキュメントはアイデンティティを持たないものとして扱われます

レンダリング設定は逆方向へ行きます。PageRenderBackend(UseNativeGDIRenderBackendが代わりにやってくれるもの)の代入、ConfigureRenderICCWorkflowやClearRenderICCWorkflowの呼び出しは、メモリー内のページを流しますが、アイデンティティは保ちます。ドキュメントはまだファイルと一致しているからです。それらの設定はメモリーキーに現れずにピクセルを変えるので、ディスクキーはバックエンド名、ブラックポイント補正フラグ、ICCプルーフと出力プロファイルのSHA-256ダイジェストを折り込みます。メモリーキーは既に、カラーインテント、出力ディザリング、オーバープリントプレビュー、ルミノシティマスクモード、フォールバックポリシー、すべてのoptional content groupの可視性をカバーしています

RenderCacheFolderディスクキャッシュに対するHotPDFの無効化セマンティクスを示す図。ロード済みドキュメントやダーティオブジェクトの編集はソースアイデンティティを落として層をバイパスさせ、描画バックエンドや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);

  // 同じドキュメントキー、別のレンダリング設定キー:このページは
  // 2つ目のフォルダーから読まれるかそこへ書かれ、デフォルトビューは無傷です
  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を通して古くなります。編集前の元を開き直せば、そのページはまだそこにあります

暗号化ソース、ジャンクション、共有ルート

HotPDFディスクレンダーキャッシュは2つの入力を意図的に拒否します。暗号化PDFのページと、ジャンクションやその他のreparse pointであるドキュメントサブフォルダーです。どちらの規則も、キャッシュヒットを安全性と取引きしています

暗号化PDFはメモリーにとどまる

レンダリングされたページは復号済みコンテンツです。それを素のPNGとしてキャッシュフォルダーへ書くと、パスワード保護ドキュメントの読めるコピーが、作者が選んだ保護の外のディスクに残ります(ISO 32000-1 §7.6)。HotPDFは、トレーラーが/Encryptエントリーを運ぶソースには、パスワードで開かれたか空のユーザーパスワードで開かれたかに関係なく、アイデンティティを捕捉しません。それらのドキュメントはそれでもメモリー層を使い、それはプロセスとともに消えます

リンクされたドキュメントフォルダーはスキップされる

キャッシュルートは自分で選べるもので、ジャンクションを指すのは構いません。違うのはその下のサブフォルダーです。キャッシュは起動時の後片付け、参照、保存、3つの追い出し上限の間に、それらを自分で作り、触り、削除します。ルートへの書き込みアクセスを持つ誰かがドキュメントフォルダーを別のディレクトリーへのジャンクションにすげ替えたら、それらの操作はすべてそれに従い、追い出しは別の場所のファイルを削除します。各エントリーポイントは最初にフォルダーの属性を読み、reparse pointと印されたものをスキップします。参照はミスを数え、保存は書き込み失敗を数え、追い出しは放置します

Unicodeパスとプロセスごとの1ルート

RenderCacheFolderはUnicodeのstringであり、アトミック置換はワイドのWindows APIを呼ぶので、システムコードページの外のプロファイルパス(たとえば英語版Windowsでの中国語ユーザー名)はキャッシュに無傷で届きます。1つのプロセスの中で同じルートへ解決される(パス展開後に大文字小文字を無視して比較される)複数のTHotPDFインスタンスは、1つの参照カウント付きindexと1つのロックを共有します。上限にとって重要です。別々のindex.txtのコピーは、部分的なビューに対してそれぞれ500 MB予算を強制し、フォルダーをそれの何倍も越えて育てさせてしまいます

共有はプロセス境界で終わります。同じルート上の2つのプロセスは別々のメモリー内indexを保持するので、同時に走るアプリケーションごとに自分のルートを与えるべきです。1つのプロセスの内側のワーカースレッドは構いません。PrefetchLoadedPagesと、リクエストキュー付きのバックグラウンドレンダリングのキューは、同じキャッシュ付き経路と同じロックを通ります

出荷前に正しく設定すべき項目

  • フォルダーと両上限は最初のキャッシュ付きレンダリングの前に、ストリームやランダムアクセスのロードではロードの前に設定する
  • メモリーだけのレンダリングになるのは、暗号化PDF、ロード後に編集されたドキュメント、そしてRenderFallbackPolicyがrfpIgnoreでないときと予期する
  • %LOCALAPPDATA%のようなユーザーごとの場所の下に、走っているアプリケーションごとのキャッシュルートを与える

永続ページキャッシュがディスクスペースの元を取るのは、同じドキュメントを1日中開き直すビューアです。このブログのDelphiでのカスタムPDFビューアアーキテクチャーの背後のワークロードです。ディスク層、メモリーラスタキャッシュ、ページレンダラーはすべてHotPDF Delphi PDF componentの一部であり、DelphiとC++Builderで利用できます