PDFium ist auf Modulebene nicht threadsicher, sodass zwei TPdf-Instanzen, die in zwei Threads an zwei verschiedenen Dateien arbeiten, sich gegenseitig beschädigen können. PDFium Component for Delphi geht das auf zwei Arten an: ValidatePdfFilesParallel serialisiert jeden nativen PDFium-Aufruf hinter einer prozessweiten Sperre, während TPdf.RenderPagesParallel jedem Worker seine eigene isolierte Kopie des PDFium-Moduls gibt. Wer das vermasselt, erzeugt die schlimmste Art von intermittierendem Versagen. Ein Batch läuft meistens durch, meldet dann eine von zwei guten Dateien als gescheitert, crasht danach den nächsten Aufruf im selben Prozess mit einer Access Violation und reißt manchmal den ganzen Prozess mit einem Exit Code mit, statt einem Stack Trace. Mit keinem einzelnen Dokument ist etwas falsch. Die Annahme ist falsch: ein TPdf pro Thread ist keine Isolation
Warum reicht ein TPdf pro Thread nicht?
Ein TPdf pro Thread reicht nicht, weil PDFium seinen unsicheren Zustand im Modul hält, nicht im Dokument. Jedes TPdf besitzt sein eigenes FPDF_DOCUMENT-Handle, aber jedes Handle im Prozess wird von derselben geladenen DLL bedient, und diese DLL hält prozessweite Singletons: den Font-Cache, das Seitenmodul und weitere globale Strukturen, die Laden, Parsen und Rendern von Dokumenten alle anfassen. Zwei Threads, die zwei nicht verwandte Dateien laden, sind zwei Threads, die zur selben Zeit in denselben Font-Cache schreiben. Auf Delphi-Seite besitzt niemand diese Daten, also kann auf Delphi-Seite auch nichts sie pro Dokument sperren
Die Komponente hat eine Sperre, und aus ihr lässt sich leicht die falsche Schlussfolgerung ziehen. TPdf wickelt seine eigenen Render-Pfade in eine interne Critical Section (EnterRenderLock / LeaveRenderLock, private Methoden von TPdf). Diese Sperre gilt pro Instanz. Sie verhindert, dass zwei Threads gleichzeitig dasselbe TPdf treiben, ein echtes Risiko, aber sie kann keine zweite Instanz auf einem anderen Thread sehen, also läuft instancesübergreifende Nebenläufigkeit geradewegs an ihr vorbei. Die allgemeine Regel lässt sich in einer Zeile nennen: In einem einzelnen geladenen PDFium-Modul darf zu jedem Zeitpunkt höchstens ein Thread innerhalb von PDFium sein, egal wie viele Dokumente offen sind
Wie sieht instancesübergreifende Korruption in einem Delphi-Prozess aus?
Dokumentübergreifende Korruption sieht aus wie ein zufälliger Mix unabhängiger Fehler, und der Schaden überlebt den Code, der ihn verursacht hat. Das naive Batch-Design erzeugt ein TPdf pro Worker-Thread und fährt Active := True plus den Preflight-Report-Build gleichzeitig auf dem geteilten Modul. Die Symptome zeigen sich auf Delphi- und Free-Pascal-Builds gleichermaßen und spannen die ganze Bandbreite auf:
- Eine valide Datei lädt nicht, oder sie kommt aus dem Batch als gescheitert zurück, obwohl sie durchgegangen wäre
- Eine Access Violation taucht in einem späteren, unverwandten Aufruf auf, oft in einem anderen Test oder einem anderen Dokument
External exception C000001Derscheint in Delphi. Dieser Code istSTATUS_ILLEGAL_INSTRUCTION, geworfen von derud2-Instruktion, die PDFiums interneCHECK- undIMMEDIATE_CRASH-Makros ausführen, wenn eine Invariante bricht- Der Prozess endet mit
0xC0000409(fail-fast, als Stack Buffer Overrun gemeldet) oder0xC0000374(Heap Corruption), ganz ohne Delphi-Exception
Die letzten beiden Punkte sind der Grund, warum sich dieses Versagen so schwer eingrenzen lässt. Die parallele Arbeit endet, der beschädigte globale Zustand bleibt zurück, und der nächste Aufrufer im selben Prozess stolpert darüber: Eine Welle von C000001D-Fehlern kann Code treffen, der den Batch nie angefasst hat, schlicht weil er der erste war, der nach dem Schaden PDFium benutzte. Die Größenordnung ist alles andere als subtil. Dieselbe Stichprobe durch zwei unsynchronisierte Worker auf einem Modul geschickt scheiterte in einem Lauf an 122 von 160 Dokumenten, in einem anderen an 138 von 160, und einer dieser Läufe warf direkt eine External exception C000001D
Wie ValidatePdfFilesParallel sicher bleibt
ValidatePdfFilesParallel serialisiert den nativen Teil jedes Auftrags und lässt den verwalteten Teil parallel laufen. Jeder Worker nimmt eine unit-weite Critical Section, bevor er sein TPdf erstellt, und hält sie über FileName, Active := True, den Preflight-Report-Build und Free. Erzeugung und Zerstörung stehen bewusst innerhalb der Sperre: Das Schließen eines Dokuments ruft ebenso ins Modul zurück wie das Laden. Hat der Worker einmal einen erfassten TPdfPreflightReport-Record in der Hand, gibt er die Sperre frei und wertet die Validierungsregeln gegen diesen Record aus, was keinen PDFium-Zustand anfasst, sodass die Regelauswertung einer Datei sich mit der PDFium-Arbeit der nächsten überlappt
Zwei Details ergeben sich aus diesem Design. Ein Ladefehler löst EPdfError mit LastLoadReport.ErrorMessage aus, sodass der ErrorMessage-Eintrag des Elements das tatsächliche Parse-Problem nennt statt eines sekundären „no active document"-Fehlers. Und der Preis ist real: Der PDFium-Teil des Batches ist serial, bei einem Batch, der von Parsing und Preflight dominiert wird, kaufen zusätzliche Worker also wenig
uses
System.SysUtils, PDFium, FPdfPreflightReport;
procedure ValidateBatch(const Files: array of string);
var
Registry: TPdfValidationRuleRegistry;
Options: TPdfBatchValidationOptions;
Report: TPdfBatchValidationReport;
I: Integer;
begin
Registry := CreateDefaultPdfValidationRuleRegistry;
try
Options := TPdfBatchValidationOptions.Default;
Options.WorkerCount := 4; // 0 = Prozessorenzahl, gedeckelt bei 8
Options.Standards := [ppsPdfA];
// Mit explizitem Registry das passende Profil selbst wählen.
// Eine leere Profiles-Liste fährt jede registrierte Regel, und Regeln für
// Standards, die Sie nicht gepreflighted haben, melden „did not pass“
SetLength(Options.ValidationOptions.Profiles, 1);
Options.ValidationOptions.Profiles[0] := 'PDF/A';
Report := ValidatePdfFilesParallel(Files, Registry, Options);
finally
Registry.Free;
end;
for I := 0 to High(Report.Results) do
case Report.Results[I].Status of
pbvisPass: Writeln('PASS ', Report.Results[I].FileName);
pbvisFail: Writeln('FAIL ', Report.Results[I].FileName);
pbvisError: Writeln('ERROR ', Report.Results[I].FileName, ': ',
Report.Results[I].ErrorMessage);
else
Writeln('SKIP ', Report.Results[I].FileName); // pbvisCancelled
end;
Writeln(Report.PassedDocumentCount, ' passed, ',
Report.FailedDocumentCount, ' failed, ',
Report.ErrorDocumentCount, ' errors');
end;
nil als Registry zu übergeben ist der kürzere Weg: ValidatePdfFilesParallel erzeugt dann selbst das Default-Registry, leitet die Profil-Liste aus Options.Standards ab und gibt das Registry bei der Rückkehr frei. Ergebnisse kommen stets in Eingabereihenfolge zurück, in welcher Reihenfolge die Worker auch fertig wurden. Für die Report-Formate und den Kommandozeilen-Wrapper um dieselbe Engine siehe Batch-PDF-Preflight-Reports mit der PDFium Component CLI, und was die PDF/A-Prüfungen selbst abdecken, siehe PDF/A-Preflight-Validierung in Delphi
Wie läuft RenderPagesParallel die Seiten wirklich parallel?
TPdf.RenderPagesParallel läuft parallel, weil seine Worker nie ein PDFium-Modul teilen. Die Methode sichert zuerst das aktive Dokument in einen Quell-Speicher auf dem aufrufenden Thread. Dann kopiert jeder Worker die geladene PDFium-DLL in eine eindeutig benannte Datei im Temp-Verzeichnis, lädt diese Kopie mit LoadLibrary und initialisiert sie. Windows behandelt eine DLL aus einem anderen Pfad als ein anderes Modul, jede Kopie bekommt also eigene Globals: eigenen Font-Cache, eigenes Seitenmodul, alles Eigene. Der Worker öffnet das gesicherte Dokument in seinem privaten Modul, rendert seine Seiten progressiv mit Abbruch-Prüfungen zwischen den Schritten, zerstört dann die Bibliothek, entlädt die Kopie und löscht die Datei
Die Isolation ist nicht gratis, und die Defaults spiegeln das. Jeder Worker zahlt für eine DLL-Kopie auf der Disk, einen zweiten Satz PDFium-Globals im Speicher und ein frisches Parsing des Dokuments. MaxWorkers = 0 heißt höchstens 4 Worker, MaxPixelsPerPage und MaxTotalOutputBytes deckeln die Rohausgabe, und die Invert- und Night-Duotone-Render-Optionen werden abgewiesen, weil die Buffer roh zurückkommen. Das Ergebnis ist ein TPdfParallelRenderReport, dessen Results-Array je angefragter Seite einen Top-down-32-Bit-Buffer hält, in Anfragereihenfolge
procedure RenderAllPages(Pdf: TPdf);
var
Options: TPdfParallelRenderOptions;
Report: TPdfParallelRenderReport;
Pages: array of Integer;
I: Integer;
begin
SetLength(Pages, Pdf.PageCount);
for I := 0 to High(Pages) do
Pages[I] := I + 1; // Seitenzahlen sind 1-basiert
Options := TPdfParallelRenderOptions.Default;
Options.Dpi := 150;
Options.MaxWorkers := 4;
// Der Quell-Snapshot läuft auf dem geteilten Modul, also die
// prozessweite PDFium-Sperre halten, wenn andere Threads auch TPdf nutzen
PdfiumLock.Acquire;
try
Report := Pdf.RenderPagesParallel(Pages, Options);
finally
PdfiumLock.Release;
end;
for I := 0 to High(Report.Results) do
if Report.Results[I].Status = pprsSucceeded then
SavePageBuffer(Report.Results[I]) // Width, Height, Stride, PixelFormat, Pixels
else
Writeln('Page ', Report.Results[I].PageNumber, ': ',
Report.Results[I].ErrorMessage);
end;
Beachten Sie die Sperre um den Aufruf. Die Worker-Module sind privat, aber der Snapshot-Schritt am Anfang läuft mit SaveAs auf dem geteilten Modul vom aufrufenden Thread aus. Fassen Sie im Prozess sonst nichts TPdf gleichzeitig an, können Sie die Sperre weglassen; tut es irgendetwas, braucht der Snapshot denselben Schutz wie jeder andere Aufruf auf dem geteilten Modul
| Muster | Sicher dokumentübergreifend | PDFium-Arbeit läuft parallel | Kosten |
|---|---|---|---|
Ein TPdf pro Thread, keine gemeinsame Sperre | Nein | Ja, bis etwas korrumpiert | Intermittierende Abstürze, beschädigter Prozesszustand |
| Eine prozessweite Sperre um alle PDFium-Aufrufe | Ja | Nein | Der PDFium-Teil ist serial |
ValidatePdfFilesParallel | Ja | Nein; die Regelauswertung ist parallel | Parsing und Preflight sind serial |
TPdf.RenderPagesParallel | Ja | Ja | DLL-Kopie, Speicher und ein frisches Parsen pro Worker |
Wie sollten Sie Ihren eigenen multithreaded PDFium-Code strukturieren?
Eigene Threads sollten sich eine einzige prozessweite Sperre teilen und sie über die gesamte Lebenszeit jedes TPdf halten, das sie benutzen, oder alternativ eine Komponenten-API verwenden, die das Modul für einen isoliert. Die Sperre muss ein einzelnes Objekt für den ganzen Prozess sein, nicht eines pro Thread, pro Formular oder pro Dokument; eine Sperre, die zwei Threads nicht teilen, schützt nichts. Das Muster unten spiegelt, was die Komponente intern tut: Erzeugen, Laden, Lesen und Freigeben innerhalb der Sperre, alles andere, das PDFium nicht anfasst, außerhalb
uses
System.Classes, System.SysUtils, System.SyncObjs, PDFium;
var
PdfiumLock: TCriticalSection; // eine Sperre für den ganzen Prozess
type
TTextExtractThread = class(TThread)
private
FFileName: string;
FText: string;
protected
procedure Execute; override;
public
constructor Create(const AFileName: string);
property ExtractedText: string read FText;
end;
constructor TTextExtractThread.Create(const AFileName: string);
begin
inherited Create(True);
FFileName := AFileName;
end;
procedure TTextExtractThread.Execute;
var
Pdf: TPdf;
Page: Integer;
Raw: TStringBuilder;
begin
Raw := TStringBuilder.Create;
try
PdfiumLock.Acquire;
try
Pdf := TPdf.Create(nil);
try
Pdf.FileName := FFileName;
Pdf.Active := True;
if not Pdf.Active then
raise EPdfError.Create(Pdf.LastLoadReport.ErrorMessage);
for Page := 1 to Pdf.PageCount do
begin
Pdf.PageNumber := Page;
Raw.AppendLine(Pdf.Text);
end;
finally
Pdf.Free; // Das Schließen des Dokuments ist auch PDFium-Arbeit
end;
finally
PdfiumLock.Release;
end;
// Unterhalb dieser Zeile kein PDFium, dieser Teil läuft also parallel
FText := Raw.ToString.Trim;
finally
Raw.Free;
end;
end;
initialization
PdfiumLock := TCriticalSection.Create;
finalization
PdfiumLock.Free;
Ein paar Regeln halten das Muster in einer echten Anwendung ehrlich:
TPdf.CreateundFreein die Sperre legen, nicht nur die offensichtlichen Aufrufe. Laden, Schließen, Property-Lesezugriffe wiePageCount, Seitenwechsel, Textextraktion, Rendern und Sichern reichen alle ins ModulActivenach der Zuweisung prüfen. Ein gescheitertes Laden lässtActiveaufFalse, undLastLoadReport.ErrorMessagesagt warum- Die Sperre pro Dokument halten statt pro Aufruf. Feineres Locking ist im Prinzip möglich, aber nur, wenn kein
TPdf-Member jemals außerhalb läuft, und die grobe Variante ist die, auf die sich die Komponente selbst verlässt - Langsame Nicht-PDFium-Arbeit, etwa Datenbank-Schreibvorgänge, Indexierung und Netzwerk-Aufrufe, außerhalb der Sperre halten, sonst serialisiert ein langsamer Consumer alles
- Die private Instanz-Rendersperre nicht als Ersatz behandeln. Sie bewacht ein
TPdfvor sich selbst und nichts weiter
Dieselbe Vorsicht gilt für Code, den Sie nicht als rohe Threads geschrieben haben. Background-Futures sind ein guter Weg, lange Renders vom UI-Thread fernzuhalten, wie in Background-PDF-Rendering mit abbrechbaren Futures beschrieben, aber der Future-Executor fügt keine eigene globale PDFium-Sperre hinzu. Wenn mehrere Futures gleichzeitig unterschiedliche TPdf-Instanzen treiben können, nehmen Sie dieselbe prozessweite Sperre in jedem Worker, und behandeln Sie einen Viewer auf dem Hauptthread als einen weiteren Kunden des geteilten Moduls. Die konservative Annahme lautet, dass die Nutzung mehrerer Instanzen über die asynchronen APIs dieselbe Serialisierung braucht wie handgeschriebene Threads. Wenn Sie echte PDFium-Parallelität für etwas anderes als Seiten-Rendering brauchen, geben separate Worker-Prozesse jedem Job konstruktionsbedingt sein eigenes Modul
Kurzreferenz: PDFium-Threading-Regeln für Delphi
- PDFiums unsicherer Zustand ist modulweit: Font-Cache, Seitenmodul und weitere Globals werden von jedem Dokument im Prozess geteilt
- Ein
TPdfpro Thread isoliert nichts; zwei Instanzen auf zwei Threads können sich trotzdem gegenseitig beschädigen - Typische Symptome sind Ladefehler, Access Violations in späterem Code,
External exception C000001Dund Prozesenden mit0xC0000409oder0xC0000374 - Die Korruption überlebt im Prozess, deshalb ist der scheiternde Aufruf oft nicht der, der sie verursacht hat
ValidatePdfFilesParallelserialisiert die PDFium-Hälfte jedes Auftrags hinter einer prozessweiten Sperre und wertet die Regeln parallel ausTPdf.RenderPagesParallelist wirklich parallel, weil jeder Worker eine isolierte Kopie des PDFium-Moduls lädt- Eigene Threads, Tasks und Futures brauchen eine prozessweite Sperre, die jedes
TPdfvonCreatebisFreeabdeckt
PDFium Component umhüllt die PDFium-Engine für Delphi mit Batch-Preflight und -Validierung, isoliertem parallelem Rendering, abbrechbarer Background-Arbeit und detaillierter Ladediagnostik. Details und Editionen finden Sie auf der PDFium Component product page