THotPDF Windowed Local File Mapping

Controls the bounded read-only memory mapping used by LoadFromFile for large local documents

Declarations

property LocalFileMappingThreshold: Int64;
property LocalFileMappingWindowSize: Integer;
property LocalFileMappingCacheWindows: Integer;
property LocalFileMappingAdaptiveGeometry: boolean;
property LastLoadUsedMemoryMapping: boolean;

function GetLastMappedFileStatistics(
  out Statistics: THPDFMappedFileStatistics): boolean;

Defaults

Setting	Default	Meaning
`LocalFileMappingThreshold`	8 MiB	Minimum source size that selects memory mapping; zero disables mapping
`LocalFileMappingWindowSize`	16 MiB	Bytes covered by one allocation-granularity-aligned view
`LocalFileMappingCacheWindows`	4	Maximum resident views retained by the LRU cache
`LocalFileMappingAdaptiveGeometry`	True	Redistribute the same mapped-byte limit for sustained sequential or random access

Statistics

THPDFMappedFileStatistics = record
  FileSize: Int64;
  ConfiguredWindowSize: Int64;
  ConfiguredCacheWindowCount: Integer;
  WindowSize: Int64;
  CacheWindowCount: Integer;
  MappedByteLimit: Int64;
  CurrentMappedBytes: Int64;
  PeakMappedBytes: Int64;
  GeometryChangeCount: Int64;
  SequentialReadCalls: Int64;
  RandomReadCalls: Int64;
  AdaptiveGeometry: Boolean;
  SequentialGeometryActive: Boolean;
  RandomGeometryActive: Boolean;
  ReadCalls: Int64;
  BytesRead: Int64;
  MapCount: Int64;
  CacheHits: Int64;
  FallbackReadCalls: Int64;
  FallbackBytes: Int64;
  DirectTransferCalls: Int64;
  DirectTransferBytes: Int64;
end;

GetLastMappedFileStatistics returns True only when the last LoadFromFile operation selected mapping

MapCount counts new views and CacheHits counts reads served by an existing view, allowing applications and benchmarks to tune window geometry against real access patterns

MappedByteLimit remains fixed while WindowSize and CacheWindowCount report the active geometry; peak mapped bytes, pattern counts, and mode flags make every adaptation observable

Advanced source types

THPDFMappedFileSource owns the shared file handle, mapping object, synchronized LRU windows, reference count, and positional fallback path

THPDFMappedFileStream exposes a bounded seekable slice over that source, while THPDFMappedFileWindow describes one cached internal view

Behaviour

Views are mapped only when a read reaches their range and are evicted by least-recently-used order
Eight sustained forward observations select larger sequential windows, while eight distant or backward observations select up to 16 smaller random-access windows
Adaptive geometry never exceeds the byte limit derived from the configured size and cache count
Reads that cross a window boundary are copied in bounded segments without creating a whole-file buffer
HPDFTransferStream writes mapped slices directly from each resident window and records direct transfer calls and bytes separately from parser reads
Parser streams and unmodified lazy PDF stream bodies share one file handle, mapping object, and thread-safe window cache
The source permits atomic rename or deletion while active, while its existing mapping retains a stable view of the opened bytes
Failure to create the mapping selects the original TFileStream implementation, while a later view-allocation failure switches the shared source to locked positional file reads
Window sizes below 64 KiB and cache counts outside 1 through 32 raise ERangeError