Transações de grafo de objetos com cópia na escrita

THotPDF fornece pontos de salvamento aninhados para grafos de objetos indiretos carregados ou montados sem clonar o documento no início da transação

Ciclo de vida da transação

PDF.BeginGraphTransaction('metadata edit');
try
  Info.AddStringValue('Producer', 'HotPDF');
  PDF.CommitGraphTransaction;
except
  PDF.RollbackGraphTransaction;
  raise;
end;

BeginGraphTransaction indexa as raízes indiretas atuais e instala observadores de mutação, mas não cria instantâneos; a primeira gravação em uma raiz indireta existente nesse quadro cria um instantâneo, e gravações posteriores na mesma raiz o reutilizam

CommitGraphTransaction mantém o grafo atual e descarta ou transfere instantâneos sem cloná-lo; RollbackGraphTransaction restaura objetos raiz no lugar, remove objetos anexados após o ponto de salvamento e restaura a alocação de números de objeto

O rollback invalida o cache de relacionamentos de formulários carregados antes de restaurar objetos, então consultas de campos posteriores são reconstruídas a partir do grafo restaurado, em vez de reter referências a campos ou widgets removidos

Transações aninhadas são pontos de salvamento independentes; um rollback interno retorna ao estado de entrada interno, enquanto um commit interno retém histórico suficiente para um rollback externo posterior

Preparação de gravação automática e explícita

THPDFDictionaryObject.AddValue, ReplaceValue e DeleteValue, THPDFArrayObject.AddObject e SetIndexedItem, e mudanças em THPDFStreamObject.Length notificam a raiz indireta que os contém automaticamente

Campos escalares públicos e bytes brutos de stream não podem interceptar atribuição; chame PrepareLoadedObjectForWrite antes de atribuir Value, alterar flags públicos de objeto, substituir ponteiros de grafo ou gravar por meio de THPDFStreamObject.Stream

PDF.BeginGraphTransaction('raw stream edit');
try
  PDF.PrepareLoadedObjectForWrite(StreamObject);
  StreamObject.Stream.Size:= 0;
  StreamObject.Stream.WriteBuffer(Bytes[0], Length(Bytes));
  StreamObject.Length:= Length(Bytes);
  PDF.CommitGraphTransaction;
except
  PDF.RollbackGraphTransaction;
  raise;
end;

Memória e desempenho

A memória de instantâneo cresce com raízes indiretas tocadas em vez do tamanho total do documento; cargas grandes de stream são despejadas em arquivos temporários de propriedade após GraphTransactionMemoryThreshold, cujo padrão é 16 MiB

O rollback troca entradas de dicionário salvas, itens de array e armazenamento de stream de volta para a raiz existente, evitando uma segunda cópia profunda; o ponteiro raiz permanece estável, mas ponteiros para descendentes diretos devem ser readquiridos após o rollback

GetGraphTransactionStatistics retorna Active, Depth de aninhamento, SnapshotCount, AddedObjectCount, bytes de instantâneo residentes e despejados e bytes de instantâneo residentes de pico

THPDFBeforeMutationEvent é a assinatura de observador de baixo nível usada para rotear mutações de contêiner e ciclo de vida para o instantâneo da raiz indireta que os contém

Escopo

Transações cobrem o grafo de objetos indiretos, o estado de ciclo de vida, raízes anexadas e a alocação de números de objeto; ponteiros de propriedade do chamador, arrays de ordenação de páginas carregadas, caches renderizados e outro estado lateral de fachada não são registrados em diário

Não remova, reordene ou substitua entradas existentes em GetLoadedIndirectObjects enquanto uma transação está ativa; use métodos de contêiner de grafo e readquira descendentes diretos após o rollback