Clasa THPDFCoalescingRandomAccessSource

Wraps any THPDFRandomAccessSource with bounded range caching and cancellation-aware asynchronous prefetch

Declaration

constructor Create(
  ASource: THPDFRandomAccessSource;
  OwnsSource: Boolean = False;
  BlockSize: Integer = 262144;
  MaxCacheBytes: Int64 = 2097152;
  MaxEntryBytes: Int64 = 0;
  MaxCacheEntries: Integer = 0;
  AdaptiveAdmission: Boolean = True);

procedure PrefetchRange(Offset, Count: Int64);
procedure ObserveReadPattern(Offset: Int64; Count: Integer);
function TransferAt(Offset, Count: Int64;
  Destination: TStream): Int64;
procedure CancelPrefetch;
function IsPrefetchActive: Boolean;
procedure ClearCache;
procedure ConfigureCacheAdmission(MaxCacheBytes,
  MaxEntryBytes: Int64; MaxCacheEntries: Integer;
  AdaptiveAdmission: Boolean = True);
procedure GetStatistics(out Statistics: THPDFRangeCacheStatistics);

property BlockSize: Integer;
property MaxCacheBytes: Int64;
property MaxEntryBytes: Int64;
property MaxCacheEntries: Integer;
property AdaptiveAdmissionEnabled: Boolean;
property AsyncPrefetchEnabled: Boolean;
property AdaptiveReadAheadEnabled: Boolean;
property MaxReadAheadBlocks: Integer;
property SequentialReadToleranceBytes: Integer;

Range coalescing

O ratare de cache se extinde la un bloc aliniat care acoperă octeții solicitați, astfel încât citirile adiacente ale parser-ului partajează o singură cerere către stocarea de suport
Cache-ul impune limite independente de octeți totali, per intrare și opționale de număr de intrări, iar un interval supradimensionat ocolește reținerea
Admiterea adaptivă combină ordinea utilizării cel mai puțin recente cu o schiță limitată de frecvență cu îmbătrânire, astfel încât scanările reci citesc direct fără a înlocui intervalele reținute mai fierbinți
When a sparse source cannot provide an expanded block, the wrapper falls back to the exact available requested range
Accesul la sursă este serializat, astfel încât subclasele existente să nu trebuiască să devină sigure pentru fire

Asynchronous prefetch and cancellation

PrefetchRange schedules one background range and replaces an unrelated earlier request

A foreground cache miss outside the active range cancels the worker before acquiring the source lock, allowing a cooperative transport to yield promptly to the visible operation

Override THPDFRandomAccessSource.ReadAtCancellable to inspect the supplied THPDFCancellationToken during network or storage I/O; the inherited implementation checks cancellation immediately before and after ReadAt

Set AsyncPrefetchEnabled to False when transport policy forbids background access

Adaptive read-ahead

The parser stream calls ObserveReadPattern after each successful read; sustained forward reads grow the read-ahead window through 1, 2, 4, and 8 blocks, while a seek or backward access immediately suppresses speculative transport

SequentialReadToleranceBytes accepts small forward gaps as sequential access and defaults to 4096 bytes; MaxReadAheadBlocks limits the adaptive window from 1 through 32 blocks and defaults to 8

The effective window is also limited by MaxCacheBytes, so read-ahead cannot intentionally exceed the configured cache capacity; sequential confidence recovers gradually after a random jump

Set AdaptiveReadAheadEnabled to False for fixed one-block prefetch while retaining asynchronous transport

Statistics

TransferAt acquires retained cache-block references and writes them to the destination without allocating or filling an intermediate read buffer

THPDFRangeCacheStatistics reports backing-source read count and bytes, cache hits and misses, cache admissions, rejections and evictions, frequency admissions, rejections and aging, prefetch requests, completions and cancellations, sequential and random reads, suppressed prefetches, current and peak read-ahead blocks, direct transfer calls and bytes, plus current cached range count and bytes

Ownership

When OwnsSource is True, destroying the wrapper cancels and joins its worker, releases cached ranges, and frees the wrapped source