技術記事

PDFlibPas MovePage:継承ボックスがインスタンスを共有するとき

Delphi PDFライブラリであるPDFlibPasでは、MovePageで移動されたページが、旧Pagesノードから継承していたMediaBox、CropBox、Resourcesの値を自分専用のコピーとして受け取り、間接参照は参照のままであります。移動されたページに、旧Pagesノードが保持するのとまったく同じオブジェクトを渡すのが見た目通りの実装であり、それは、移動後のページへの後のSetPageBoxやDrawTextが、そのノードと、まだそこを継承しているすべての兄弟を静かに書き換えることを意味します。同じ「共有せずコピーする」規則は、関連する2つの経路も覆います。複数ページが共有する間接ボックスへのSetPageBoxと、ソースドキュメントのページ上へ継承値を実体化するCopyPageRangesです

ここに至る報告は、オブジェクトの同一性には一切触れません。「7ページをトリミングしたら8から12ページまでトリミングされた」「CropBoxを狭めたらMediaBoxが一緒に動いた」、そして一番混乱させる「ページを新ドキュメントへコピーしたら元ファイルが変わった」。クラッシュもリークもなく、保存されたファイルは完璧に有効なPDFです。ただ、誰も頼んでいないジオメトリが入っているだけです

1ページへのSetPageBoxが兄弟ページのサイズを変える理由

起こるのは、2つのページツリーエントリが1つのインメモリ配列を指し、SetPageBoxがそのターゲット配列をその場で編集するときです。同じインスタンスを保持するあらゆるページやPagesノードが、その編集を目にします。ページツリーエディタには、その共有を生み出しうる3つのコード経路があります:

  • MovePageは親から切り離す前に、継承可能な属性をページ上へ実体化します。コピーではなく祖先自身のオブジェクトを添付すると、移動されたページと旧兄弟が、ボックス配列とResources辞書を共有したままになります
  • 間接参照をたどり参照先の配列を編集するボックスライターは、1つの/MediaBox 11 0 Rオブジェクトを指すすべてのページを、1回の呼び出しでリサイズします。MovePageが関わっていたかどうかとは無関係です
  • CopyPageRangesは、ターゲットドキュメントへクローンする前に、ソースページ上へ継承値を実体化します。Pagesノードのインスタンスをソースページへ添付し、さらにデフォルトCropBoxとしてMediaBoxインスタンスそのものを添付すると、それらすべてが結び付きます
PDFlibPas MovePageのエイリアシングを示す図。移動されたページと旧兄弟がどちらも祖先自身のMediaBox配列インスタンスを保持し、SetPageBoxが1ページを編集すると他方がリサイズされます。v3.539.36以降、実体化はデコード済みコピーを添付し、編集は触ったページにローカルに留まります
2つのページツリーエントリーが1つのメモリ内配列を指していると、すべての編集がすべての保持者に着地します。しかも保存されたPDFはずっと有効なままでした

実体化そのものは、任意ではありません。/Resourcesだけを運んでいると、別の親の下へ移動されたページは、黙ってその親のサイズと回転を引き受けます。だからMovePageはMediaBox、CropBox、Rotateも運びます。ページを並べ替えるCollateDocumentsExが頼っているのも、この動作です。問いはただ1つ、それらの値がコピーとして届くのか、共有インスタンスとして届くのか、だけです

直接値、間接参照、ページ属性継承

継承ページ属性の正しいコピーは、直接値を複製し、間接参照は参照のまま保ちます。それがISO 32000-1自身が引いている区別だからです。辞書の中に書かれた[0 0 400 300]のような直接オブジェクトは、その辞書だけのものです。一度11 0 objと定義され11 0 Rとして引用される間接オブジェクトは、設計上共有されるものです。ISO 32000-1 §7.3.10は、ファイル内のどこからでもアドレス可能にし、すべての11 0 Rが同じオブジェクトを意味させます

ページ属性継承(ISO 32000-1 §7.7.3.4)は3つ目のケースを加えます。Resources、MediaBox、CropBox、RotateはPagesノードに置かれ、自分自身を定義しないすべての子孫ページに適用され得ます。ページは値を保持しません。/Parentを通して値を引いてくるのです。この引き回しのチェーンは、ページが親を変わった瞬間に切れます。だからMovePageとBalancePageTreeは、まず実効値をページ自身に書き込まなければなりません。問題は、どう書くかだけです

オブジェクトプールが間違いを隠す理由

PDFlibPasでは、パースされた、あるいは作成されたすべてのPDFオブジェクトはドキュメントのTPDFStructureプールが所有し、辞書と配列はエントリーへの素のポインターを保存します。TPDFDictionary.Addが記録するのはポインターだけです。だから1つのインスタンスを2つの親コンテナに追加するのは、ランタイムが検査できる全レベルで合法です。テアダウン時の二重解放もなく、狂う参照カウントもなく、例外もありません。シリアライズも同様に寛容で、各コンテナは共有インスタンスの現在値をインラインで書き出します。編集が入る前の出力は、正しいコピーが作るものとバイト単位で同じです

エイリアシングが表面化するのは、誰かが共有インスタンスをその場で変更したときだけです。SetPageBoxは既存配列への矩形ラッパーを通してまさにそれをやりますし、ページへの描画は、フォントや画像が登録されるときResources辞書に対して同じことをします。編集は、ポインターを保持する他のすべてのコンテナへ、静かに着地します

PDFlibPasが共有の代わりにコピーする仕組み

PDFlibPasは問題の両端で対処します。実体化はコピーを添付し、ボックスの書き込みはページが所有する配列だけを編集します。各規則は、相手ではカバーできないケースを1つカバーします

実体化ヘルパーのPLInheritPageAttributesは、ValueそのものではなくPage.Owner.Decode(Value.Output)を添付します。シリアライザーを通すラウンドトリップは、大雑把ですが正確な、PDFセマンティクスをタダで手に入れる方法です。直接の配列や辞書はリテラルテキストへシリアライズされ、新しく独立したインスタンスへデコードされます。間接参照は11 0 Rへシリアライズされ、同じオブジェクト11を指す新しい参照オブジェクトへデコードされるため、ページはインライン化されたコピーを受け取る代わりに、共有オブジェクトを引き続き参照します。コピーの深さは直接構造とちょうど同じです。コピーされた辞書の中で参照を通して辿り着くものは、ファイルフォーマットの意図どおり共有されたままです。BalancePageTreeは再親化するすべてのページで同じヘルパーを呼ぶため、そこで実体化されたページも別インスタンスを得ます

PDFlibPasの実体化ラウンドトリップを示す図。PLInheritPageAttributesがPage.Owner.Decode(Value.Output)を添付します。直接配列はリテラルテキストにシリアライズされて新インスタンスへデコードされ、間接の11 0 Rは共有オブジェクト11を指し続ける新しい参照へシリアライズ、デコードされます
シリアライズして再パースすれば、PDFオブジェクトのセマンティクスはタダで手に入ります。直接値はコピー、参照は参照のまま。ISO 32000-1の意図どおりです

コピーだけでは足りません。参照のケースは依然として共有オブジェクトを指しているからです。もしSetPageBoxがその参照をたどってオブジェクト11を編集したら、移動されたページはまたしても旧親とその他の子をリサイズします。そこでボックスライターはコピーオンライトを適用します。ページ自身のエントリーが直接配列のときだけその場で編集し、間接参照や欠落のボックスは新しい直接配列で置き換えます。オブジェクト11は、それを引用する他のすべてのページのために、手つかずのまま残されます

PDFlibPas SetPageBoxのコピーオンライト判断を示す図。ページ自身のエントリーが直接配列のときはその場で編集され、間接参照や欠落のときはライターが新しい直接配列へ置き換えるため、共有オブジェクト11は引用する他のすべてのページのために値を保ちます
実体化でのコピーだけでは足りません。参照は共有オブジェクトを指したままだからです。ボックスライターはページが所有するものだけを編集します
コード経路インスタンス共有(罠)PDFlibPas
MovePageの実体化ページが祖先自身の直接インスタンスを保持ページがデコード済みコピーを保持。参照は参照のまま
SetPageBox参照をたどり共有配列を編集ページ上の直接配列だけを編集。そうでなければ新規に書き込む
CopyPageRangesのソースページPagesノードのボックスを共有。CropBoxはMediaBoxインスタンスソースページの実体化された値はすべてコピー
ページリソースのクローン時のデフォルトボックスCropBox、BleedBox、TrimBox、ArtBoxが1つの配列を共有各デフォルトボックスが独自の配列を得る

最後の行が、微妙な行です。ライブラリがページキャプチャやマージのためにページのリソースをクローンするとき、欠落しているCropBox、BleedBox、TrimBox、ArtBoxのエントリを埋めますが、4つすべてを1つの配列インスタンスから埋めると、どれかを最初に編集する呼び出し元が現れるまで待ち構えるエイリアスを残すことになります。これらのデフォルトボックス値がどう選ばれるかはそれ自体が話題であり、PDFlibPasのTrimBox、BleedBox、CropBoxデフォルトのガイドで扱います

手組みのPDFでMovePageエイリアシングを再現する

ページツリー編集コードのエイリアシングをテストする最速の方法は、LoadFromStringでロードする小さな手書きPDFです。すべてのオブジェクト番号が事前に分かっています。下のヘルパーは、正しく計算されたバイトオフセットで古典的なクロスリファレンステーブルを書くため、テストは壊れたファイル向けのパーサーの復旧挙動に頼りません

uses
  System.SysUtils, PDFlibrary;

function BuildPdf(const Objects: array of AnsiString): AnsiString;
var
  Offsets: array of Integer;
  I, XRefPos: Integer;
begin
  Result := '%PDF-1.4'#10;
  SetLength(Offsets, Length(Objects));
  for I := 0 to High(Objects) do
  begin
    Offsets[I] := Length(Result);   // "N 0 obj"の0始まりバイトオフセット
    Result := Result + AnsiString(IntToStr(I + 1)) + ' 0 obj'#10 +
      Objects[I] + #10'endobj'#10;
  end;
  XRefPos := Length(Result);
  Result := Result + 'xref'#10'0 ' + AnsiString(IntToStr(Length(Objects) + 1)) +
    #10'0000000000 65535 f '#10;
  for I := 0 to High(Offsets) do      // 各エントリーはちょうど20バイト
    Result := Result + AnsiString(Format('%.10d 00000 n ', [Offsets[I]])) + #10;
  Result := Result + 'trailer'#10'<< /Size ' +
    AnsiString(IntToStr(Length(Objects) + 1)) + ' /Root 1 0 R >>'#10 +
    'startxref'#10 + AnsiString(IntToStr(XRefPos)) + #10'%%EOF'#10;
end;

function StreamObj(const Content: AnsiString): AnsiString;
begin
  Result := '<< /Length ' + AnsiString(IntToStr(Length(Content))) +
    ' >>'#10'stream'#10 + Content + #10'endstream';
end;

テストドキュメントには中間Pagesノードが2つあります。ノード3は間接MediaBox(オブジェクト11、400×300ポイント)、直接CropBox、直接Resources辞書を運び、2ページを所有します。ノード4はレターサイズのMediaBoxを持ち、3ページ目を所有します。ページ1を位置3へ移動すると、ノード4の下へ再親化されます。実体化がまさに必要な移動です。なければ、ページはレターサイズに化けます

procedure Check(Condition: Boolean; const Msg: string);
begin
  if not Condition then
    raise Exception.Create(Msg);
end;

procedure CheckMovedPageIsIsolated;
var
  Lib: TPDFlib;
  FontID: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Check(Lib.LoadFromString(BuildPdf([
      '<< /Type /Catalog /Pages 2 0 R >>',
      '<< /Type /Pages /Kids [3 0 R 4 0 R] /Count 3 >>',
      '<< /Type /Pages /Parent 2 0 R /Kids [5 0 R 6 0 R] /Count 2 ' +
        '/MediaBox 11 0 R /CropBox [10 20 390 280] /Resources << >> >>',
      '<< /Type /Pages /Parent 2 0 R /Kids [7 0 R] /Count 1 ' +
        '/MediaBox [0 0 612 792] >>',
      '<< /Type /Page /Parent 3 0 R /Contents 8 0 R >>',
      '<< /Type /Page /Parent 3 0 R /Contents 9 0 R >>',
      '<< /Type /Page /Parent 4 0 R /Contents 10 0 R >>',
      StreamObj('1 w'), StreamObj('2 w'), StreamObj('3 w'),
      '[0 0 400 300]']), '') = 1, 'load failed');

    Lib.SelectPage(1);
    Check(Lib.MovePage(3) = 1, 'MovePage failed');
    Lib.SelectPage(3);                       // 今まさに移動したページ
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'inherited MediaBox lost');

    Lib.SetPageBox(1, 0, 200, 200, 200);     // MediaBoxを200 x 200に
    Lib.SetPageBox(2, 0, 100, 100, 100);     // CropBoxを100 x 100に
    FontID := Lib.AddStandardFont(4);        // Helveticaフォント
    Lib.SelectFont(FontID);
    Lib.SetTextSize(12);
    Lib.DrawText(20, 20, 'MOVED');

    // 別のページを選択する前に旧親を検査する(下記参照)
    Check(Pos(AnsiString('/Font'), Lib.GetObjectToString(3)) = 0,
      'font registered in the old Pages node');

    Lib.SelectPage(1);                       // 旧ページ2、まだノード3の下
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'sibling MediaBox changed');
    Check(Abs(Lib.GetPageBox(2, 2) - 380) < 0.001, 'sibling CropBox changed');
    Check(Pos(AnsiString('400'), Lib.GetObjectToString(11)) > 0,
      'shared object 11 was rewritten');
  finally
    Lib.Free;
  end;
end;

GetPageBox(BoxType, Dimension)は、ボックスタイプ1がMediaBox、2がCropBox、ディメンション2が幅を取ります。デフォルトの左下原点では、SetPageBox(1, 0, 200, 200, 200)は左0、上200、幅200、高さ200を意味します。インスタンスを共有する実体化では、兄弟の検査が失敗します。CropBoxの編集はノード3の直接配列に着地し、参照をたどるボックスライターはオブジェクト11を書き換えます

CopyPageRangesはソースドキュメントを変えるのか

CopyPageRangesはソースページへ書き込みますが、書き込む値はすべて独立したコピーであるため、後のソース側の編集は、編集したページにローカルに留まります。書き込み自体は意図的なものです。ソースページの辞書がターゲットへクローンされる前に、明示的なMediaBox、CropBox、Rotate、Resourcesが必要であり、なければコピーは継承していたすべてを失います。ページの採番し直しとターゲットへのコピーは、PDFlibPasのクロスドキュメントオブジェクトディープコピーで扱います。ここでの罠はソース側に座っています。コピーは読むだけだと、たいていの人が思い込んでいる側です

保存された出力には、これが現れることは決してありません。共有でもコピーでも、実体化された値は同じようにシリアライズされるため、どちらの道でも両ドキュメントはバイト単位で同じ保存結果になります。エイリアスを暴くのは、コピーの後のソースドキュメントへの編集だけです:

procedure CheckSourceSurvivesCopy;
var
  Lib: TPDFlib;
  SourceID, TargetID: Integer;
begin
  Lib := TPDFlib.Create;
  try
    Check(Lib.LoadFromString(BuildPdf([
      '<< /Type /Catalog /Pages 2 0 R >>',
      '<< /Type /Pages /Kids [3 0 R 4 0 R] /Count 2 ' +
        '/MediaBox [0 0 400 300] /Resources << >> >>',
      '<< /Type /Page /Parent 2 0 R /Contents 5 0 R >>',
      '<< /Type /Page /Parent 2 0 R /Contents 6 0 R >>',
      StreamObj('1 w'), StreamObj('2 w')]), '') = 1, 'load failed');
    SourceID := Lib.SelectedDocument;

    TargetID := Lib.NewDocument;             // 選択中ドキュメントになる
    Check(Lib.CopyPageRanges(SourceID, '1') = 1, 'copy failed');

    Lib.SelectDocument(SourceID);
    Lib.SelectPage(1);
    Lib.SetPageBox(2, 50, 250, 100, 100);    // CropBoxだけ狭める
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'MediaBox followed CropBox');
    Lib.SetPageBox(1, 0, 200, 200, 200);

    Lib.SelectPage(2);
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'sibling page resized');

    Lib.SelectDocument(TargetID);            // コピーは元のサイズを保つ
    Lib.SelectPage(Lib.PageCount);
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'copied page resized');
  finally
    Lib.Free;
  end;
end;

ここの両ページは、ルートノードの直接MediaBoxを継承します。そのインスタンスをソースページ1へ添付し、さらにページ1のCropBoxとしてもう一度添付するコピーのステップは、CropBoxを狭めればMediaBoxが狭くなり、MediaBoxをリサイズすればルートノードを通してページ2がリサイズされる状態を作ります。ページをコピーしてからソースの編集を続けるワークフロー、たとえば元帳票のトリミング前に両面スキャンを1つのPDFへ整理するような流れこそ、この種のエイリアスが顔を出す場所です

インスタンスエイリアシングはなぜテストが難しいのか

インスタンスエイリアシングのテストが難しいのは、観測可能な効果が、特定の順序での3ステップを必要とするからです。エイリアスを作り、片側を変更し、他の何かが触れる前に反対側を検査する。ほとんどのテストは最初のステップしかやらず、保存出力を比較します。エイリアスがあろうがなかろうが、同じ出力です

PDFlibPasでの順序の罠はSelectPageです。ページを選択すると、現在のフォントがSelectFont経由で再適用され、そのフォントがページのリソースへ登録されます。自分の/Resourcesを持たないページは親の辞書へ解決されるため、その種のページを選ぶだけで、Pagesノードに/Fontが正当に追加されます。上のMovePageテストでは、旧ページ2の選択がノード3へHelveticaエントリを追加します。これは正しい挙動であって、リークではありません。GetObjectToString(3)の検査がSelectPage(1)の前に走るのはそのためです。2つを入れ替えると、エイリアスが存在しなくてもテストは失敗します

このルールは、PDFlibPasがあえて手を付けないものも示しています。Resources辞書を継承するページへのリソース書き込みは、祖先の辞書へ書き込まれ、すべての兄弟がその新しいエントリを見ます。これは仕様どおりに動く継承であって、インスタンス共有ではありません。共有辞書にフォントや画像の名前を追加しても、他のページの描かれ方は変わらないため、無害です。ページに継承をやめさせたいなら、まずそのページ専用のResources辞書を与えてください

PDFオブジェクトモデルコードのためのチェックリスト

この教訓は、プールとポインターコンテナの上に構築された任意のPDFオブジェクトモデルに一般化します。Delphiでも他でも:

  • ISO 32000-1 §7.7.3.4に従って継承属性を実体化するときは、直接値をディープコピーし、間接参照は同じオブジェクトへの新しい参照として保つ
  • 共有が意図され文書化されていない限り、既存インスタンスを2つ目のコンテナへAddしない。プールによる所有は、ランタイムが決して文句を言わないことを意味します
  • その場で編集するのは、現在のノードが直接オブジェクトとして所有するものだけ。間接や継承の値は新しい直接オブジェクトで置き換える(コピーオンライト)
  • MediaBoxから派生するCropBoxのように、別のエントリーから導かれるデフォルト値には、専用のインスタンスが要る
  • エイリアシングは、変更してから反対の保持者を検査するシーケンスでテストし、間に正当に書き込み得る呼び出しの順序も確認する
  • 保存出力の比較はここでは何も証明しない。共有とコピーの値は、最初の編集が入るまで同じようにシリアライズされる

PDFlibPasは、ページツリー編集、クロスドキュメントコピー、ページボックス制御を、Delphi、C++Builder、Free Pascal向けの1つのTPDFlibクラスで公開しています。エディション、プラットフォーム、完全なAPIリファレンスは、PDFlibPas Delphi PDF library製品ページを参照してください