PDFium modül düzeyinde thread-safe değildir; dolayısıyla iki thread'de iki farklı dosya üzerinde çalışan iki TPdf instance'ı birbirini bozabilir. Delphi için PDFium Component bunu iki şekilde ele alır: ValidatePdfFilesParallel her native PDFium çağrısını tek bir süreç geneli kilidin arkasında serileştirir, TPdf.RenderPagesParallel ise her worker'a PDFium modülünün kendi yalıtılmış kopyasını verir. Bunu yanlış yapmak en kötü türde aralıklı başarısızlık üretir. Bir batch çoğunlukla geçer, sonra iki iyi dosyadan birini başarısız diye bildirir, sonra aynı süreçteki sonraki çağrıyı bir access violation ile çökertir ve bazen tüm süreci stack trace yerine bir çıkış koduyla indirir. Tek bir belgede hiçbir sorun yoktur. Yanlış olan varsayımdır: thread başına bir TPdf yalıtım değildir
Thread başına bir TPdf neden yetmez?
Thread başına bir TPdf yetmez, çünkü PDFium güvensiz durumunu belgede değil modülde tutar. Her TPdf kendi FPDF_DOCUMENT handle'ına sahiptir ama süreçteki her handle aynı yüklenmiş DLL tarafından servis edilir ve o DLL süreç geneli singleton'lar tutar: font cache, page module ve belge yükleme, ayrıştırma ve render'in hepsinin dokunduğu öteki global yapılar. İki ilişkisiz dosyayı yükleyen iki thread, aynı anda aynı font cache'e yazan iki thread'dir. O veriye Delphi tarafında sahip olan yoktur; dolayısıyla Delphi tarafında onu belge başına kilitleyen hiçbir şey olamaz
Bileşenin bir kilidi vardır ve ondan yanlış sonuç çıkarmak kolaydır. TPdf, kendi render yollarını dahili bir critical section içine sarar (EnterRenderLock / LeaveRenderLock, TPdf'in private metotları). O kilit instance başınadır. Aynı anda iki thread'in aynı TPdf'yi sürmesini engeller — gerçek bir tehlikedir bu — ama başka thread'deki ikinci bir instance'ı göremez; dolayısıyla çapraz-instance eşzamanlılık düz onun yanından geçer. Genel kural tek satırda özetlenecek kadar basittir: tek bir yüklenmiş PDFium modülünde herhangi bir anda PDFium içinde en fazla bir thread olabilir, kaç belge açık olduğuna bakılmaksızın
Çapraz-belge bozulması bir Delphi sürecinde nasıl görünür?
Çapraz-belge bozulması, ilişkisiz başarısızlıkların rastgele bir karışımı gibi görünür ve hasar, ona neden olan koddan daha uzun yaşar. Naif batch tasarımı, worker thread başına bir TPdf oluşturur ve Active := True atamasını preflight raporu oluşturmasıyla birlikte paylaşılan modül üzerinde eşzamanlı koşturur. Belirtiler hem Delphi hem Free Pascal derlemelerinde görülür ve tüm yelpazeyi kapsar:
- Geçerli bir dosya yüklenemiyor ya da geçmesi gerekirken batch'ten başarısız dönüyor
- Bir access violation, sonradan ilişkisiz bir çağrıda su yüzüne çıkıyor; çoğunlukla başka bir testte ya da başka bir belgede
- Delphi'de
External exception C000001Dgörünüyor. O kodSTATUS_ILLEGAL_INSTRUCTION'dır; PDFium'un dahiliCHECKileIMMEDIATE_CRASHmakrolarının bir değişmez bozulduğunda çalıştırdığıud2komutu yükseltir - Süreç
0xC0000409(fail-fast; stack buffer overrun diye bildirilir) ya da0xC0000374(heap corruption) ile çıkıyor; hiçbir Delphi exception'ı yok
Son iki madde, bu hatanın neden bu kadar zor saptandığıdır. Paralel iş biter, bozulmuş global durum geride kalır ve aynı süreçteki sonraki çağıran ona takılır: C000001D başarısızlıkları dalgası, batch'e hiç dokunmamış koda çarpar; çünkü o kod, hasardan sonra PDFium'u kullanan ilk koddur. Ölçek de göz ardı edilecek kadar küçük değildir. Aynı örneği tek modül üzerinde senkronize edilmemiş iki worker'a koşturmak bir koşuda 160 belgeden 122'sini, başka bir koşuda 138'ini başarısız kıldı ve o koşulardan biri açıkça External exception C000001D yükseltti
ValidatePdfFilesParallel nasıl güvenli kalır?
ValidatePdfFilesParallel her işin native yarısını serileştirir ve yönetilen yarısını paralel tutar. Her worker, TPdf'ini kurmadan önce bir unit düzeyi critical section alır ve onu FileName, Active := True, preflight raporu oluşturması ve Free boyunca tutar. Oluşturma ve yıkım bilerek kilit içindedir: bir belgeyi kapatmak da tıpkı yüklemek gibi modüle geri çağrı yapar. Worker, yakalanmış bir TPdfPreflightReport record'una sahip olduğunda kilidi bırakır ve doğrulama kurallarını o record'a karşı değerlendirir; bu hiçbir PDFium durumuna dokunmaz, dolayısıyla bir dosyanın kural değerlendirmesi, sonrakinin PDFium işiyle örtüşür
Bu tasarımın iki sonucu var. Bir yükleme başarısızlığı, LastLoadReport.ErrorMessage ile EPdfError yükseltir; böylece kaydın ErrorMessage alanı, ikincil bir aktif-belge-yok hatası yerine gerçek ayrıştırma sorununu bildirir. Ve bedel gerçektir: batch'in PDFium yarısı seridir; ayrıştırma ve preflight'ın hâkim olduğu bir batch'te ek worker'lar pek az şey kazandırır
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 = işlemci sayısı, 8'le sınırlandı
Options.Standards := [ppsPdfA];
// Açık bir registry ile eşleşen profili kendiniz seçin.
// Boş bir Profiles listesi kayıtlı her kuralı koşturur ve preflight
// etmediğiniz standartların kuralları "did not pass" bildirir
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;
Registry olarak nil geçirmek kısa yoldur: ValidatePdfFilesParallel o zaman varsayılan registry'nin kendisini kurar, profil listesini Options.Standards'tan türetir ve dönerken registry'yi serbest bırakır. Sonuçlar, worker'lar hangi sırada bitmiş olursa olsun daima girdi sırasıyla döner. Rapor biçimleri ve aynı motorun etrafındaki komut satırı sarmalayıcısı için PDFium Component CLI ile batch PDF preflight raporları'na, PDF/A kontrollerinin kendilerinin neleri kapsadığı için Delphi'de PDF/A preflight doğrulaması yazısına bakın
RenderPagesParallel sayfaları gerçekten paralel nasıl koşturur?
TPdf.RenderPagesParallel paralel koşar, çünkü worker'ları hiçbir zaman bir PDFium modülü paylaşmaz. Metot önce aktif belgeyi, çağıran thread üzerinde bir kaynak deposuna kaydeder. Sonra her worker, yüklenmiş PDFium DLL'sini geçici dizinde benzersiz adlı bir dosyaya kopyalar, o kopyayı LoadLibrary ile yükler ve başlatır. Windows, başka bir yoldan yüklenen bir DLL'yi farklı bir modül sayar; dolayısıyla her kopya kendi global'lerini alır: kendi font cache'i, kendi page module'ü, kendi her şeyi. Worker, kaydedilmiş belgeyi kendi özel modülünde açar, sayfalarını adımlar arası iptal kontrolleriyle aşamalı olarak render eder, sonra kütüphaneyi yok eder, kopyayı boşaltır ve dosyayı siler
Yalıtım bedava değildir ve varsayılanlar bunu yansıtır. Her worker, diskte bir DLL kopyasının, bellekte ikinci bir PDFium global kümesinin ve belgenin taze bir ayrıştırmasının bedelini öder. MaxWorkers = 0 en çok 4 worker demektir; MaxPixelsPerPage ile MaxTotalOutputBytes ham çıktıyı tavanlar ve tamponlar ham döndürüldüğü için inverted ile gece-duotone render seçenekleri reddedilir. Sonuç, Results dizisi istenen her sayfa için istek sırasıyla bir üstten-aşağı 32 bitlik tampon tutan bir TPdfParallelRenderReport'tur
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; // sayfa numaraları 1 tabanlıdır
Options := TPdfParallelRenderOptions.Default;
Options.Dpi := 150;
Options.MaxWorkers := 4;
// Kaynak anlık görüntüsü paylaşılan modülde alınır; öteki thread'ler de
// TPdf kullanıyorsa süreç geneli PDFium kilidini tutun
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;
Çağrının çevresindeki kilide dikkat. Worker modülleri özeldir ama baştaki anlık görüntü adımı, çağıran thread üzerinden paylaşılan modülde SaveAs koşturur. Süreçte başka hiçbir şey eşzamanlı olarak TPdf'ye dokunmuyorsa kilidi atlayabilirsiniz; bir şey dokunuyorsa anlık görüntü, öteki her paylaşılan-modül çağrısıyla aynı korumayı ister
| Örüntü | Belgeler arası güvenli | PDFium işi paralel koşar | Bedel |
|---|---|---|---|
Thread başına bir TPdf, paylaşılan kilit yok | Hayır | Evet, bozulana kadar | Aralıklı çökmeler, hasar görmüş süreç durumu |
| Tüm PDFium çağrıları çevresinde tek süreç geneli kilit | Evet | Hayır | PDFium yarısı seri |
ValidatePdfFilesParallel | Evet | Hayır; kural değerlendirmesi paralel | Ayrıştırma ve preflight seri |
TPdf.RenderPagesParallel | Evet | Evet | Worker başına DLL kopyası, bellek ve taze bir ayrıştırma |
Kendi çok thread'li PDFium kodunuzu nasıl yapılandırmalısınız?
Kendi thread'leriniz tek bir süreç geneli kilidi paylaşmalı ve kullandıkları her TPdf'nin tüm yaşamı boyunca onu tutmalı ya da modülü sizin için yalıtan bir bileşen API'si kullanmalıdır. Kilit, tüm süreç için tek bir nesne olmalıdır; thread başına, form başına veya belge başına bir kilit değil; iki thread'in paylaşmadığı bir kilit hiçbir şeyi korumaz. Aşağıdaki örüntü, bileşenin içeride yaptığının aynadır: oluştur, yükle, oku ve serbest bırak kilidin içinde; PDFium'a dokunmayan her şeyi ise dışında yapın
uses
System.Classes, System.SysUtils, System.SyncObjs, PDFium;
var
PdfiumLock: TCriticalSection; // bütün süreç için tek kilit
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; // belgeyi kapatmak da PDFium işidir
end;
finally
PdfiumLock.Release;
end;
// Bu satırın altında PDFium yok; dolayısıyla bu kısım paralel koşar
FText := Raw.ToString.Trim;
finally
Raw.Free;
end;
end;
initialization
PdfiumLock := TCriticalSection.Create;
finalization
PdfiumLock.Free;
Birkaç kural, örüntüyü gerçek bir uygulamada dürüst tutar:
TPdf.CreateileFree'yi kilit içine koyun; yalnızca bariz çağrıları değil. Yükleme, kapatma,PageCountgibi property okumaları, sayfa değişimleri, metin çıkarma, render ve kaydetmenin hepsi modüle uzanırActive'i atadıktan sonra kontrol edin. Başarısız bir yüklemeActive'iFalse'ta bırakır veLastLoadReport.ErrorMessagenedenini söyler- Kilidi çağrı başına değil belge başına tutun. Daha ince kilitleme ilke olarak mümkündür ama yalnızca hiçbir
TPdfüyesinin dışında koşmadığı durumlarda; bileşenin kendisinin bel bağladığı da kaba sürümdür - Veritabanı yazımları, indeksleme ve ağ çağrıları gibi yavaş PDFium-dışı işleri kilit dışında tutun; yoksa yavaş bir tüketici her şeyi serileştirir
- Özel instance başına render kilidini bir ikame olarak görmeyin. O, tek bir
TPdf'yi kendisine karşı korur, daha fazlasını değil
Aynı dikkat, ham thread olarak yazmadığınız kod için de geçerlidir. Arka plan future'ları, uzun render'ları UI thread'inin dışında tutmanın iyi bir yoludur; iptal edilebilir future'larla arka plan PDF render yazısında anlatıldığı gibi. Ama future executor'ı kendine ait bir global PDFium kilidi eklemez. Birkaç future aynı anda farklı TPdf instance'larını sürebiliyorsa her worker içinde aynı süreç geneli kilidi alın ve ana thread'deki bir görüntüleyiciyi paylaşılan modülün bir müşterisi daha sayın. Tutucu varsayım şudur: asenkron API'ler üzerinden çapraz-instance kullanım, elle yazılmış thread'lerle aynı serileştirmeye ihtiyaç duyar. Sayfa render dışında gerçek PDFium paralelliğine ihtiyaç duyduğunuzda ayrı worker süreçleri, her işe tasarım gereği kendi modülünü verir
Hızlı başvuru: Delphi için PDFium threading kuralları
- PDFium'un güvensiz durumu modül genişidir: font cache, page module ve öteki global'ler süreçteki her belge tarafından paylaşılır
- Thread başına bir
TPdfhiçbir şeyi yalıtmaz; iki thread'deki iki instance hâlâ birbirini bozabilir - Tipik belirtiler yükleme başarısızlıkları, sonraki kodda access violation'lar,
External exception C000001Dve0xC0000409ya da0xC0000374ile çıkışlardır - Bozulma süreçte kalıcıdır; dolayısıyla başarısız olan çağrı çoğunlukla ona neden olan değildir
ValidatePdfFilesParallel, her işin PDFium yarısını tek bir süreç geneli kilidin arkasında serileştirir ve kuralları paralel değerlendirirTPdf.RenderPagesParallelgerçekten paraleldir, çünkü her worker PDFium modülünün yalıtılmış bir kopyasını yükler- Kendi thread'leriniz, task'larınız ve future'larınız, her
TPdf'yiCreate'denFree'ye kapsayan tek bir süreç geneli kilide ihtiyaç duyar
PDFium Component, PDFium motorunu Delphi için batch preflight ve doğrulama, yalıtılmış paralel render, iptal edilebilir arka plan işi ve ayrıntılı yükleme teşhisiyle sarar. Ayrıntılar ve sürümler PDFium Component ürün sayfasında