Articolo tecnico

PDFlibPas MovePage: quando le box condividono istanze

In PDFlibPas, la libreria PDF Delphi, una pagina spostata con MovePage riceve le sue copie dei valori MediaBox, CropBox e Resources che ereditava dal suo vecchio nodo Pages, e un riferimento indiretto resta un riferimento. Consegnare alla pagina spostata gli identici oggetti che il vecchio nodo Pages tiene è l'implementazione ovvia, e significa che un successivo SetPageBox o DrawText sulla pagina spostata riscrive in silenzio quel nodo e ogni sorella che eredita ancora da esso. La stessa regola copia-non-condividere copre due percorsi correlati: SetPageBox su una box indiretta che più pagine condividono, e CopyPageRanges, che materializza i valori ereditati sulle pagine del documento sorgente

I sintomi di questo tipo di aliasing non menzionano mai l'identità degli oggetti. Suonano come "ho ritagliato la pagina 7 e le pagine da 8 a 12 si sono ritagliate anche loro", o "ho ristretto il CropBox e il MediaBox si è spostato con esso", o, il più confondente, "ho copiato una pagina in un nuovo documento e il file originale è cambiato". Niente crash, niente leak, e il file salvato è PDF perfettamente valido. Contiene solo geometria che nessuno ha chiesto

Come può SetPageBox su una pagina ridimensionare le sorelle?

Succede quando due voci dell'albero pagine puntano a un array in memoria e SetPageBox modifica il suo array di destinazione sul posto: qualsiasi pagina o nodo Pages che tiene la stessa istanza vede la modifica. Tre percorsi di codice in un editor dell'albero pagine possono produrre quella condivisione:

  • MovePage materializza gli attributi ereditabili sulla pagina prima di staccarla dal suo genitore; attaccare gli oggetti propri dell'antenato invece che copie lascia la pagina spostata e le sue ex sorelle che condividono un array di box e un dizionario Resources
  • Uno scrittore di box che segue i riferimenti indiretti e modifica l'array referenziato ridimensiona ogni pagina che punta a un oggetto /MediaBox 11 0 R con una singola chiamata, che MovePage sia mai coinvolto o no
  • CopyPageRanges materializza i valori ereditati sulla pagina sorgente prima di clonarla nel documento di destinazione; attaccare le istanze dei nodi Pages alla pagina sorgente, più l'istanza MediaBox stessa come CropBox predefinito, lega tutto insieme
Trappola di aliasing di MovePage in cui una pagina spostata e la sua ex sorella tengono entrambe l'istanza dell'array MediaBox proprio dell'antenato, così SetPageBox modifica una pagina e ridimensiona l'altra; la materializzazione PDFlibPas attacca copie decodificate così le modifiche restano locali alla pagina che toccate
Due voci dell'albero pagine che puntano a un array in memoria fanno atterrare ogni modifica in ogni detentore, e il PDF salvato resta valido tutto il tempo

La materializzazione in sé non è opzionale. Portare attraverso solo /Resources e una pagina spostata sotto un genitore diverso prende in silenzio dimensione e rotazione di quel genitore, quindi MovePage porta anche MediaBox, CropBox e Rotate, cosa di cui conta anche CollateDocumentsEx quando riordina le pagine. L'unica domanda è se quei valori arrivano come copie o come istanze condivise

Valori diretti, riferimenti indiretti ed ereditarietà degli attributi di pagina

Una copia corretta di un attributo di pagina ereditato duplica i valori diretti e conserva i riferimenti indiretti come riferimenti, perché è questa la distinzione che traccia lo stesso ISO 32000-1. Un oggetto diretto come [0 0 400 300] scritto dentro un dizionario appartiene a quel dizionario da solo. Un oggetto indiretto, definito una volta come 11 0 obj e citato come 11 0 R, è condiviso per progetto: ISO 32000-1 §7.3.10 lo rende indirizzabile da qualsiasi punto del file, e ogni 11 0 R significa lo stesso oggetto

L'ereditarietà degli attributi di pagina, ISO 32000-1 §7.7.3.4, aggiunge un terzo caso. Resources, MediaBox, CropBox e Rotate possono stare su un nodo Pages e valere per ogni pagina discendente che non definisce i propri. La pagina non tiene il valore; lo risale attraverso /Parent. Quella catena di ricerca si spezza nel momento in cui una pagina cambia genitore, ed è per questo che MovePage e BalancePageTree devono prima scrivere i valori effettivi sulla pagina stessa. La domanda è solo come scriverli

Perché un object pool nasconde l'errore

In PDFlibPas ogni oggetto PDF analizzato o creato appartiene al pool TPDFStructure del documento, e i dizionari e gli array memorizzano semplici puntatori alle proprie voci. TPDFDictionary.Add registra il puntatore e nient'altro. Aggiungere una istanza a due contenitori padre è quindi legale a ogni livello che il runtime può controllare: niente doppia liberazione allo smontaggio, niente reference count che sbaglia, niente eccezioni. La serializzazione è altrettanto permissiva, dato che ogni contenitore scrive inline il valore corrente dell'istanza condivisa, e prima di qualsiasi modifica l'output è byte per byte ciò che una copia corretta produrrebbe

L'aliasing emerge solo quando qualcuno modifica sul posto l'istanza condivisa. SetPageBox fa esattamente questo attraverso un wrapper rettangolo sull'array esistente, e disegnare su una pagina lo fa al dizionario Resources quando si registra un font o un'immagine. La modifica atterra, in silenzio, in ogni altro contenitore che tiene il puntatore

Come PDFlibPas copia invece di condividere

PDFlibPas gestisce il problema da entrambe le estremità: la materializzazione attacca copie, e le scritture di box modificano solo un array che la pagina possiede. Ogni regola copre un caso che l'altra non può

La helper di materializzazione, PLInheritPageAttributes, attacca Page.Owner.Decode(Value.Output) piuttosto che Value stessa. Il round-trip attraverso il serializzatore è un modo brutale ma esatto di avere gratis la semantica PDF. Un array o dizionario diretto si serializza nel suo testo letterale e si decodifica in una istanza fresca e indipendente. Un riferimento indiretto si serializza in 11 0 R e si decodifica in un nuovo oggetto riferimento che punta allo stesso oggetto 11, quindi la pagina continua a riferirsi all'oggetto condiviso invece di ricevere una copia inline. La copia è profonda esattamente quanto la struttura diretta: qualsiasi cosa raggiunta attraverso un riferimento dentro un dizionario copiato resta condivisa, come il formato file intende. BalancePageTree chiama la stessa helper per ogni pagina di cui cambia genitore, quindi le pagine materializzate lì prendono anch'esse istanze separate

Round-trip di materializzazione PDFlibPas in cui PLInheritPageAttributes attacca Page.Owner.Decode(Value.Output): un array diretto si serializza in testo letterale e si decodifica in una istanza fresca, mentre un 11 0 R indiretto si serializza e si decodifica in un nuovo riferimento che punta ancora all'oggetto condiviso 11
Serializzare e ri-analizzare dà gratis la semantica degli oggetti PDF: i valori diretti si copiano, i riferimenti restano riferimenti, esattamente come intende ISO 32000-1

Copiare da solo non basta, perché il caso riferimento punta ancora a un oggetto condiviso. Se SetPageBox seguisse quel riferimento e modificasse l'oggetto 11, la pagina spostata ridimensionerebbe di nuovo il vecchio genitore e i suoi altri figli. Così lo scrittore di box applica copy-on-write: modifica sul posto solo quando la voce della pagina è un array diretto, e sostituisce una box indiretta o mancante con un nuovo array diretto. L'oggetto 11 resta intatto per ogni altra pagina che lo cita

Decisione copy-on-write di SetPageBox in PDFlibPas: quando la voce della pagina è un array diretto viene modificato sul posto, e quando è un riferimento indiretto o manca lo scrittore lo sostituisce con un nuovo array diretto così l'oggetto condiviso 11 conserva il proprio valore per ogni altra pagina che lo cita
Copiare alla materializzazione non basta finché i riferimenti puntano ancora a oggetti condivisi, quindi lo scrittore di box modifica solo ciò che la pagina possiede
Percorso di codiceCondivisione di istanze (la trappola)PDFlibPas
Materializzazione di MovePageLa pagina tiene le istanze dirette proprie dell'antenatoLa pagina tiene copie decodificate; i riferimenti restano riferimenti
SetPageBoxSegue un riferimento e modifica l'array condivisoModifica solo un array diretto sulla pagina, altrimenti ne scrive uno nuovo
Pagina sorgente di CopyPageRangesCondivide le box dei nodi Pages; il CropBox è l'istanza MediaBoxOgni valore materializzato sulla pagina sorgente è una copia
Box predefinite alla clonazione delle risorse di paginaCropBox, BleedBox, TrimBox e ArtBox condividono un arrayOgni box predefinita prende il suo array

L'ultima riga è quella sottile. Quando la libreria clona le risorse di una pagina per cattura o merge di pagine, riempie le voci mancanti di CropBox, BleedBox, TrimBox e ArtBox, e riempire tutte e quattro da una istanza array lascerebbe un alias in attesa del primo chiamante che ne modifica una. Come vengono scelte quelle box predefinite è un tema a sé, trattato nella guida PDFlibPas ai predefiniti di TrimBox, BleedBox e CropBox

Riprodurre l'aliasing di MovePage con un PDF costruito a mano

Il modo più veloce di testare codice di editing dell'albero pagine per aliasing è un piccolo PDF scritto a mano caricato con LoadFromString, dove ogni numero di oggetto è noto in anticipo. La helper sotto scrive una classica tabella cross-reference con offset di byte calcolati correttamente, così il test non conta sul comportamento di recupero del parser per file danneggiati

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 di byte a base zero di "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      // ogni voce è esattamente 20 byte
    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;

Il documento di prova ha due nodi Pages intermedi. Il nodo 3 porta un MediaBox indiretto (oggetto 11, 400 per 300 punti), un CropBox diretto e un dizionario Resources diretto, e possiede due pagine. Il nodo 4 ha un MediaBox formato Letter e possiede la terza pagina. Spostare la pagina 1 alla posizione 3 le cambia genitore sotto il nodo 4, che è esattamente lo spostamento che richiede materializzazione: senza, la pagina diventerebbe una pagina 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);                       // la pagina appena spostata
    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');

    // Ispeziona il vecchio parent PRIMA di selezionare un'altra pagina (vedi sotto)
    Check(Pos(AnsiString('/Font'), Lib.GetObjectToString(3)) = 0,
      'font registered in the old Pages node');

    Lib.SelectPage(1);                       // ex pagina 2, ancora sotto il nodo 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) prende il tipo box 1 per MediaBox e 2 per CropBox, e la dimensione 2 per la larghezza. Con l'origine in basso a sinistra predefinita, SetPageBox(1, 0, 200, 200, 200) significa sinistra 0, cima 200, 200 largo e 200 alto. Con un materializzatore che condivide istanze, i controlli sulle sorelle falliscono: la modifica del CropBox atterra nell'array diretto del nodo 3, e uno scrittore di box che segue i riferimenti riscrive l'oggetto 11

CopyPageRanges cambia il documento sorgente?

CopyPageRanges scrive sì sulle pagine sorgenti, ma ogni valore che scrive è una copia separata, così le modifiche successive alla sorgente restano locali alla pagina che modificate. La scrittura in sé è intenzionale: la pagina sorgente vuole MediaBox, CropBox, Rotate e Resources espliciti prima che il suo dizionario venga clonato nella destinazione, altrimenti la copia perderebbe tutto ciò che ha ereditato. Rinumerazione e copia della pagina nella destinazione sono trattate in copia profonda di oggetti tra documenti in PDFlibPas; la trappola qui sta sul lato sorgente, che la maggior parte della gente assume che una copia solo legga

L'output salvato non lo mostra mai. Condivisi o copiati, i valori materializzati si serializzano identici, quindi entrambi i documenti si salvano byte per byte uguali in entrambi i casi. Solo una modifica al documento sorgente dopo la copia rivela un 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;             // diventa il documento selezionato
    Check(Lib.CopyPageRanges(SourceID, '1') = 1, 'copy failed');

    Lib.SelectDocument(SourceID);
    Lib.SelectPage(1);
    Lib.SetPageBox(2, 50, 250, 100, 100);    // restringe solo il 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);            // la copia conserva la dimensione originale
    Lib.SelectPage(Lib.PageCount);
    Check(Abs(Lib.GetPageBox(1, 2) - 400) < 0.001, 'copied page resized');
  finally
    Lib.Free;
  end;
end;

Entrambe le pagine qui ereditano il MediaBox diretto del nodo radice. Un passo di copia che avesse attaccato quell'istanza alla pagina sorgente 1, e l'avesse attaccata di nuovo come CropBox della pagina 1, farebbe sì che restringere il CropBox restringa il MediaBox, e che ridimensionare il MediaBox ridimensioni la pagina 2 attraverso il nodo radice. I flussi di lavoro che copiano pagine fuori e poi continuano a modificare la sorgente, come collazionare scansioni duplex in un PDF prima di ritagliare gli originali, sono dove questo tipo di alias compare

Perché l'aliasing di istanze è così difficile da testare?

L'aliasing di istanze è difficile da testare perché l'effetto osservabile richiede tre passi in un ordine preciso: creare l'alias, modificare un lato, poi ispezionare l'altro lato prima che qualsiasi altra cosa lo tocchi. La maggior parte dei test fa solo il primo passo e confronta l'output salvato, che è identico che l'alias esista o no

La trappola d'ordine in PDFlibPas è SelectPage. Selezionare una pagina riapplica il font corrente tramite SelectFont, che registra quel font nelle risorse della pagina. Una pagina senza /Resources proprie si risolve al dizionario del genitore, così il solo selezionare una simile pagina aggiunge legittimamente /Font al nodo Pages. Nel test MovePage sopra, selezionare l'ex pagina 2 aggiunge la voce Helvetica al nodo 3, che è comportamento corretto e non un leak. Ecco perché il controllo GetObjectToString(3) gira prima di SelectPage(1); scambiateli e il test fallisce anche quando nessun alias esiste

Quella regola segna anche ciò che PDFlibPas lascia deliberamente in pace. Scrivere una risorsa su una pagina che eredita il suo dizionario Resources scrive nel dizionario dell'antenato, e ogni sorella vede la nuova voce. È l'ereditarietà che lavora come specificato, non condivisione di istanze, ed è innocua perché aggiungere un nome di font o immagine a un dizionario condiviso non cambia come renderizzano le altre pagine. Se vi serve che una pagina smetta di ereditare, datele prima il suo dizionario Resources

Lista di controlli per il codice di object model PDF

Le lezioni si generalizzano a qualsiasi object model PDF costruito su un pool e contenitori a puntatori, in Delphi o altrove:

  • Quando materializzate attributi ereditati per ISO 32000-1 §7.7.3.4, copiate in profondità i valori diretti e conservate i riferimenti indiretti come nuovi riferimenti allo stesso oggetto
  • Mai Add di un'istanza esistente a un secondo contenitore a meno che la condivisione sia voluta e documentata; la ownership da parte di un pool significa che il runtime non si lamenterà mai
  • Modificate sul posto solo ciò che il nodo corrente possiede come oggetto diretto; sostituite valori indiretti o ereditati con un oggetto diretto fresco (copy-on-write)
  • I valori predefiniti derivati da un'altra voce, come un CropBox da un MediaBox, vogliono la propria istanza
  • Testate l'aliasing con sequenze modifica-poi-ispeziona sull'altro detentore, e controllate l'ordine delle chiamate che potrebbero scrivere legittimamente in mezzo
  • Confrontare l'output salvato non prova nulla qui: valori condivisi e copiati si serializzano identici fino alla prima modifica

PDFlibPas espone editing dell'albero pagine, copia tra documenti e controllo delle page box attraverso un'unica classe TPDFlib per Delphi, C++Builder e Free Pascal. Vedi la pagina prodotto della PDFlibPas Delphi PDF library per edizioni, piattaforme e il riferimento API completo