Technical Article

Stream Remote PDFs in Delphi: HotPDF Range Coalescing

A PDF that opens instantly from a local disk can take several seconds to show its first page when the same bytes come from an HTTP server answering range requests, even though the file is only a few megabytes and the link is fast. Bandwidth is not the problem. The request count is, and the cure is to turn hundreds of tiny scattered reads into a few dozen cached blocks, then read ahead only while the access pattern stays sequential

Why does the same PDF load instantly from disk and crawl over HTTP?

A PDF parser does not read a file front to back. It navigates one. The structure in ISO 32000-1 §7.5 puts the entry point at the end: the parser seeks to the last kilobyte for startxref, jumps back to the cross-reference table, resolves the trailer dictionary, follows a reference to the Catalog, then to the page tree root, then to a page node, then to that page's resource dictionary. Each hop reads tens of bytes from a different offset, and an incrementally updated file repeats the walk once per revision through the /Prev chain

On a local file this pattern is nearly free, because the operating system already holds the surrounding 4 KiB page in its file cache and the second read costs a memory copy. A network transport has no such locality. Every read becomes a request with its own latency, and the arithmetic is brutal: at 40 ms per round trip, 300 small reads add up to twelve seconds of waiting while the wire sits mostly idle. Reading less is not an option, since the parser needs exactly the bytes it asks for. What can change is how much each physical request brings back

Wrapping your transport in THPDFCoalescingRandomAccessSource

HotPDF loads documents from any class that descends from THPDFRandomAccessSource, and THPDFCoalescingRandomAccessSource sits between that class and the parser. Every read is rounded out to an aligned block and the block is kept in memory. BlockSize defaults to 262,144 bytes and MaxCacheBytes to 2,097,152, so eight blocks stay resident and the least recently used one goes when the budget is full. The parser's 40-byte lookup of a trailer key pulls in the 256 KiB around it, and the next dozen reads in that neighbourhood (cross-reference entries, the Catalog, page tree keys) come out of memory

Your own class stays thin. Two methods are mandatory: GetSize and ReadAt. Override ReadAtCancellable when your HTTP client can abort a request in flight, and override IsRangeAvailable when the source is a download still in progress. The wrapper asks that question before every fetch: if a whole block is not there yet it retries with just the bytes requested, and if those are missing too the read comes back short instead of blocking

Diagram of HotPDF block coalescing: scattered parser seeks are rounded up into cached 256 KiB blocks so later reads in the same neighbourhood are served from memory
reads are rounded up to cached 256 KiB blocks by default, so the parser's scatter costs one network transfer per neighbourhood
type
  // TMyHttpClient stands for your own HTTP client class
  THttpRangeSource = class(THPDFRandomAccessSource)
  private
    FClient: TMyHttpClient;
    FUrl: string;
    FSize: Int64;
  public
    constructor Create(const AUrl: string);
    function GetSize: Int64; override;
    function ReadAt(Offset: Int64; var Buffer; Count: Longint): Longint; override;
    function ReadAtCancellable(Offset: Int64; var Buffer; Count: Longint;
      CancellationToken: THPDFCancellationToken): Longint; override;
  end;

var
  Raw: THttpRangeSource;
  Cached: THPDFCoalescingRandomAccessSource;
  Pdf: THotPDF;
begin
  Raw := THttpRangeSource.Create('https://files.example.com/contract.pdf');
  // OwnsSource=True: the wrapper frees Raw; 256 KiB blocks, 8 MiB budget
  Cached := THPDFCoalescingRandomAccessSource.Create(Raw, True, 262144, 8388608);
  Cached.MaxReadAheadBlocks := 8;   // valid range 1..32
  Pdf := THotPDF.Create(nil);
  try
    // OwnsSource=True again: Pdf frees Cached, which frees Raw
    if Pdf.LoadFromRandomAccessSource(Cached, True) > 0 then
      RenderFirstPage(Pdf);   // your own code
  finally
    Pdf.Free;
  end;
end;

Asynchronous prefetch and adaptive read-ahead are both on as soon as the wrapper is constructed, so the sample only touches the window ceiling. The constructor validates its arguments up front: BlockSize must lie between 4,096 and 16,777,216 bytes and MaxCacheBytes must hold at least one block, otherwise you get an ERangeError before a single byte moves

You do not strictly need the explicit wrapper. Hand LoadFromRandomAccessSource a plain source and HotPDF wraps it for you, using the raw-cache policy you can read and change through GetCacheAdmissionPolicy and SetCacheAdmissionPolicy with the clkRawCompressed layer: eight entries, 2 MiB in total, 256 KiB per entry. Pass your own THPDFCoalescingRandomAccessSource and it is used exactly as configured. For anything that crosses a network, build the wrapper yourself; you get the read-ahead knobs and the full statistics record, while the automatic path reports only hit, miss, admission and eviction counts through GetCacheAdmissionStatistics

How far ahead should it read?

Adaptive read-ahead decides per document. With AdaptiveReadAheadEnabled set, every read the parser makes through the loaded document is classified as sequential or random, and the prefetch window follows a score. Two consecutive forward reads open the window to two blocks, four open it to four, six open it to eight. The window never exceeds MaxReadAheadBlocks, and it never exceeds the number of blocks that fit in MaxCacheBytes, so a small cache cannot be flooded by its own prefetch

A read that jumps backward, or lands too far past the previous read's end, drops the score below zero. The window closes, any prefetch heading somewhere else is cancelled, and SuppressedPrefetchCount goes up. Two forward reads later the window reopens at a single block. That lag is the point: one lucky contiguous read in the middle of a cross-reference chase does not restart speculation

SequentialReadToleranceBytes, 4,096 by default, defines "too far". A parser walking a content stream does not produce perfectly contiguous offsets; it skips a length field here, an inline image dictionary there. Reads landing within the tolerance of the previous end still count as forward. Set it too low and a normal forward scan is classified as random, so read-ahead never engages. Set it too high and genuine random access looks sequential, and you fetch megabytes nobody reads. The setter accepts any value from zero up to BlockSize and resets the score when it changes

Growth is gradual, collapse is immediate, and that asymmetry is deliberate. Over-fetching on a random workload burns real bandwidth, and on a metered transport real money; under-fetching on a sequential one costs a few extra round trips. Leave AdaptiveReadAheadEnabled on. Switched off, the wrapper prefetches one block after every read regardless of pattern, which is exactly the wrong behaviour while the parser is hopping between cross-reference sections

Ladder diagram of adaptive read-ahead in HotPDF growing one, two, four and eight blocks on sustained forward reads with an immediate collapse on out-of-order access
growth walks up one ladder rung at a time while collapse is immediate — the cheap mistake is preferred on metered transports

Classification is driven by the stream HotPDF reads from during a load. If your own code also pulls bytes through the wrapper, for example to hash a file or extract an attachment, call ObserveReadPattern with the offset and length after each read so the window reacts to that traffic too. When you already know which bytes will be wanted next, PrefetchRange starts a background fetch directly; IsPrefetchActive reports whether one is still running

Keeping hot blocks when the cache is full

Plain least-recently-used eviction has a known weakness. One long forward pass, say through a large embedded image, pushes out every block the parser keeps coming back to, including the cross-reference and Catalog blocks it will need again on the next page. THPDFCoalescingRandomAccessSource counts how often each block has been asked for, and once the budget is full a new block only enters the cache if it has been requested at least as often as the block it would replace. Otherwise the read goes straight to your source for exactly the bytes requested, and RejectionCount and FrequencyRejectionCount record it

That rule is on by default (the AdaptiveAdmission constructor argument). ConfigureCacheAdmission changes the byte budget, the per-entry ceiling, an optional entry count limit and the admission rule on a live wrapper; it cancels any running prefetch and trims the cache to the new limits on the spot

Cancellation that actually stops the transfer

Prefetch runs on a single background thread, and the wrapper cancels it as soon as it stops being worth finishing. A foreground read for bytes outside the range being prefetched cancels it, so the page the user asked for never waits behind speculative traffic. A random read cancels it. Destroying the wrapper, or calling CancelPrefetch or ClearCache, cancels it and waits for the thread to exit. Each of these sets the THPDFCancellationToken the prefetch thread passes into your ReadAtCancellable

Whether bytes actually stop flowing depends on your override. The default ReadAtCancellable on THPDFRandomAccessSource checks the token before and after a plain ReadAt, which is enough for a file share but lets a half-finished 256 KiB HTTP response run to completion. A client that reads the response body in chunks can check the token between chunks and abort:

function THttpRangeSource.ReadAt(Offset: Int64; var Buffer;
  Count: Longint): Longint;
begin
  Result := ReadAtCancellable(Offset, Buffer, Count, nil);
end;

function THttpRangeSource.ReadAtCancellable(Offset: Int64; var Buffer;
  Count: Longint; CancellationToken: THPDFCancellationToken): Longint;
var
  Status: Integer;
begin
  if CancellationToken <> nil then
    CancellationToken.ThrowIfCancellationRequested('http range read');
  // GetRange and its callback are your client's API: it sends
  // "Range: bytes=Offset-(Offset+Count-1)" and calls the callback between body chunks
  Result := FClient.GetRange(FUrl, Offset, Count, Buffer, Status,
    function: Boolean
    begin
      Result := (CancellationToken <> nil) and
        CancellationToken.IsCancellationRequested;
    end);
  // 200 instead of 206 means the server ignored Range and sent the whole file
  if Status <> 206 then
    raise EStreamError.CreateFmt('Range request not honored (HTTP %d)', [Status]);
  if CancellationToken <> nil then
    CancellationToken.ThrowIfCancellationRequested('http range read');
end;

The status check covers the trap most HTTP sources hit first. RFC 9110 §14 lets a server ignore a Range header and answer 200 with the full representation, and some CDN and proxy configurations do exactly that for certain files. A source that copies the first Count bytes of a 200 response hands the parser bytes from offset zero no matter which offset it asked for. Return values matter as well: the wrapper raises EStreamError if ReadAt reports a negative count or more bytes than requested, and it treats zero as end of data

The only non-nil token your source receives belongs to the prefetch thread. Parser reads during a load reach your ReadAtCancellable with a nil token, so stopping the load itself is a separate switch: assign a token to THotPDF.OperationCancellationToken, and the document load checks it as it goes. The same token model drives the queue described in background rendering with a request queue, so a viewer can cancel a load, its renders and its speculative network traffic from one close handler

Reading the range cache statistics

GetStatistics fills a THPDFRangeCacheStatistics record that keeps what your transport did apart from what the cache did. SourceReadCount and SourceBytesRead are physical traffic. CacheHitCount and CacheMissCount are logical traffic. SequentialReadCount and RandomReadCount show how the access pattern was classified, CurrentReadAheadBlocks and PeakReadAheadBlocks show how far the window opened, and the four prefetch counters show whether speculation paid off. CachedRangeCount, CachedBytes, EvictionCount and RejectionCount describe the cache itself

var
  S: THPDFRangeCacheStatistics;
begin
  Cached.GetStatistics(S);
  Log(Format('physical %d reads / %d bytes, hits %d, misses %d',
    [S.SourceReadCount, S.SourceBytesRead, S.CacheHitCount, S.CacheMissCount]));
  Log(Format('pattern: %d sequential, %d random, peak window %d blocks',
    [S.SequentialReadCount, S.RandomReadCount, S.PeakReadAheadBlocks]));
  Log(Format('prefetch: %d issued, %d completed, %d canceled, %d suppressed',
    [S.PrefetchRequestCount, S.PrefetchCompletedCount,
     S.PrefetchCancelledCount, S.SuppressedPrefetchCount]));
  Log(Format('cache: %d blocks / %d bytes, %d evicted, %d rejected',
    [S.CachedRangeCount, S.CachedBytes, S.EvictionCount, S.RejectionCount]));

  // Rejections piling up on a mostly sequential document: give it more room
  if S.RejectionCount > S.CacheHitCount then
    Cached.ConfigureCacheAdmission(16 * 1024 * 1024, Cached.BlockSize, 0);
end;

Three readings tell you what to change. Many cancelled prefetches next to a high random-read count mean the document is being walked out of order, so lower MaxReadAheadBlocks and stop paying for bandwidth you throw away. Many misses with the peak window stuck at 1 mean the tolerance is rejecting a pattern that is effectively sequential, so raise SequentialReadToleranceBytes. SourceBytesRead far above the file size means blocks are evicted before they are used again; raise MaxCacheBytes before touching anything else. The rejection threshold in the sample is our own starting heuristic, so tune it against your traffic

HotPDF panel mapping the three THPDFRangeCacheStatistics readings to the MaxReadAheadBlocks, SequentialReadToleranceBytes and MaxCacheBytes adjustments
each symptom reading names its fix, from lowering the window on random walks to widening the cache when blocks thrash

Linearised files change the arithmetic

If you control the producer, linearising the document changes the problem instead of tuning it. ISO 32000-1 Annex F places the first page's objects and a hint table at the front of the file, so a viewer can render page one from the opening bytes without touching the rest. HotPDF exposes that path through GetProgressiveLinearizedLoadInfo and ReadProgressiveLinearizedFirstPageSection, both of which take the same THPDFRandomAccessSource you would wrap for coalescing; the writing side is covered in generating linearised PDFs with hint tables

The two techniques compose. Coalescing makes any document tolerable over a slow link, including files from third parties you cannot re-save; linearisation makes the first page arrive fast on documents you produce yourself. Files on a local disk that are too large to hold in memory are a different problem with no round-trip latency to amortize, and the mapped-file and lazy-stream paths in the direct file API workflow fit them better

The random-access source classes, the coalescing wrapper, the cache admission policies and the progressive linearised loading calls all ship with HotPDF, a native Delphi and C++Builder PDF component with full source. Licensing and the complete API reference are on the HotPDF Delphi PDF component page