Sharded Loaded-Image Decode Cache

HotPDF combines independently locked cache metadata with exact per-key singleflight coordination

Parallel work

Sixteen metadata shards limit contention during lookup, admission, and eviction while expensive image decoding runs outside cache locks

Requests for different keys may decode concurrently and requests for the same key elect one owner whose completed result is shared with all waiting callers

Global bounds

ImageCacheMaxBytes, the maximum entry count, and the maximum per-entry size apply to the combined contents of all shards

Cross-shard trimming preserves exact configured limits and avoids selecting the just-inserted shard while another shard can satisfy the eviction request

Ownership and lifetime

AcquireLoadedImageStream and AcquireLoadedImageRegionAtResolution return immutable reference-counted handles, so warm hits and singleflight waiters share decoded storage without copying pixels

A handle remains valid after cache eviction, invalidation, and document destruction, while CreateBitmapCopy provides an isolated caller-owned bitmap when mutable pixels are required

The legacy cached decode methods retain their caller-owned TBitmap contract by materializing one copy from the handle

Telemetry

GetImageDecodeConcurrencyInfo exposes live and cumulative concurrency counters

The counters expose handle acquisitions, compatibility bitmap copies, and copied bytes in addition to parallel owner and singleflight activity

Related APIs

IHPDFDecodedBitmapHandle · AcquireLoadedImageStream · AcquireLoadedImageRegionAtResolution · THPDFImageDecodeConcurrencyInfo