Technical Article

HotPDF RenderCacheFolder: A Disk Page Cache in Delphi

A page cache keyed by file name will show yesterday's pages for a PDF that was overwritten overnight with a new revision under the same name. A cache keyed by a full SHA-256 of the file never makes that mistake, but on a 400 MB scanned archive the hash can take longer than rendering the two pages the user actually opens. The workable key sits between those two, and choosing it also forces a second decision: what an in-memory edit should do to pages already sitting on disk

How the RenderCacheFolder disk tier sits behind the memory cache

HotPDF RenderCacheFolder adds a persistent tier behind the in-memory raster cache of the HotPDF Delphi component, and it only takes part when the property holds a non-empty path. A call to RenderLoadedPageToBitmapCached(PageIndex, DPI) checks memory first, using page index, DPI and the current render settings as the key. On a miss it asks the disk. A disk hit decodes the stored PNG, promotes it back into memory and hands you a copy. Only when both tiers miss does the page go through the full renderer described in rendering a loaded PDF page to a TBitmap, and that fresh bitmap is written to disk on the way out

HotPDF diagram of the render cache lookup for RenderLoadedPageToBitmapCached: the in-memory tier keyed by page, DPI and render variant is checked first, then the RenderCacheFolder disk tier of PNG files with atomic replace, then the content-stream interpreter, and every hit returns a caller-owned copy
HotPDF looks in memory first, then on disk, and only then rasterises; a disk hit is promoted back into memory and every path hands you a copy you own and must free

The folder layout is plain enough to inspect in Explorer. Each document gets a subfolder whose name combines a 16-hex-character document key with a 16-hex-character render-settings key, and every page lands there as <page>@<dpi>.png. An index.txt at the root lists documents in most-recently-used order under a schema tag; if the tag does not match, the whole folder is cleared on first use. PNG and index writes go to a temporary file first and are then swapped in with MoveFileExW and the replace-existing flag, so a crash halfway through a write leaves the previous file or no file. A PNG that fails to decode is deleted and counted as a miss

Three limits keep the folder from growing without bound:

  • RenderCacheMaxDocuments (default 20) caps the number of document subfolders, evicting the least recently used one first
  • RenderCacheMaxBytes (default 524288000, or 500 MB) caps the combined size of every PNG under the root
  • Each document folder holds at most 200 page images; that cap is fixed inside THotPDF and has no property

RenderCacheCapacity (default 8) is unrelated to the disk. It counts pages held in memory

uses
  SysUtils, Graphics, HPDFDoc;

procedure WarmThumbnails(const FileName: string);
var
  Pdf: THotPDF;
  Bmp: TBitmap;
  I: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    // The disk tier reads the folder and both limits once, on the first
    // cached render, so set them before that call
    Pdf.RenderCacheFolder := IncludeTrailingPathDelimiter(
      GetEnvironmentVariable('LOCALAPPDATA')) + 'MyViewer\PageCache';
    Pdf.RenderCacheMaxDocuments := 50;
    Pdf.RenderCacheMaxBytes := Int64(1024) * 1024 * 1024; // 1 GiB
    Pdf.RenderCacheCapacity := 16;                        // pages in memory

    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
          // Hand the copy to the thumbnail strip here
        finally
          Bmp.Free; // the cached call always returns a caller-owned copy
        end;
      end;
  finally
    Pdf.Free; // disk entries survive for the next session
  end;
end;

Run that procedure twice on the same file and the second pass rasterises nothing that fit the limits. The disk cache is created on the first cached render and lives as long as the THotPDF instance, so changing the folder or either limit after that moment does not move or resize it. Two more conditions keep a page off the disk. A bitmap above the memory cache's default per-entry ceiling (64 MiB of 32-bit pixels, a 4096 × 4096 page) is not stored. And the disk tier is consulted only while RenderFallbackPolicy stays at its default rfpIgnore, since a PNG carries pixels but none of the fallback diagnostics a stricter policy reports

Why do the obvious cache keys fail?

Three keys come to mind first, and each fails in a different way. The file path fails on overwrite. A hash of an in-memory copy of the PDF bytes looks safe until you notice that a parser reading the file in place has no reason to keep such a copy; hashing a buffer that was never filled yields an empty key, and a cache that treats an empty key as "skip the disk" leaves a correctly configured folder that never receives a PNG. Hashing the whole file from disk works, at the cost of reading every byte on every open

The harder trap is invalidation. A component like this has to clear its in-memory pages at the start of every load, after every edit and when it is destroyed, and the tempting move is to delete the document's disk folder in the same place. Do that and every viewer session wipes its own cache on exit, so the next morning starts cold anyway. Recomputing the key from the unchanged source after an edit is worse still: the edited renders land under the original file's key and get served to whoever opens the untouched PDF next. Identity and invalidation have to be designed as one piece. Get either one wrong and you ship a cache that never hits, or one that shows pages the file does not contain

How HotPDF fingerprints a PDF source

HotPDF identifies a PDF loaded with LoadFromFile by hashing its size, its last-write time and its first and last 64 KiB with SHA-256, and identifies a stream or random-access source by a SHA-256 of the entire content. The identity is captured once, when a load succeeds, and the first 16 hex characters of the digest (64 bits) become the document key

SourceIdentityCostCaptured when
LoadFromFileSize + last-write time + leading and trailing 64 KiB, hashed with SHA-256At most 128 KiB read, whatever the file sizeEvery successful load, even if RenderCacheFolder is set afterwards
LoadFromStreamSHA-256 of the whole streamOne full pass over the sourceOnly if RenderCacheFolder was set before the load
LoadFromRandomAccessSourceSHA-256 of the whole sourceOne full pass over the sourceOnly if the folder was set first and every byte range is available
Any source with an /Encrypt entryNoneNoneNever; the disk tier is bypassed
HotPDF source identity map for the disk render cache: LoadFromFile hashes size, LastWriteTime and the first and last 64 KiB, LoadFromStream and LoadFromRandomAccessSource hash the whole content only when RenderCacheFolder was set first, and any /Encrypt trailer captures no identity at all
files are fingerprinted from their ends because the header, xref and trailer live there, streams only pay for a full hash when you asked for the cache first, and encrypted documents are never written to disk

For a desktop viewer the sampled fingerprint is the right default, and full hashing on every open is the wrong one. The two sampled regions were picked from the file structure. The header sits at the start; the trailer and the last cross-reference section sit at the end (ISO 32000-1 §7.5). An incremental update appends a new body, cross-reference section and trailer (§7.5.6), which changes the size and the tail together, and any ordinary full rewrite bumps the last-write time. Below 128 KiB the two samples overlap and cover every byte, so small documents are hashed in full anyway

What slips through is a same-size edit in the middle of a large file by a tool that then restores the original timestamp. Editors that deliberately preserve modification times while changing content exist, but they are rare, and against such a file the cache serves stale pages. The opposite case works in your favour: a Windows file copy keeps the last-write time, so a copy of a cached document hits the same entries, which is correct since the bytes match

A stream has no timestamp. Content is the only honest identity, so HotPDF pays for the full SHA-256 pass only when a disk cache was requested before the load, and code that calls LoadFromStream without a cache folder pays nothing extra. That makes the order of two lines matter:

procedure OpenDownloadedPdf(Pdf: THotPDF; Data: TStream;
  const CacheRoot: string);
begin
  // Wrong order for streams: the content hash is only computed when the
  // folder is already set, so this document would bypass the disk tier
  //   Pdf.LoadFromStream(Data);
  //   Pdf.RenderCacheFolder := CacheRoot;

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

A random-access source that is still downloading gets no identity at all instead of a hash of whatever ranges have arrived. If computing the identity throws for any reason, the load still succeeds and the document renders through memory only

What happens to cached pages after an edit?

Editing a loaded document never deletes anything from the HotPDF disk render cache. The edit drops the document's identity instead, so the rest of that load bypasses the disk tier, and the stored pages stay valid for the unmodified file they were rendered from. Entries leave the disk only through the document and byte limits, the 200-page cap, a PNG that fails to decode, or a schema change

The key describes a file on disk. Once you stamp a page or change an annotation, the document in memory no longer matches it, so neither reading nor writing under that key would be honest. InvalidateRenderedPageCache and the per-page invalidation that edits trigger both clear the identity and leave the folder alone. A second check covers edit paths that never invalidated anything: before each disk lookup, THotPDF asks whether any loaded object carries unsaved changes and, if one does, treats the document as having no identity

Render settings go the other way. Assigning PageRenderBackend (which UseNativeGDIRenderBackend does for you), calling ConfigureRenderICCWorkflow or calling ClearRenderICCWorkflow flushes the pages in memory but keeps the identity, because the document still matches its file. Those settings change pixels without appearing in the memory key, so the disk key folds in the backend name, the black-point compensation flag and SHA-256 digests of the ICC proof and output profiles. The memory key already covers the colour intent, output dithering, overprint preview, luminosity mask mode, fallback policy and the visibility of every optional content group

HotPDF invalidation semantics for the RenderCacheFolder disk cache: editing the loaded document or any dirty object drops the source identity so the tier is bypassed, changing the render backend or ICC workflow keeps identity under a new variant key, and saving plus reloading rekeys the document
an edit never deletes the stored folder, a settings change renders under a different key, and only save plus reload earns the edited document a fresh identity

Layer visibility is a good example of a change that stays on disk. SetLoadedOptionalContentGroupVisible records the override in memory without touching any PDF object, so the document keeps its identity and the toggled view renders into its own subfolder next to the default one:

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);

  // Same document key, different render-settings key: this page is read
  // from or written to a second folder, and the default view is untouched
  Bmp := Pdf.RenderLoadedPageToBitmapCached(PageIndex, 150);
end;

An edited document gets back onto the disk tier only by becoming a new file. Save it and load the result:

procedure CommitEditsAndRekey(Pdf: THotPDF; const EditedFile: string);
begin
  // After editing: refresh the in-memory pages. The source identity is
  // already gone, so the original document's folder is neither read
  // nor written
  Pdf.InvalidateRenderedPageCache;

  // The saved file has its own size and last-write time, hence its own
  // identity; renders after this load are cached under the new key
  Pdf.SaveLoadedDocument(EditedFile);
  if Pdf.LoadFromFile(EditedFile) <= 0 then
    raise Exception.Create('Could not reload the edited document');
end;

The original document's folder stays where it was and ages out through RenderCacheMaxDocuments and RenderCacheMaxBytes like any other entry. Reopen the unedited original and its pages are still there

Encrypted sources, junctions and shared roots

The HotPDF disk render cache refuses two inputs on purpose: pages of an encrypted PDF, and document subfolders that are junctions or other reparse points. Both rules trade cache hits for safety

Encrypted PDFs stay in memory

A rendered page is decrypted content. Writing it as a plain PNG into a cache folder would leave a readable copy of a password-protected document on disk, outside the protection its author chose (ISO 32000-1 §7.6). HotPDF captures no identity for any source whose trailer carries an /Encrypt entry, whether it was opened with a password or with an empty user password. Those documents still use the memory tier, which disappears with the process

Linked document folders are skipped

The cache root is yours to choose, and pointing it at a junction is fine. The subfolders under it are different: the cache creates, touches and deletes them on its own during startup cleanup, lookup, store and all three eviction limits. If someone with write access to the root swapped a document folder for a junction to another directory, every one of those operations would follow it, and eviction would delete files elsewhere. Each entry point reads the folder's attributes first and skips anything flagged as a reparse point. A lookup counts a miss, a store counts a write failure, and eviction leaves it alone

Unicode paths and one root per process

RenderCacheFolder is a Unicode string, and the atomic replace calls the wide Windows API, so a profile path outside the system code page (a Chinese user name on an English Windows installation, say) reaches the cache intact. Several THotPDF instances in one process that resolve to the same root, compared case-insensitively after path expansion, share one reference-counted index and one lock. That matters for the limits: separate copies of index.txt would each enforce the 500 MB budget against a partial view and let the folder grow several times past it

Sharing ends at the process boundary. Two processes on the same root keep separate in-memory indexes, so each concurrently running application should get its own root. Worker threads inside one process are fine: PrefetchLoadedPages and the queue in background rendering with a request queue go through the same cached path and the same lock

Settings to get right before shipping

  • Set the folder and both limits before the first cached render, and for stream or random-access loads before loading
  • Expect memory-only rendering for encrypted PDFs, for documents edited after the load, and whenever RenderFallbackPolicy is not rfpIgnore
  • Give each running application its own cache root under a per-user location such as %LOCALAPPDATA%

A persistent page cache earns its disk space in a viewer that reopens the same documents all day, which is the workload behind the custom PDF viewer architecture in Delphi on this blog. The disk tier, the memory raster cache and the page renderer are all part of the HotPDF Delphi PDF component, available for Delphi and C++Builder