Artykuł techniczny

PDFlibPas MovePage: gdy dziedziczone boxy dzielą instancje

W PDFlibPas, bibliotece PDF dla Delphi, strona przeniesiona przez MovePage dostaje własne kopie wartości MediaBox, CropBox i Resources, które dziedziczyła ze swojego starego węzła Pages, a referencja pośrednia zostaje referencją. Podanie przeniesionej stronie dokładnie tych samych obiektów, które trzyma stary węzeł Pages, to oczywista implementacja — i znaczy, że późniejsze SetPageBox albo DrawText na przeniesionej stronie po cichu przepisze ten węzeł i każdą siostrę nadal dziedziczącą z niego. Ta sama reguła kopiuj-nie-dziel obejmuje dwie powiązane ścieżki: SetPageBox na pośrednim boxie współdzielonym przez kilka stron oraz CopyPageRanges, które materializuje wartości dziedziczone na stronach dokumentu źródłowego

Objawy tego rodzaju aliasingu nigdy nie wspominają o tożsamości obiektów. Brzmią jak „obciąłem stronę 7, a strony 8 do 12 też się obcięły", albo „zawęziłem CropBox, a MediaBox ruszył się razem z nim", albo — najbardziej mylące — „skopiowałem stronę do nowego dokumentu, a oryginalny plik się zmienił". Nic nie kracze, nic nie cieknie, a zapisany plik jest całkowicie poprawnym PDF-em. Po prostu zawiera geometrię, o którą nikt nie prosił

Jak SetPageBox na jednej stronie może przeskalować jej siostry?

Dzieje się tak, gdy dwa wpisy drzewa stron celują w jedną tablicę w pamięci, a SetPageBox edytuje swoją tablicę docelową na miejscu: każda strona albo węzeł Pages trzymające tę samą instancję widzą edycję. Trzy ścieżki kodu w edytorze drzewa stron mogą wyprodukować takie współdzielenie:

  • MovePage materializuje atrybuty dziedziczne na stronie przed odłączeniem jej od rodzica; przypięcie własnych obiektów przodka zamiast kopii zostawia przeniesioną stronę i jej dawne siostry współdzielące tablicę boxa i słownik Resources
  • Pisarz boxów, który podąża za referencjami pośrednimi i edytuje wskazywaną tablicę, przeskaluje jednym wywołaniem każdą stronę celującą w jeden obiekt /MediaBox 11 0 R — niezależnie od tego, czy MovePage w ogóle brał udział
  • CopyPageRanges materializuje wartości dziedziczone na stronie źródłowej przed sklonowaniem jej do dokumentu docelowego; przypięcie instancji węzła Pages do strony źródłowej, plus samej instancji MediaBox jako domyślnego CropBoxa, spią wszystkie te elementy razem
Aliasing w MovePage w PDFlibPas: przeniesiona strona i jej dawna siostra trzymały obie instancję tablicy MediaBox przodka, więc SetPageBox edytował jedną stronę, a przeskalowywał drugą; od v3.539.36 materializacja przypina zdekodowane kopie, a edycje zostają lokalne w stronie, której dotykasz
Dwa wpisy drzewa stron wskazujące na jedną tablicę w pamięci sprawiały, że każda edycja lądowała u każdego posiadacza, a zapisany PDF cały czas pozostawał poprawny

Materializacja sama w sobie nie jest opcjonalna. Przenieś tylko /Resources, a strona przeniesiona pod innego rodzica po cichu przejmie jego rozmiar i obrót — dlatego MovePage wozi też MediaBox, CropBox i Rotate, na czym polega CollateDocumentsEx, gdy przestawia strony. Jedynym pytaniem jest, czy te wartości przychodzą jako kopie, czy jako współdzielone instancje

Wartości bezpośrednie, referencje pośrednie i dziedziczenie atrybutów strony

Poprawna kopia dziedziczonego atrybutu strony powiela wartości bezpośrednie i zostawia referencje pośrednie referencjami, bo takie rozróżnienie wprowadza sam ISO 32000-1. Obiekt bezpośredni, taki jak [0 0 400 300] zapisany w słowniku, należy tylko do tego słownika. Obiekt pośredni, zdefiniowany raz jako 11 0 obj i cytowany jako 11 0 R, jest z założenia współdzielony: ISO 32000-1 §7.3.10 czyni go adresowalnym z dowolnego miejsca pliku, a każde 11 0 R znaczy ten sam obiekt

Dziedziczenie atrybutów strony, ISO 32000-1 §7.7.3.4, dodaje trzeci przypadek. Resources, MediaBox, CropBox i Rotate mogą siedzieć na węźle Pages i obowiązywać każdą stronę potomną, która nie definiuje własnych. Strona nie trzyma wartości; odszukuje ją przez /Parent. Ten łańcuch odszukiwania pęka w momencie, gdy strona zmienia rodzica, dlatego MovePage i BalancePageTree muszą najpierw zapisać wartości efektywne na samej stronie. Pytanie brzmi tylko, jak je zapisać

Dlaczego pula obiektów ukrywa błąd

W PDFlibPas każdy sparsowany albo utworzony obiekt PDF jest własnością puli TPDFStructure dokumentu, a słowniki i tablice trzymają gołe wskaźniki na swoje wpisy. TPDFDictionary.Add zapamiętuje wskaźnik i nic poza tym. Dodanie jednej instancji do dwóch kontenerów rodzicielskich jest więc legalne na każdym poziomie, jaki runtime potrafi sprawdzić: żadnego podwójnego zwolnienia przy demontażu, żadnej liczby referencji, która mogłaby się pogubić, żadnego wyjątku. Serializacja jest równie wyrozumiała, bo każdy kontener zapisuje bieżącą wartość współdzielonej instancji inline, a przed jakąkolwiek edycją wyjście jest bajt w bajt tym, co wyprodukowałaby poprawna kopia

Aliasing wychodzi na jaw dopiero, gdy ktoś zmienia współdzieloną instancję w miejscu. Dokładnie to robi SetPageBox przez prostokątny wrapper na istniejącej tablicy, a rysowanie po stronie robi to ze słownikiem Resources w chwili rejestracji fontu albo obrazu. Edycja ląduje, po cichu, w każdym innym kontenerze trzymającym wskaźnik

Jak PDFlibPas kopiuje zamiast dzielić

PDFlibPas łapie problem na obu końcach: materializacja przypina kopie, a zapisy boxów edytują wyłącznie tablicę, którą strona posiada. Każda reguła pokrywa przypadek, którego druga nie obejmie

Pomocnik materializacji, PLInheritPageAttributes, przypina Page.Owner.Decode(Value.Output) zamiast samego Value. Podróż przez serializator tam i z powrotem to tępy, ale dokładny sposób zdobycia semantyki obiektów PDF za darmo. Bezpośrednia tablica albo słownik serializuje się do swojego dosłownego tekstu i dekoduje do świeżej, niezależnej instancji. Referencja pośrednia serializuje się do 11 0 R i dekoduje do nowego obiektu referencji celującego w ten sam obiekt 11, więc strona nadal odnosi się do współdzielonego obiektu zamiast dostać skopiowaną treść w linii. Kopia jest dokładnie tak głęboka jak struktura bezpośrednia: wszystko osiągalne przez referencję wewnątrz skopiowanego słownika pozostaje współdzielone, tak jak zamierza format pliku. BalancePageTree woła ten sam pomocnik dla każdej przenoszonej strony, więc strony materializowane tam też dostają osobne instancje

Podróż materializacji w obie strony w PDFlibPas, gdzie PLInheritPageAttributes przypina Page.Owner.Decode(Value.Output): tablica bezpośrednia serializuje się do dosłownego tekstu i dekoduje do świeżej instancji, a pośrednie 11 0 R serializuje się i dekoduje do nowej referencji, która wciąż wskazuje współdzielony obiekt 11
Serializacja i ponowne sparsowanie daje semantykę obiektów PDF gratis: wartości bezpośrednie się kopiują, referencje zostają referencjami, dokładnie tak, jak zamierza ISO 32000-1

Samo kopiowanie nie wystarcza, bo przypadek referencyjny nadal celuje we współdzielony obiekt. Gdyby SetPageBox podążał za tą referencją i edytował obiekt 11, przeniesiona strona znów przeskalowałaby starego rodzica i jego pozostałe dzieci. Pisarz boxów stosuje więc copy-on-write: edytuje na miejscu tylko wtedy, gdy własny wpis strony jest bezpośrednią tablicą, a pośredni albo brakujący box zastępuje nową bezpośrednią tablicą. Obiekt 11 zostaje nietknięty dla każdej innej strony, która go cytuje

Decyzja copy-on-write w SetPageBox w PDFlibPas: gdy własny wpis strony to tablica bezpośrednia, jest edytowany w miejscu, a gdy to referencja pośrednia albo wpis brakujący, pisarz zastępuje go nową tablicą bezpośrednią, więc współdzielony obiekt 11 zachowuje swoją wartość dla każdej innej cytującej go strony
Kopiowanie przy materializacji nie wystarczy, dopóki referencje wciąż wskazują na współdzielone obiekty, więc pisarz boxów edytuje tylko to, co jest własnością strony
Ścieżka koduWspółdzielenie instancji (pułapka)PDFlibPas
Materializacja w MovePageStrona trzyma bezpośrednie instancje przodka same w sobieStrona trzyma zdekodowane kopie; referencje zostają referencjami
SetPageBoxPodąża za referencją i edytuje współdzieloną tablicęEdytuje tylko tablicę bezpośrednią na stronie, w innym wypadku zapisuje nową
Strona źródłowa w CopyPageRangesDzieli boxy węzła Pages; CropBox to instancja MediaBoxaKażda zmaterializowana wartość na stronie źródłowej to kopia
Domyślne boxy przy klonowaniu zasobów stronyCropBox, BleedBox, TrimBox i ArtBox dzielą jedną tablicęKażdy domyślny box dostaje własną tablicę

Ostatni wiersz to ten subtelny. Gdy biblioteka klonuje zasoby strony dla przechwycenia strony albo scalania, uzupełnia brakujące wpisy CropBox, BleedBox, TrimBox i ArtBox, a wypełnienie wszystkich czterech z jednej instancji tablicy zostawiłoby alias czekający na pierwszego wywołującego, który edytuje którąkolwiek z nich. Jak wybierane są te domyślne wartości boxów, to osobny temat — omawia go artykuł przewodnik PDFlibPas po domyślnych TrimBox, BleedBox i CropBox

Odtwarzanie aliasingu z MovePage na ręcznie zbudowanym PDF

Najszybszym sposobem przetestowania kodu edycji drzewa stron na aliasing jest mały ręcznie pisany PDF wczytany przez LoadFromString, w którym każdy numer obiektu zna się z góry. Pomocnik poniżej zapisuje klasyczną tabelę odniesień krzyżowych z poprawnie policzonymi offsetami bajtowymi, więc test nie polega na zachowaniu naprawczym parsera dla uszkodzonych plików

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);   // offset bajtowy liczony od zera napisu "N 0 obj"
    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      // każdy wpis ma dokładnie 20 bajtów
    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;

Dokument testowy ma dwa pośrednie węzły Pages. Węzeł 3 niesie pośredni MediaBox (obiekt 11, 400 na 300 punktów), bezpośredni CropBox i bezpośredni słownik Resources oraz posiada dwie strony. Węzeł 4 ma MediaBox w rozmiarze Letter i posiada trzecią stronę. Przeniesienie strony 1 na pozycję 3 przepina ją pod węzeł 4, czyli dokładnie ten ruch, który wymaga materializacji: bez niej strona zamieniłaby się w stronę Letter

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);                       // strona, którą przed chwilą przeniesliśmy
    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');

    // Obejrzyj starego rodzica PRZED wybraniem innej strony (patrz niżej)
    Check(Pos(AnsiString('/Font'), Lib.GetObjectToString(3)) = 0,
      'font registered in the old Pages node');

    Lib.SelectPage(1);                       // dawna strona 2, wciąż pod węzłem 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) bierze typ boxa 1 dla MediaBox i 2 dla CropBox, a wymiar 2 dla szerokości. Przy domyślnym początku w lewym dolnym rogu SetPageBox(1, 0, 200, 200, 200) znaczy lewo 0, góra 200, 200 szerokości i 200 wysokości. Przy materializatorze dzielącym instancje kontrole sióstr zawodzą: edycja CropBoxa ląduje w bezpośredniej tablicy węzła 3, a pisarz boxów podążający za referencjami przepisuje obiekt 11

Czy CopyPageRanges zmienia dokument źródłowy?

CopyPageRanges faktycznie zapisuje na stronach źródłowych, ale każda zapisywana wartość to osobna kopia, więc późniejsze edycje źródła zostają lokalne w stronie, którą edytujesz. Samo zapisywanie jest zamierzone: strona źródłowa potrzebuje jawnych MediaBox, CropBox, Rotate i Resources, zanim jej słownik zostanie sklonowany do celu, inaczej kopia straciłaby wszystko, co dziedziczyła. Przenumerowanie i kopiowanie strony do celu pokrywa artykuł głęboka kopia obiektów między dokumentami w PDFlibPas; pułapka siedzi tu po stronie źródłowej, którą większość ludzi zakłada tylko czytaną

Zapisane wyjście nigdy tego nie pokaże. Współdzielone albo skopiowane, zmaterializowane wartości serializują się identycznie, więc oba dokumenty zapisują się bajt w bajt tak samo w obu przypadkach. Dopiero edycja dokumentu źródłowego po kopii ujawnia alias:

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;             // staje się wybranym dokumentem
    Check(Lib.CopyPageRanges(SourceID, '1') = 1, 'copy failed');

    Lib.SelectDocument(SourceID);
    Lib.SelectPage(1);
    Lib.SetPageBox(2, 50, 250, 100, 100);    // zwęź tylko 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);            // kopia zachowuje swój pierwotny rozmiar
    Lib.SelectPage(Lib.PageCount);
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'copied page resized');
  finally
    Lib.Free;
  end;
end;

Obie strony tutaj dziedziczą bezpośredni MediaBox węzła głównego. Krok kopiujący, który przypiąłby tę instancję do strony źródłowej 1 i przypiął ją ponownie jako CropBox strony 1, sprawiłby, że zawężenie CropBoxa zawęzi MediaBox, a zmiana rozmiaru MediaBoxa przeskaluje stronę 2 przez węzeł główny. Obiegi pracy, które kopiują strony, a potem kontynuują edycję źródła — jak składanie skanów dupleksowych w jeden PDF przed przycięciem oryginałów — to miejsca, gdzie taki alias wychodzi na jaw

Dlaczego aliasing instancji jest tak trudny do przetestowania?

Aliasing instancji jest trudny do przetestowania, bo obserwowalny efekt wymaga trzech kroków w konkretnej kolejności: utwórz alias, zmień jedną stronę, potem obejrzyj drugą, zanim cokolwiek innego ją dotknie. Większość testów robi tylko krok pierwszy i porównuje zapisane wyjście, które jest identyczne niezależnie od tego, czy alias istnieje

Pułapką kolejności w PDFlibPas jest SelectPage. Wybranie strony nakłada ponownie bieżący font przez SelectFont, co rejestruje ten font w zasobach strony. Strona bez własnego /Resources rozwiązuje się do słownika rodzica, więc samo wybranie takiej strony legalnie dokłada /Font do węzła Pages. W teście MovePage powyżej wybranie dawnej strony 2 dokłada wpis Helvetica do węzła 3 — to poprawne zachowanie, a nie wyciek. Dlatego kontrola GetObjectToString(3) biegnie przed SelectPage(1); zamień je miejscami, a test zawodzi nawet bez żadnego aliasu

Ta reguła oznacza też, czego PDFlibPas celowo nie rusza. Zapis zasobu do strony dziedziczącej swój słownik Resources pisze do słownika przodka i każda siostra widzi nowy wpis. To dziedziczenie działające według specyfikacji, nie współdzielenie instancji, i jest nieszkodliwe, bo dodanie nazwy fontu albo obrazu do współdzielonego słownika nie zmienia renderowania innych stron. Jeśli potrzebujesz, by strona przestała dziedziczyć, najpierw daj jej własny słownik Resources

Lista kontrolna dla kodu modelu obiektów PDF

Wnioski uogólniają się na każdy model obiektów PDF zbudowany na puli i kontenerach wskaźnikowych, w Delphi i gdziekolwiek indziej:

  • Materializując dziedziczone atrybuty według ISO 32000-1 §7.7.3.4, kopiuj głęboko wartości bezpośrednie i zostawiaj referencje pośrednie jako nowe referencje na ten sam obiekt
  • Nigdy nie dodawaj istniejącej instancji przez Add do drugiego kontenera, chyba że współdzielenie jest zamierzone i udokumentowane; własność puli znaczy, że runtime nigdy nie zaprotestuje
  • Edytuj w miejscu tylko to, co bieżący węzeł posiada jako obiekt bezpośredni; wartości pośrednie albo odziedziczone zastępuj świeżym obiektem bezpośrednim (copy-on-write)
  • Wartości domyślne wyprowadzone z innego wpisu, jak CropBox z MediaBoxa, potrzebują własnej instancji
  • Testuj aliasing sekwencjami zmień-potem-obejrzyj na drugim posiadaczu i sprawdzaj kolejność wywołań, które mogłyby legalnie zapisać po drodze
  • Porównywanie zapisanego wyjścia niczego tu nie dowodzi: współdzielone i skopiowane wartości serializują się identycznie do pierwszej edycji

PDFlibPas wystawia edycję drzewa stron, kopiowanie między dokumentami i kontrolę boxów stron przez jedną klasę TPDFlib dla Delphi, C++Builder i Free Pascal. Wydania, platformy i pełną referencję API znajdziesz na stronie produktu PDFlibPas Delphi PDF library