技術記事

PDFiumのプログレッシブダウンロードとキャンセル(FPDFAvail)

ページ数ゼロの非nullドキュメントハンドル。これは、線形化されたことのないPDFに対してFPDFAvail_GetDocumentが返してくることがあり、しかもFPDFAvail_IsDocAvailがすでにPDF_DATA_AVAILを報告した後でさえそうなります。ハンドルは開いたように見え、何も文句は言わず、ビューアーは空のドキュメントを表示します。PDFiumのアベイラビリティAPIはISO 32000-1 附属書Fの線形化レイアウトを読むもので、それ以外のファイルは完全に到着してから、通常のカスタムドキュメント経路で開く必要があります。この経路振り分けの判断が、ダウンロード中のPDFを開く作業の半分です。もう半分は、ファイルの4分の1でタブを閉じ、しばらくして同じリンクをもう一度開くユーザーです

TPdfProgressiveDocumentの背後のアベイラビリティループ

PDFium Componentでは、セッション全体がTPdfProgressiveDocumentに住んでいます。ランダムアクセスストリームが満たされる間、PDFiumのアベイラビリティプロバイダーを生かし続けるTPdfサブクラスです。BeginProgressiveLoad(AStream, AFileSize, AOwnsStream, AInitialAvailableByteCount)はバッキングストリームとリモートファイルの論理サイズ(自分のローカルストアの現在の長さではなく、Content-Lengthのほう)を受け取り、IsDataAvailコールバックとAddSegmentコールバックを配線し、FPDFAvail_Createを呼びます。OpenProgressiveDocumentが成功した後は、そのオブジェクトは他のどのアクティブなTPdfと同じように振る舞います。ページ、テキスト、レンダリング、保存がすべて通常のメンバーを通じて動きます

パースのステップはどれも、あなたのコードへの質問です。PDFiumが範囲を欲しがるとき、コンポーネントは、その範囲がAvailableByteCountの表す連続接頭辞の内側にあるか、RangeRequestsスケジューラですでに完了した範囲の内側にあるとき、yesと答えます。そこからOnDataAvailableハンドラーが最後の言葉を得ます。そのどちらでも表せない範囲へ、スパースキャッシュが答えるための仕組みです。CheckDocumentAvailabilityは3つのTPdfDataAvailability値(pdaAvailable、pdaNotAvailable、pdaError)のいずれかを返し、PDFiumが求めたバイト範囲を、ソート・マージ済みのTPdfDownloadRanges配列として手渡します。それらの範囲は、あなたが見る時点ですでにrrpImmediate優先度でスケジューラにキュー済みです。したがってヒント配列はログと進捗表示のためのもので、仕事のキューはRangeRequestsです

// FetchRangeはあなたのトランスポート(HTTP Range GET、ソケット、blobリーダー):
// StoreのOffsetへSizeバイトを書き、届いた数を返す
function FetchRange(Store: TStream; Offset, Size: UInt64): UInt64; forward;

procedure OpenWhileDownloading(Pdf: TPdfProgressiveDocument; Store: TStream;
  RemoteSize: UInt64);
const
  MaxRounds = 64;
var
  Hints: TPdfDownloadRanges;
  State: TPdfDataAvailability;
  Request: TPdfRangeRequest;
  Round: Integer;
begin
  Pdf.BeginProgressiveLoad(Store, RemoteSize, False);
  State := pdaNotAvailable;
  for Round := 1 to MaxRounds do
  begin
    State := Pdf.CheckDocumentAvailability(Hints);
    if State <> pdaNotAvailable then
      Break;
    // ヒントは既にキュー済み。まずバイトを書いてから完了させる
    while Pdf.RangeRequests.TryDequeue(Request) do
      Pdf.RangeRequests.CompleteRequest(Request,
        FetchRange(Store, Request.Offset, Request.Size));
  end;
  if State <> pdaAvailable then
    raise EPdfError.Create('The document could not be discovered');
  Pdf.OpenProgressiveDocument;
end;

このループには、重みを持つ詳細が2つあります。ラウンド上限があるのは、死んだリンクがCheckDocumentAvailabilityに毎回同じ範囲を尋ねさせ、上限なしのループはネットワーク障害をUIのハングに変えるからです。順序が効くのは、スケジューラは自分の状態をクリティカルセクションで直列化するものの、バッキングストアのTStream.Positionには何もしないからです。トランスポートスレッドはCompleteRequestを呼ぶ前に、レスポンスのバイトをストリームへ書き込まなければなりません。完了が公開された瞬間、PDFiumはその範囲を読みに来るかもしれないのです。並行するライターにはpositioned I/Oか自分専用のロックが要ります

PDFium ComponentにおけるTPdfProgressiveDocumentのアベイラビリティループの図。BeginProgressiveLoadがFPDFAvailプロバイダを作り、CheckDocumentAvailabilityがrrpImmediate優先度でキュー済みの、ソート・マージ済みダウンロードヒントを手渡し、トランスポートはCompleteRequestが各範囲をPDFiumへ公開する前にストアへバイトを書き込みます。ループは64ラウンドで打ち止めです。死んだリンクは同じ範囲を尋ね続けるので
バイトを書いてからリクエストを完了させる。完了が公開された瞬間、PDFiumはその範囲を読みに来得ます。ストリーム位置を守ってくれるものはありません

AvailableByteCountが後戻りを拒む理由

AvailableByteCountは伸びる一方です。より小さい値を代入すると、「Available byte count cannot move backwards」というEPdfErrorが上がります。アベイラビリティコールバックがいったんPDFiumへ範囲の存在を告げたら、パーサーはすでにそこからオブジェクトを読んでキャッシュしているかもしれず、後からそのバイトを引き上げると、PDFiumは、アベイラビリティの答えが今や存在を否定するソースを持つオブジェクトを握り続けることになります。同じセッターはLogicalFileSizeより大きな値を拒否し、セッションの外では「No progressive load is active」を上げます

この最後の検査が、すでに手元にあるバイトの居場所を決めます。前回の訪問がファイルの最初の300 KBをキャッシュに残していたなら、その数をAInitialAvailableByteCountとして渡してください。コンポーネントはFPDFAvail_Createが走る前にそれを記録するため、PDFiumがヘッダーを最初に見るとき、すでにそこにあります。初期カウントがゼロのとき、Linearizationは、PDFiumがヘッダーを見るまでplnUnknownを読みます。それが普通の出発状態です

接頭辞を持ち上げることは、仕事のキャンセルでもあります。新しく告知されたバイトと重なる飛行中のリクエストはもう冗長なので、スケジューラはそれを落とし、OnCancelRequestを発火させます。そのリクエストへの遅いCompleteRequestはFalseを返します。順不同で満たされるストアは、接頭辞で自分を表現しようとすべきではありません。範囲はスケジューラ経由で完了させるか、OnDataAvailableで範囲ごとに答えてください。そのハンドラーの内側で上がった例外はCコールバックの境界を越えられないため、コンポーネントが受け止め、その範囲を欠落として報告し、PDFiumは次の検査でまた尋ねるだけです

部分的にダウンロードしたPDFが実際に開けるのはいつか

ファイル全体が届く前に開けるのは、線形化されたPDFだけです。OpenProgressiveDocumentはLinearizationプロパティ(plnUnknown、plnNotLinearized、plnLinearized)を検査し、ローダーを選びます。線形化ファイルは、最初のページセクションとヒントテーブルが揃い次第、FPDFAvail_GetDocument経由で開きます。非線形化ファイルは同じファイルアクセスレコードの上でFPDF_LoadCustomDocumentへ行き、その種のファイルではPDFiumは、全バイトが揃って初めてドキュメントを利用可能と報告します。この経路振り分けこそが、冒頭のゼロページハンドルをビューアーの外に留めておくものです

PDFium ComponentでOpenProgressiveDocumentが部分的ダウンロードを振り分ける方法の図。線形化ファイルは最初のページセクションとヒントテーブルの到着後、FPDFAvail_GetDocumentで開きます。非線形化ファイルはFPDF_LoadCustomDocumentと全バイトを要します。LoadAvailablePageはページ確認の前にFPDFAvail_IsFormAvailでフォームの可用性を確認し、非nullのゼロページハンドルの罠を避けます
先手を取れるのは線形化ファイルだけです。それ以外ではFPDFAvail_GetDocumentが、開いたように見えてページゼロの文書を返し得ます。振り分けが防ぐのはまさにそれです

つまりサーバー上のファイルが、最初のページが現れる速さを決めます。初回描画までの時間が大事で、公開側を自分で握っているなら、そこでファイルを線形化してください。TPdf.SaveAsLinearizedはコンポーネント自身から附属書Fのレイアウトを書き出し、Fast Web Viewとヒントテーブルのウォークスルーがそのレイアウトの中身を扱います。握っていないファイルでも、非線形化PDFは同じループを通ってロードされます。ただ100パーセントまで早くpdaAvailableに届かないだけです

LoadAvailablePageは1始まりのページ番号を受け取り、PDFiumが期待する順序を守ります。最初のページ検査の前にCheckFormAvailability、つまりFPDFAvail_IsFormAvailを包むものを実行し、その後でのみFPDFAvail_IsPageAvailを呼びます。pfaNotPresentはAcroFormのないドキュメントへの普通の答えで、何も妨げません。ページの準備ができたら、LoadAvailablePageはそれをアクティブページにします。線形化されたパンフレットの1ページ目は、後続ページがまだ輸送中でもレンダリングできるわけです。ページ待ちは最初のコード例と同じ形です。LoadAvailablePageを呼び、pdaNotAvailableでRangeRequestsを排出し、pdaAvailableかpdaErrorで止まり、ラウンド上限を持つ。FirstAvailablePageNumberは、線形化辞書が最初と指名するページを、PDFiumの0始まりインデックスからの変換済みで報告します。非線形化ファイルではどのページも即座にpdaAvailableを報告します。ドキュメントはファイルが完全になったときにしか開けなかったのですから

レンジスケジューラのリトライ、ショートリード、優先度

FPDFAvail_*APIそのものは、ネットワークについて何も知りません。パーサーが今どんなバイトを必要とするかを言い、後でまた尋ねるだけです。リクエストもリトライもキャンセルという概念もありません。それらを供給するのがTPdfRangeRequestSchedulerで、その4つの規則がトランスポートの書き方を形作ります

  • 短い応答は進捗として扱われます。要求より少ないバイトでのCompleteRequest(Request, BytesReceived)は接頭辞を公開し、残りをキューに入れます。短い応答は失敗試行としても数えられるため、残りは依然としてMaxRetryCountに縛られ、使い切ると放棄されます。ゼロバイトは素の失敗試行です
  • MaxRetryCountのデフォルトは2なので、1つの範囲に合計3回の試行が許されます。FailRequestは範囲を再キューしたときTrueを返し、範囲が放棄されたらFalseを返します。Statistics.AbandonedRequestCountが諦めた数を追跡します
  • MaxRequestSizeは大きな範囲をデキュー時にチャンクへ分割し、MergeGapは2つの保留中の範囲を小さな未知のギャップ越しにマージさせます。ただし完了済みや飛行中のバイトを越えることは決してありません
  • CheckDocumentAvailabilityとLoadAvailablePageからのヒントはrrpImmediateで届きます。直接のCheckFormAvailability呼び出しからのフォームヒントはrrpNormalです。LoadAvailablePageがその検査を自分で実行し、フォームデータが欠けているときは、ヒントはrrpImmediateでキューされます。TryDequeueは常に最も高い優先度を先に、同じ優先度内では最小のオフセットから処理します

優先度の規則が効くのは先読みです。ドキュメントが開いた直後にファイル全体をrrpBackgroundでキューすると、スケジューラーはすでに完了済みや飛行中のものを差し引き、欠けているバイトだけを回線に載せます。その後ユーザーがページ40へ跳び、そのページのヒントがすでにダウンロード中のバックグラウンドチャンクと重なると、スケジューラーはバックグラウンドリクエストを引き戻し、OnCancelRequestを発火し、重ならない後ろ身をリトライのカウントなしでバックグラウンド優先度へ戻し、重なりを新しいimmediate仕事としてキューします。跳びが接続を勝ち取ります。これがなければ、ページのリクエストは、関係ない256 KBチャンクの後ろで待たされるところでした

procedure TDownloadForm.QueueRestOfFile;
var
  Whole: TPdfDownloadRanges;
begin
  FPdf.RangeRequests.MaxRequestSize := 256 * 1024;  // チャンクサイズはあなたの判断
  SetLength(Whole, 1);
  Whole[0].Offset := 0;
  Whole[0].Size := FPdf.LogicalFileSize;
  FPdf.RangeRequests.EnqueueHints(Whole, rrpBackground);
end;

// 1つのHTTP Rangeレスポンスが終わったときにワーカースレッドで呼ばれる。
// WriteAtはバッキングストアへの自前のpositioned書き込み
procedure TDownloadForm.RangeFinished(const Request: TPdfRangeRequest;
  const Body: TBytes; Succeeded: Boolean);
begin
  if Succeeded and (Length(Body) > 0) then
  begin
    WriteAt(FStore, Request.Offset, Body);              // 先にバイト
    FPdf.RangeRequests.CompleteRequest(Request, Length(Body));
  end
  else if not FPdf.RangeRequests.FailRequest(Request) then
    TThread.Queue(nil, ShowRangeGaveUp);  // 放棄されたか、キャンセルされたセッションからのもの
end;

CompleteRequestもFailRequestも、ワーカースレッドから呼んで安全です。スケジューラーは自分のロックを取ります。差し替えられたリクエストや、キャンセルされたセッションに属するリクエストは、何にも触れずにFalseで戻るため、ワーカーは自分の範囲がなぜ古くなったかを知る必要がありません

CancelProgressiveLoadは何をどんな順で解放するのか

CancelProgressiveLoadは、4ステップでセッションを解体します。常に同じ順序です。レンジスケジューラーをキャンセルし、ドキュメントを閉じ、アベイラビリティハンドルをFPDFAvail_Destroyで破棄し、それからコールバックレコードを廃棄してストリームアダプターを解放する。スケジューラーのキャンセルが最初なのは、ジェネレーションカウンターを進め、保留中と飛行中の全リクエストを落とし、飛行中のそれぞれにOnCancelRequestを発火させるからです。その後に着地するトランスポート完了は古いジェネレーションを運び、CompleteRequestはFalseを返します。ドキュメントは、アベイラビリティハンドルとストリームアダプターが消える前に閉じられます。PDFiumはドキュメントを閉じている最中もファイルアクセスプロバイダーを通じて読み続けられるからです

PDFium ComponentにおけるCancelProgressiveLoadの固定解体順序の図。まずレンジスケジューラをキャンセルし、遅れた完了が進められたジェネレーションカウンタに当たってFalseを返すようにします。ファイルアクセスアダプタが消える前に文書を閉じ、アベイラビリティハンドルをFPDFAvail_Destroyで破棄し、その後にコールバックレコードを廃棄してストリームアダプタを解放します
1つのべき等メソッドが、失敗した開始もユーザーによるキャンセルもデストラクタも同じように片付けます。ワーカースレッドがストアへ書き込む構成では、ストリームの所有権はあなたの手元に
procedure TDownloadForm.FormCreate(Sender: TObject);
begin
  FPdf := TPdfProgressiveDocument.Create(nil);
  // スケジューラはFPdfと同じ寿命なので、配線は1回でいい
  FPdf.RangeRequests.OnCancelRequest := RangeCancelled;
end;

procedure TDownloadForm.RangeCancelled(Sender: TObject; RequestId: UInt64;
  Attempt: Cardinal);
begin
  FTransport.Abort(RequestId);   // あなたのコード:そのソケットかリクエストを閉じる
end;

procedure TDownloadForm.CancelButtonClick(Sender: TObject);
begin
  FPdf.CancelProgressiveLoad;
  // ProgressiveLoading = False, Active = False, AvailableByteCount = 0
end;

このメソッドはべき等で、3つの状況に対する唯一の後片付け経路です。構築の途中で失敗したBeginProgressiveLoad、明示的なユーザーによるキャンセル、そしてデストラクタです。BeginProgressiveLoad自身もこれを呼ぶため、前のセッションが開くまでに至らなかったなら、同じオブジェクトを新しいURLで再開するのは問題ありません。OpenProgressiveDocumentが成功した後はオブジェクトはアクティブであり、BeginProgressiveLoadはおなじみの「Cannot perform this operation on an active」エラーを上げます。先にCancelProgressiveLoadを呼んでください。OnCancelRequestはまた、あなたのソケットが閉じられる唯一の場所です。スケジューラーにはソケットという概念がないためです。その内側で上がった例外はリクエストごとに飲み込まれ、1つの失敗したabortが残りを塞ぐことはありません

ストアを書く人が所有者を決めます。ワーカースレッドがバッキングストリームへ書き込む構成では、AOwnsStream = Falseを渡し、ワーカーが止まった後に自分でストリームを解放してください。所有権を渡すと、キャンセルがストリームを解放する一方で、すでに進行中の書き込みがまだ道の途中かもしれないのです。呼び出し元以外のスレッドがストアに触れるときは、常に所有権を手元に保ってください。AOwnsStream = Trueがはまるのは、最初のコード例のような完全に同期のトランスポートだけです

ファイル全体を待つ機能

パース済みドキュメントではなく元ファイルのバイトを必要とする機能があり、それらは不完全なプログレッシブソースをまっすぐ拒みます。ReadXmpPacketは「PDF/A metadata is unavailable until progressive loading completes」を上げます。ValidatePadesはSourceStatusがpvssIncompleteの結果を返し、ValidatePdfMacは完全なソースを求めるメッセージつきで未対応を報告します。BeginIncrementalSaveも失敗します。増分更新は、ロードされた正確なバイトへ追記しなければならないからです

その背後にある完全性の検査は、AvailableByteCountがLogicalFileSizeに届くことです。したがってすべてをスケジューラー経由で届けたトランスポートは、全バイトを握りながらも、ソースが不完全だと告げられ得ます。連続接頭辞が動かなかったからです。スケジューラーが完全なカバーを確認したら、接頭辞を公開してください:

procedure TDownloadForm.CheckSignaturesWhenComplete;
var
  Report: TPadesValidationResult;
begin
  if FPdf.RangeRequests.IsRangeAvailable(0, FPdf.LogicalFileSize) then
    FPdf.AvailableByteCount := FPdf.LogicalFileSize;
  Report := FPdf.ValidatePades;
  if Report.SourceStatus = pvssIncomplete then
    LabelStatus.Caption := 'Signatures are checked when the download finishes'
  else
    ShowSignatureReport(Report);   // 自前のUI
end;

このどれが始まる前に適用されるサイズ上限が1つあります。WindowsではFPDF_FILEACCESSがファイル長を32ビットフィールドに保存するため、BeginProgressiveLoadは4 GiBを超える論理サイズを、PDFiumに切り詰められた長さをパースさせる代わりにEPdfErrorで拒否します

完全なローカルファイルをストリームアダプター経由でオンデマンドでロードするのは、PDFiumで大きなPDFをオンデマンドでストリーミングするをご覧ください。より大きなバッファーの内側に座るPDFは、埋め込みPDFのバイトレンジローディングです。すでに届いたページの遅いレンダリングを止めるのは別の仕組みで、キャンセル可能なプログレッシブページレンダリングで扱っています。TPdfProgressiveDocumentとそのレンジスケジューラー、SaveAsLinearizedは、DelphiとC++Builder向けPDFium Componentの一部です