Cache Infrastructure

HotPDF는 상한이 있는 메모리 캐싱과 재사용 폰트 subset, 렌더링 페이지용 영속 캐시를 제공합니다

가중치 메모리 캐시

HPDFCache의 THPDFWeightedCache는 TObject 값을 소유하고 AnsiString으로 인덱싱하며, 합산 가중치가 MaxBytes에 맞을 때까지 가장 오래된 값을 내보냅니다

Get과 TryGet은 적중한 항목을 가장 최근에 사용한 항목으로 올리고 요청 통계를 갱신합니다
Peek과 ContainsKey는 최근 사용 순서나 요청 통계를 바꾸지 않고 항목을 확인합니다
Put은 소유권을 가져가고 기존 키를 그 자리에서 교체하며, 가중치만 바뀐 같은 객체도 안전하게 다시 받습니다
Remove는 항목을 해제하고, Extract는 소유권을 호출자에게 넘깁니다
MaxBytes를 줄이면 항목이 즉시 내보내지고, TrimToBudget은 같은 수렴 operation을 명시적으로 노출합니다
Hits, Misses, HitRate, Evictions, Rejections, Replacements가 캐시 동작을 노출하고, ResetStatistics는 새 측정 구간을 시작합니다
슬롯 용량은 기하급수적으로 늘고, live 항목은 상수 시간 최근 사용 순서로 연결된 채 유지됩니다

Content keys

function HPDFCacheKeyOfBytes(const Bytes: TBytes): AnsiString;
function HPDFCacheKeyOfStream(Stream: TStream): AnsiString;

두 함수는 같은 콘텐츠에 대해 같은 소문자 SHA-256 16진수 키를 반환합니다

HPDFCacheKeyOfStream은 두 번째 전체 크기 바이트 배열을 할당하지 않고 해싱하며, seekable stream을 위치 0부터 읽고 원래 위치를 복원합니다

로드된 폰트 디코더 캐시

각 THotPDF 인스턴스는 성공적으로 파싱된 로드 폰트 디코더를 문서 범위 가중치 LRU 캐시에 유지합니다

기본 예산은 32MiB에 하드 한도 128항목이고, 0바이트 예산은 보존을 끕니다
공유 indirect 폰트 딕셔너리는 페이지가 다른 리소스 이름을 쓰더라도 페이지에 걸쳐 하나의 파싱 코어를 재사용합니다
텍스트 추출, SVG 내보내기, 로드된 텍스트 교체, 명시적 디코더 요청이 같은 캐시를 공유합니다
GetLoadedFontDecoder는 관리 배열을 깊이 복사해 호출자가 캐시된 매핑이나 폭을 바꾸지 못하게 합니다
문서 다시 로드, 그래프 변경, 페이지 무효화, JSON Patch, 모든 CMapResourcePath 할당이 보유 디코더를 지웁니다
디코더 획득은 한 폰트의 중복 파싱을 피하려고 문서별로 직렬화되지만, 이 잠금이 동시 문서 변경을 안전하게 만들지는 않습니다
GetLoadedFontDecoderCacheInfo는 항목, 추정 바이트, 예산, 히트, 미스, 파싱, eviction, 무효화를 노출합니다

샤딩된 로드 이미지 디코딩 캐시

각 THotPDF 인스턴스는 16개 독립 잠금 metadata shard로 로드 이미지 디코딩 재사용을 조정합니다

캐시 조회와 승인은 선택된 shard만 잠그고, 비용이 큰 filter·이미지 디코딩은 캐시 잠금 밖에서 실행됩니다
키별 정확한 singleflight가 owner 디코딩 하나를 선출해 중복 호출자가 같은 완료 결과를 기다리게 합니다
설정된 ImageCacheMaxBytes, 항목 수 한도, 항목별 한도는 모든 shard에 걸쳐 전역으로 유지됩니다
decoded-image 항목은 eviction을 넘어 살아남는 불변 참조 카운트 handle을 담아 렌더러가 TBitmap 사본을 만들지 않고 웜 히트를 그릴 수 있게 합니다
완성된 이미지는 호출자 소유 TBitmap 인스턴스로 복사되어 호출자가 보유 캐시 픽셀을 바꾸지 못합니다
문서 다시 로드와 이미지 캐시 무효화는 완료 항목을 지우고, 활성 flight 객체는 자체 참조 카운트 수명을 유지합니다
GetImageDecodeConcurrencyInfo는 활성 flight, 활성/피크 owner 디코딩, 대기, 완료, 실패를 보고합니다

ICC transform 캐시

HPDFICC는 스레드 안전 64MiB 가중치 LRU 캐시로 완전한 source→sRGB transform을 공유하며, 설정 시 proof/output 프로파일도 포함합니다

SHA-256 키는 전체 source, proof, output 프로파일 내용과 실효 rendering intent, black-point compensation 설정을 포괄합니다
HPDFGetICCTransformCacheInfo는 히트, 미스, eviction, 거부, 항목 수, 현재/최대 바이트를 보고합니다
HPDFSetICCTransformCacheMaxBytes는 새 프로세스 전역 예산을 즉시 적용하고 필요하면 가장 오래된 transform을 내보냅니다
HPDFClearICCTransformCache는 호출자가 이미 보유한 transform 인터페이스를 무효화하지 않고 보유 transform을 해제하고 요청 통계를 초기화합니다

영속 폰트 subset 캐시

EnableFontSubsetting이 활성인 동안 재사용 가능한 TrueType/OpenType subset 결과를 켜려면 THotPDF.FontSubsetCacheFolder를 설정합니다

키는 원본 폰트 바이트, 정확한 사용 glyph bitmap, compact/sparse 모드, 캐시 스키마 버전을 포괄합니다
일반 GDI 폰트 저장소 경로와 등록된 Unicode 폰트 finalizer가 같은 캐시를 재사용합니다
컴팩트 PDF/A 항목은 CIDToGIDMap에 필요한 이전→새 GID 맵과 새 glyph 수를 보존합니다
항목은 사용 전에 검증되고, 손상된 항목은 제거되며, 교체는 같은 디렉터리의 원자적 이동으로 이뤄집니다
FontSubsetCacheMaxBytes는 즉시 적용되며 무관한 폴더를 훑지 않고 가장 오래 접근되지 않은 exact 캐시 파일을 내보냅니다
GetFontSubsetCacheInfo는 히트, 미스, 쓰기, eviction, 손상, 거부, 쓰기 실패, 바이트, 파일을 보고합니다
ClearFontSubsetCache는 설정된 폴더에서 폰트 subset 항목과 버려진 임시 항목만 제거합니다

PDF.EnableFontSubsetting := True;
PDF.FontSubsetCacheFolder := 'C:\ProgramData\MyApp\HotPDF\FontSubsets';
PDF.FontSubsetCacheMaxBytes := 256 * 1024 * 1024;

영속 렌더링 페이지 캐시

THotPDF.RenderCacheFolder를 설정하면, 메모리 내 렌더링 페이지 캐시 다음 단계로 사용되는 디스크 티어가 활성화됩니다

페이지 파일은 문서 콘텐츠, 0 기반 페이지 인덱스, DPI, 실효 optional-content 표시, 컬러 intent, 폴백 policy로 키가 정해집니다
layer와 컬러 intent 변경은 캐시 bitmap을 모두 버리는 대신 재사용 가능한 상태 변형을 선택합니다
PNG와 인덱스 갱신은 원자적이며, 회수 중에 버려진 임시 파일을 제거합니다
페이지 읽기는 페이지 수준 recency를 새로 고치고, 문서 수·페이지 수·바이트 한도는 가장 오래된 데이터를 내보냅니다
설정 한도를 줄이면 이후 쓰기를 기다리지 않고 즉시 수렴합니다
손상된 PNG 파일, 오래되거나 중복된 인덱스 행, 사라진 폴더, 인덱스에 없는 캐시 폴더는 자동 복구됩니다
잘못된 문서 키와 좌표는 파일시스템 접근 전에 거부됩니다
연결된 문서 폴더는 복구, 읽기, 쓰기, 무효화, eviction 중에 건너뛰며, 링크와 그 외부 대상 파일은 보존됩니다

소유권

THPDFWeightedCache는 Put에 전달된 값을 소유하며, Extract로 반환한 값은 예외입니다
THPDFDiskPageCache.Lookup은 새로 할당된 호출자 소유 bitmap을 반환합니다
THPDFDiskPageCache.Store에 전달된 bitmap 값은 계속 호출자가 소유합니다