Teknik Makale

HotPDF RenderCacheFolder: Delphi'de disk page cache'i

Dosya adıyla anahtarlanmış bir sayfa cache'i, bir gece aynı adla yeni bir revizyonla üzerine yazılmış bir PDF için dünkü sayfaları gösterir. Dosyanın tam SHA-256'sıyla anahtarlanan bir cache o hatayı asla yapmaz ama 400 MB'lık taranmış bir arşivde hash, kullanıcının gerçekten açtığı iki sayfayı render etmekten daha uzun sürebilir. İşe yarar anahtar o ikisinin arasında oturur ve onu seçmek ikinci bir kararı da zorunlu kılar: bellek içi bir düzenleme, diskte çoktan oturan sayfalara ne yapmalı

RenderCacheFolder disk katmanı bellek cache'inin arkasında nasıl oturur?

HotPDF RenderCacheFolder, HotPDF Delphi component'inin bellek içi raster cache'inin arkasına kalıcı bir katman ekler ve yalnızca özellik boş olmayan bir yol tuttuğunda devreye girer. RenderLoadedPageToBitmapCached(PageIndex, DPI) çağrısı önce belleğe bakar; anahtar olarak sayfa indeksini, DPI'yi ve mevcut render ayarlarını kullanır. Iskalayınca diske sorar. Disk isabeti saklanan PNG'yi decode eder, belleğe geri terfi ettirir ve size bir kopya verir. İki katman da ıskaladığında sayfa, yüklenmiş bir PDF sayfasını TBitmap'e render etmeyi anlatan tam renderer'dan geçer ve o taze bitmap çıkarken diske yazılır

RenderLoadedPageToBitmapCached için HotPDF render cache arama şeması: önce sayfa, DPI ve render varyantıyla anahtarlanan bellek içi katman denetlenir; sonra atomik replace ile RenderCacheFolder PNG disk katmanı; sonra content-stream yorumlayıcısı gelir ve her isabet çağıranın malı bir kopya döndürür
HotPDF önce belleğe, sonra diske bakar ve ancak ondan sonra rasterize eder; disk isabeti belleğe geri terfi ettirilir ve her yol size sahip olduğunuz ve free etmeniz gereken bir kopya verir

Klasör düzeni Explorer'da incelemeye yeterince düzdür. Her belge, adı 16 hex karakterlik bir belge anahtarıyla 16 hex karakterlik bir render ayarları anahtarını birleştiren bir alt klasör alır ve her sayfa oraya <page>@<dpi>.png olarak düşer. Kökteki bir index.txt, belgeleri bir şema etiketi altında en son kullanılan sırada listeler; etiket uyuşmazsa bütün klasör ilk kullanımda temizlenir. PNG ile indeks yazımı önce geçici bir dosyaya gider ve sonra MoveFileExW ile replace-existing bayrağıyla yer değiştirir; yazımın ortasında bir çökme önceki dosyayı ya da hiç dosyayı bırakır. Decode edilemeyen bir PNG silinir ve ıskalama sayılır

Üç sınır klasörün sınırsız büyümesini önler:

  • RenderCacheMaxDocuments (varsayılan 20) belge alt klasörlerinin sayısını sınırlar, en son kullanılanı önce süpürür
  • RenderCacheMaxBytes (varsayılan 524288000, yani 500 MB) kök altındaki her PNG'nin birleşik boyutunu sınırlar
  • Her belge klasörü en fazla 200 sayfa görüntüsü tutar; o tavan THotPDF'in içinde sabittir ve bir özelliği yoktur

RenderCacheCapacity (varsayılan 8) disk ile ilgisizdir. Bellekte tutulan sayfaları sayar

uses
  SysUtils, Graphics, HPDFDoc;

procedure WarmThumbnails(const FileName: string);
var
  Pdf: THotPDF;
  Bmp: TBitmap;
  I: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    // Disk katmanı klasörü ile iki sınırı bir kez okur, ilk önbellekli
    // render'da; o yüzden o çağrıdan önce set edin
    Pdf.RenderCacheFolder := IncludeTrailingPathDelimiter(
      GetEnvironmentVariable('LOCALAPPDATA')) + 'MyViewer\PageCache';
    Pdf.RenderCacheMaxDocuments := 50;
    Pdf.RenderCacheMaxBytes := Int64(1024) * 1024 * 1024; // 1 GiB
    Pdf.RenderCacheCapacity := 16;                        // bellekte sayfalar

    if Pdf.LoadFromFile(FileName) > 0 then
      for I := 0 to Pdf.LoadedPageCount - 1 do
      begin
        Bmp := Pdf.RenderLoadedPageToBitmapCached(I, 96);
        if Bmp <> nil then
        try
          // Kopyayı burada küçük resim şeridine verin
        finally
          Bmp.Free; // önbellekli çağrı daima çağıranın malı bir kopya döndürür
        end;
      end;
  finally
    Pdf.Free; // disk girişleri sonraki oturum için yaşar
  end;
end;

O prosedürü aynı dosyada iki kez koşturun; ikinci geçiş, sınırlara sığan hiçbir şeyi rasterize etmez. Disk cache'i ilk önbellekli render'da kurulur ve THotPDF örneği kadar yaşar; o andan sonra klasörü ya da iki sınırdan birini değiştirmek onu taşımaz ya da yeniden boyutlamaz. İki koşul daha bir sayfayı diskten uzak tutar. Bellek cache'inin varsayılan giriş başına tavanını (32 bitlik pikselle 64 MiB; 4096 × 4096 bir sayfa) aşan bir bitmap saklanmaz. Ve disk katmanına yalnızca RenderFallbackPolicy varsayılanı rfpIgnore'de dururken başvurulur; çünkü bir PNG pikselleri taşır ama daha katı bir politikanın bildirdiği fallback teşhislerinden hiçbirini taşımaz

Bariz cache anahtarları neden başarısız olur?

Aklıma ilk gelen üç anahtar var ve her biri başka bir biçimde başarısız olur. Dosya yolu üzerine yazmada başarısız olur. PDF baytlarının bellek içi bir kopyasının hash'i, yerinde okuyan bir parser'ın öyle bir kopya tutma nedeni olmadığını fark edene dek güvenli görünür; hiç doldurulmamış bir tamponu hash'lemek boş bir anahtar verir ve boş anahtarı "diski atla" sayan bir cache, hiç PNG almayan doğru yapılandırılmış bir klasör bırakır. Bütün dosyayı diskten hash'lemek çalışır, her açılışta her baytı okuma bedeliyle

Daha zor tuzak geçersiz kılmadır. Böyle bir component, bellek içi sayfalarını her yüklemenin başında, her düzenlemeden sonra ve yok edilirken temizlemek zorundadır; cazip hamle, belgenin disk klasörünü aynı yerde silmektir. Yapın; her görüntüleyici oturumu çıkarken kendi cache'ini siler ve ertesi sabah yine soğuk başlar. Düzenlemeden sonra değişmemiş kaynaktan anahtarı yeniden hesaplamak daha beter: düzenlenen render'lar orijinal dosyanın anahtarı altına düşer ve sonraki açan kişiye, dokunulmamış PDF'i açan kim olursa sunulur. Kimlik ile geçersiz kılma tek parça olarak tasarlanmalıdır. İkisinden birini yanlış yapın ya hiç isabet etmeyen bir cache ya da dosyanın içermediği sayfaları gösteren bir cache dağıtırsınız

HotPDF bir PDF kaynağını nasıl parmak izler?

HotPDF, LoadFromFile ile yüklenen bir PDF'i boyutunu, son yazma zamanını ile ilk ve son 64 KiB'sini SHA-256 ile hash'leyerek tanımlar; stream ya da rastgele erişimli bir kaynağı içeriğin tamamının SHA-256'sıyla tanımlar. Kimlik, bir yükleme başarılı olduğunda bir kez yakalanır ve digest'in ilk 16 hex karakteri (64 bit) belge anahtarı olur

KaynakKimlikMaliyetNe zaman yakalanır
LoadFromFileBoyut + son yazma zamanı + baştaki ve sondaki 64 KiB, SHA-256 ile hash'liDosya boyutu ne olursa olsun en fazla 128 KiB okumaHer başarılı yükleme; RenderCacheFolder sonradan set edilse bile
LoadFromStreamBütün stream'in SHA-256'sıKaynak üzerinde bir tam geçişYalnızca RenderCacheFolder yüklemeden önce set edilmişse
LoadFromRandomAccessSourceBütün kaynağın SHA-256'sıKaynak üzerinde bir tam geçişYalnızca klasör önce set edilmişse ve her bayt aralığı ulaşılabilirse
/Encrypt girdisi taşıyan her kaynakYokYokAsla; disk katmanı bypass edilir
Disk render cache'i için HotPDF kaynak kimlik haritası: LoadFromFile boyutu, LastWriteTime'ı ve ilk ile son 64 KiB'yi hash'ler; LoadFromStream ile LoadFromRandomAccessSource bütün içeriği yalnızca RenderCacheFolder önce set edildiğinde hash'ler ve /Encrypt trailer'ı taşıyan hiçbir kaynak kimlik yakalamaz
dosyalar uçlarından parmak izlenir, çünkü header, xref ve trailer orada durur; stream'ler tam hash'in bedelini yalnızca cache'i önce istediğinizde öder ve şifreli belgeler diske asla yazılmaz

Masaüstü bir görüntüleyici için örneklenmiş parmak izi doğru varsaylandır, her açılışta tam hash yanlış olan. İki örneklenmiş bölge dosya yapısından seçildi. Header başta oturur; trailer ile son çapraz referans bölümü sonda oturur (ISO 32000-1 §7.5). Bir artımlı güncelleme yeni bir body, çapraz referans bölümü ile trailer ekler (§7.5.6); boyut ile kuyruğu birlikte değiştirir ve sıradan her tam yeniden yazım son yazma zamanını ilerletir. 128 KiB'nin altında iki örnek üst üste biner ve her baytı kapsar; küçük belgeler zaten tam olarak hash'lenir

Kaçan hâl, büyük bir dosyanın ortasında aynı boyutlu bir düzenleme yapan ve sonra orijinal zaman damgasını geri koyan bir araçtır. İçeriği değiştirirken değişiklik zamanlarını bilerek koruyan düzenleyiciler vardır ama nadirdirler ve öyle bir dosyaya karşı cache eski sayfaları sunar. Tersi lehinize işler: bir Windows dosya kopyası son yazma zamanını korur; önbelleklenmiş bir belgenin kopyası aynı girişlere isabet eder ve baytlar uyuştuğu için bu doğrudur

Bir stream'in zaman damgası yoktur. İçerik tek dürüst kimliktir; HotPDF tam SHA-256 geçişinin bedelini yalnızca disk cache'i yüklemeden önce istenmişse öder ve cache klasörü olmadan LoadFromStream çağıran kod hiçbir ek bedel ödemez. İki satırın sırası bu yüzden önemli:

procedure OpenDownloadedPdf(Pdf: THotPDF; Data: TStream;
  const CacheRoot: string);
begin
  // Stream'ler için yanlış sıra: içerik hash'i yalnızca klasör hâlihazırda
  // setliyken hesaplanır; bu belge disk katmanını bypass ederdi
  //   Pdf.LoadFromStream(Data);
  //   Pdf.RenderCacheFolder := CacheRoot;

  Pdf.RenderCacheFolder := CacheRoot; // önce set edin
  Data.Position := 0;
  if Pdf.LoadFromStream(Data) <= 0 then
    raise Exception.Create('The stream is not a loadable PDF');
end;

Hâlâ inen bir rastgele erişimli kaynak, gelen aralıkların hash'i yerine hiçbir kimlik almaz. Kimliği hesaplamak herhangi bir nedenle throw ederse yükleme yine başarılı olur ve belge yalnızca bellek üzerinden render edilir

Düzenlemeden sonra önbelleklenmiş sayfalara ne olur?

Yüklenmiş bir belgeyi düzenlemek, HotPDF disk render cache'inden hiçbir şey silmez. Düzenleme belgenin kimliğini düşürür; o yüzden o yüklemenin gerisi disk katmanını bypass eder ve saklanan sayfalar, render edildikleri değişmemiş dosya için geçerli kalır. Girişler diski yalnızca belge ile bayt sınırları, 200 sayfa tavanı, decode edilemeyen bir PNG ya da bir şema değişikliğiyle terk eder

Anahtar diskteki bir dosyayı tarif eder. Bir sayfa damgaladığınız ya da bir annotation değiştirdiğinizde bellekteki belge onunla artık uyuşmaz; o anahtar altında ne okuma ne yazma dürüst olurdu. InvalidateRenderedPageCache ile düzenlemelerin tetiklediği sayfa başına geçersiz kılma ikisi de kimliği temizler ve klasöre dokunmaz. İkinci bir kontrol, hiçbir şeyi geçersiz kılmayan düzenleme yollarını kapsar: her disk aramasından önce THotPDF, yüklenmiş herhangi bir object'in kaydedilmemiş değişiklikler taşıyıp taşımadığına bakar ve taşıyorsa belgeyi kimlikesiz sayar

Render ayarları öbür yönde işler. PageRenderBackend atamak (bunu UseNativeGDIRenderBackend sizin için yapar), ConfigureRenderICCWorkflow ya da ClearRenderICCWorkflow çağırmak bellekteki sayfaları boşaltır ama kimliği tutar; çünkü belge hâlâ dosyasıyla uyuşur. O ayarlar, bellek anahtarında görünmeden pikselleri değiştirir; o yüzden disk anahtarı backend adını, black-point compensation bayrağını ile ICC proof ile output profillerinin SHA-256 özetlerini katlar. Bellek anahtarı renk niyetini, çıktı dithering'ini, overprint önizlemesini, luminosity mask modunu, fallback politikasını ile her isteğe bağlı content grubunun görünürlüğünü çoktan kapsar

RenderCacheFolder disk cache'i için HotPDF geçersiz kılma semantiği: yüklenen belgeyi ya da kirli bir objecti düzenlemek kaynak kimliğini düşürür ve katman bypass edilir; render backend ya da ICC workflow değişikliği kimliği yeni bir varyant anahtarı altında tutar; kaydetmek ve yeniden yüklemek ise belgeyi yeni anahtara taşır
bir düzenleme saklanan klasörü asla silmez, bir ayar değişikliği farklı bir anahtar altında render eder ve yalnızca kaydetme artı yeniden yükleme, düzenlenmiş belgeye taze bir kimlik kazandırır

Katman görünürlüğü, diskte kalan bir değişikliğin iyi bir örneğidir. SetLoadedOptionalContentGroupVisible, hiçbir PDF object'ine dokunmadan override'ı bellekte kaydeder; belge kimliğini korur ve açılıp kapanan görünüm kendi alt klasörüne, varsayılanın yanına render edilir:

procedure ShowLayer(Pdf: THotPDF; const LayerName: AnsiString;
  PageIndex: Integer; out Bmp: TBitmap);
var
  I: Integer;
begin
  for I := 0 to Pdf.GetLoadedOptionalContentGroupCount - 1 do
    if Pdf.GetLoadedOptionalContentGroupName(I) = LayerName then
      Pdf.SetLoadedOptionalContentGroupVisible(I, True);

  // Aynı belge anahtarı, farklı render ayarları anahtarı: bu sayfa ikinci bir
  // klasörden okunur ya da oraya yazılır, varsayılan görünüm dokunulmaz
  Bmp := Pdf.RenderLoadedPageToBitmapCached(PageIndex, 150);
end;

Düzenlenmiş bir belge, ancak yeni bir dosya olarak diske geri döner. Kaydedin ve sonucu yükleyin:

procedure CommitEditsAndRekey(Pdf: THotPDF; const EditedFile: string);
begin
  // Düzenlemeden sonra: bellek içi sayfaları tazeleyin. Kaynak kimliği
  // çoktan gitmiştir; orijinal belgenin klasörü ne okunur
  // ne yazılır
  Pdf.InvalidateRenderedPageCache;

  // Kaydedilen dosyanın kendi boyutu ile son yazma zamanı, dolayısıyla
  // kendi kimliği vardır; bu yüklemeden sonraki render'lar yeni anahtar altında önbelleklenir
  Pdf.SaveLoadedDocument(EditedFile);
  if Pdf.LoadFromFile(EditedFile) <= 0 then
    raise Exception.Create('Could not reload the edited document');
end;

Orijinal belgenin klasörü yerinde kalır ve RenderCacheMaxDocuments ile RenderCacheMaxBytes üzerinden her öteki giriş gibi yaşlanır. Düzenlenmemiş orijinali yeniden açın; sayfaları hâlâ oradadır

Şifreli kaynaklar, junction'lar ve paylaşılan kökler

HotPDF disk render cache'i iki girdiyi bilerek reddeder: şifreli bir PDF'in sayfaları ile junction ya da başka bir reparse point olan belge alt klasörleri. Her iki kural da cache isabetlerini güvenliğe takas eder

Şifreli PDF'ler bellekte kalır

Render edilmiş bir sayfa çözülmüş içeriktir. Onu düz bir PNG olarak bir cache klasörüne yazmak, parola korumalı bir belgenin okunabilir bir kopyasını, yazarının seçtiği korumanın dışında (ISO 32000-1 §7.6) diskte bırakır. HotPDF, trailer'ında /Encrypt girdisi taşıyan hiçbir kaynak için — parola ile açılmış olsun, boş user password ile olsun — kimlik yakalamaz. O belgeler bellek katmanını kullanmaya devam eder; o katman process ile birlikte kaybolur

Bağlantılı belge klasörleri atlanır

Cache kökünü siz seçersiniz ve onu bir junction'a yöneltmek sorun değildir. Altındaki alt klasörler başka bir iştir: cache onları başlangıç temizliği, arama, saklama ve üç süpürme sınırının tamamında kendi başına kurar, dokunur ve siler. Köke yazma erişimi olan biri bir belge klasörünü başka bir dizine bir junction'la takas etseydi o işlemlerin her biri onu izlerdi ve süpürme başka yerdeki dosyaları silerdi. Her giriş noktası önce klasörün özniteliklerini okur ve reparse point olarak işaretli her şeyi atlar. Bir arama ıskalama sayar, bir saklama yazım başarısızlığı sayar ve süpürme ona dokunmaz

Unicode yolları ve process başına tek kök

RenderCacheFolder Unicode bir string'dir ve atomik replace geniş Windows API'yi çağırır; böylece sistem code page'inin dışında bir profil yolu (İngilizce bir Windows kurulumunda bir Çince kullanıcı adı diyelim) cache'e bozulmadan ulaşır. Aynı köke — yol genişletmesinden sonra büyük küçük harf duyarsız kıyasla — çözülen tek process'teki birkaç THotPDF örneği, referans sayımlı tek bir indeksi ile tek bir kilidi paylaşır. Sınırlar için önemlidir: ayrı index.txt kopyalarının her biri 500 MB bütçesini kısmi bir görünüme karşı dayatırdı ve klasörün birkaç kat aşmasına izin verirdi

Paylaşım process sınırında biter. Aynı kökteki iki process ayrı bellek içi indeksler tutar; her eşzamanlı koşan uygulama kendi kökünü almalıdır. Bir process'in içindeki worker thread'ler sorun değildir: PrefetchLoadedPages ile istek kuyruğuyla arka planda render aynı önbellekli yoldan ve aynı kilitten geçer

Dağıtımdan önce doğru yapılacak ayarlar

  • Klasörü ile iki sınırı ilk önbellekli render'dan önce, stream ya da rastgele erişimli yüklemeler için yüklemeden önce set edin
  • Şifreli PDF'ler için, yüklemeden sonra düzenlenen belgeler için ve RenderFallbackPolicy rfpIgnore olmadığında yalnızca bellek render bekleyin
  • Koşan her uygulamaya %LOCALAPPDATA% gibi kullanıcı başına bir konum altında kendi cache kökünü verin

Kalıcı bir sayfa cache'i, aynı belgeleri bütün gün yeniden açan bir görüntüleyicide disk alanını hak eder; bu blogdaki Delphi'de özel PDF görüntüleyici mimarisinin arkasındaki iş yükü budur. Disk katmanı, bellek raster cache'i ile sayfa renderer'ı, Delphi ile C++Builder için HotPDF Delphi PDF component'in parçasıdır