기술 문서

Delphi에서 원격 PDF 스트리밍: HotPDF 레인지 코얼레싱

로컬 디스크에서 순식간에 열리는 PDF가 같은 바이트를 범위 요청에 답하는 HTTP 서버에서 받으면 첫 페이지를 보여 주는 데 몇 초가 걸릴 수 있습니다. 파일이 몇 메가바이트뿐이고 회선이 빨라도요. 대역폭이 문제가 아닙니다. 요청 개수가 문제고, 치료법은 흩어진 수백 개의 잘게 쪼갠 읽기를 수십 개의 캐시된 블록으로 바꾼 뒤, 접근 패턴이 순차로 유지되는 동안에만 앞서 읽는 것입니다

같은 PDF가 디스크에선 순식간이고 HTTP에선 왜 기어갈까?

PDF 파서는 파일을 앞에서 뒤로 읽지 않고 탐색합니다. ISO 32000-1 §7.5의 구조는 입구를 끝에 둡니다. 파서는 마지막 킬로바이트로 seek해 startxref를 찾고, 크로스 레퍼런스 테이블로 되뛰고, 트레일러 딕셔너리를 resolve하고, 참조를 따라 Catalog로, 페이지 트리 루트로, 페이지 노드로, 그 페이지의 리소스 딕셔너리로 갑니다. 각 홉은 서로 다른 오프셋에서 수십 바이트를 읽고, 증분 업데이트된 파일은 /Prev 사슬을 통해 리비전마다 그 순회를 반복합니다

로컬 파일에서 이 패턴은 거저나 다름없습니다. 운영체제가 이미 주변 4 KiB 페이지를 파일 캐시에 쥐고 두 번째 읽기는 메모리 복사 비용이니까요. 네트워크 전송에는 그런 지역성이 없습니다. 모든 읽기가 자기 지연을 달고 온 요청이 되고 계산은 잔인합니다. 왕복 40 ms에서 잘게 쪼갠 읽기 300개는 회선이 대부분 놀고 있는 동안 기다림 12초로 합산됩니다. 덜 읽는 것은 선택지가 아닙니다. 파서는 자기가 요청한 정확한 바이트가 필요하니까요. 바뀔 수 있는 것은 각 물리 요청이 얼마나 되가져오느냐입니다

전송 계층을 THPDFCoalescingRandomAccessSource로 감싸기

HotPDF는 THPDFRandomAccessSource를 내려받는 어떤 클래스로든 문서를 적재하고, THPDFCoalescingRandomAccessSource는 그 클래스와 파서 사이에 앉습니다. 모든 읽기는 정렬된 블록으로 올림되고 그 블록은 메모리에 유지됩니다. BlockSize 기본값은 262,144바이트, MaxCacheBytes는 2,097,152라 여덟 블록이 상주하고 예산이 차면 가장 오래 안 쓴 하나가 나갑니다. 트레일러 키를 찾는 파서의 40바이트 조회는 주변 256 KiB를 끌어들이고, 그 이웃에서 이어지는 열두 읽기(크로스 레퍼런스 항목, Catalog, 페이지 트리 키)는 메모리에서 나옵니다

여러분 클래스는 얇게 유지됩니다. 필수 메서드는 GetSize와 ReadAt 둘입니다. HTTP 클라이언트가 진행 중 요청을 중단할 수 있으면 ReadAtCancellable을, 소스가 아직 진행 중인 다운로드라면 IsRangeAvailable을 오버라이드하세요. 래퍼는 매 fetch 전에 그 질문을 합니다. 블록 전체가 아직 없으면 요청된 바이트만으로 재시도하고, 그것마저 없으면 읽기는 막히는 대신 짧게 돌아옵니다

HotPDF 블록 코얼레싱 다이어그램: 흩어진 파서 seek이 캐시된 256 KiB 블록으로 올림되어 같은 이웃의 이후 읽기가 메모리에서 제공됩니다
읽기는 기본으로 캐시된 256 KiB 블록으로 올림되므로 파서의 흩어짐은 이웃당 네트워크 전송 한 번의 비용이 됩니다
type
  // TMyHttpClient는 여러분 자체 HTTP 클라이언트 클래스를 대변합니다
  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: 래퍼가 Raw를 해제합니다. 256 KiB 블록, 8 MiB 예산
  Cached := THPDFCoalescingRandomAccessSource.Create(Raw, True, 262144, 8388608);
  Cached.MaxReadAheadBlocks := 8;   // 유효 범위 1..32
  Pdf := THotPDF.Create(nil);
  try
    // 다시 OwnsSource=True: Pdf가 Cached를 해제하고 Cached가 Raw를 해제합니다
    if Pdf.LoadFromRandomAccessSource(Cached, True) > 0 then
      RenderFirstPage(Pdf);   // 자체 코드
  finally
    Pdf.Free;
  end;
end;

비동기 프리페치와 적응형 리드어헤드는 래퍼가 생성되자마자 둘 다 켜져 있으므로 샘플은 창 천장만 만집니다. 생성자는 인수를 미리 검증합니다. BlockSize는 4,096에서 16,777,216바이트 사이여야 하고 MaxCacheBytes는 최소한 블록 하나를 담아야 하며, 아니면 바이트 하나 움직이기 전에 ERangeError를 받습니다

명시적 래퍼는 엄밀히 필수가 아닙니다. LoadFromRandomAccessSource에 맨 소스를 넘기면 HotPDF가 대신 감싸 줍니다. clkRawCompressed 계층의 GetCacheAdmissionPolicy와 SetCacheAdmissionPolicy로 읽고 바꿀 수 있는 raw 캐시 정책을 써서요. 항목 여덟 개, 총 2 MiB, 항목당 256 KiB입니다. 자체 THPDFCoalescingRandomAccessSource를 넘기면 설정된 그대로 쓰입니다. 네트워크를 건너는 무엇이든 래퍼를 직접 만드세요. 리드어헤드 손잡이와 온전한 통계 레코드를 얻는 반면 자동 경로는 GetCacheAdmissionStatistics로 hit, miss, 승인, 퇴출 개수만 보고합니다

얼마나 앞서 읽어야 할까?

적응형 리드어헤드는 문서별로 판단합니다. AdaptiveReadAheadEnabled가 설정되면 적재된 문서를 거쳐 파서가 내는 모든 읽기가 순차나 무작위로 분류되고 프리페치 창은 점수를 따라갑니다. 연속된 순방향 읽기 두 개가 창을 두 블록으로 열고, 넷은 넷으로, 여섯은 여덟으로 엽니다. 창은 MaxReadAheadBlocks를 넘지 않고 MaxCacheBytes에 들어가는 블록 수도 넘지 않으므로 작은 캐시가 자기 프리페치에 잠기지 않습니다

뒤로 뛰는 읽기나 이전 읽기 끝에서 너무 멀리 착지하는 읽기는 점수를 0 아래로 떨어뜨립니다. 창이 닫히고 딴 곳으로 향하던 프리페치는 취소되며 SuppressedPrefetchCount가 오릅니다. 순방향 읽기 두 번 뒤에 창은 한 블록으로 다시 열립니다. 그 지연이 요점입니다. 크로스 레퍼런스 추적 한가운데의 우연한 연속 읽기 하나가 추측을 재시작하지 않습니다

SequentialReadToleranceBytes, 기본 4,096이 '너무 멀다'를 정의합니다. 콘텐츠 스트림을 걷는 파서는 완벽히 연속적인 오프셋을 내지 않습니다. 여기서 길이 필드를 하나 건너뛰고 저기서 인라인 이미지 딕셔너리를 건너뛰죠. 이전 끝의 허용 오차 안에 착지하는 읽기는 여전히 순방향으로 셉니다. 너무 낮게 잡으면 정상적인 순방향 스캔이 무작위로 분류돼 리드어헤드가 아예 발화하지 않고, 너무 높게 잡으면 진짜 무작위 접근이 순차로 보여 아무도 읽지 않을 메가바이트를 가져옵니다. 세터는 0부터 BlockSize까지 어떤 값이든 받고 바뀔 때 점수를 리셋합니다

성장은 완만하고 무너짐은 즉각이며 그 비대칭은 의도된 것입니다. 무작위 작업 부하에서의 과잉 가져오기는 진짜 대역폭을 태우고 종량제 전송에서는 진짜 돈을 태웁니다. 순차 작업 부하에서의 과소 가져오기는 왕복 몇 번의 비용입니다. AdaptiveReadAheadEnabled는 켜 두세요. 꺼두면 래퍼는 패턴과 무관하게 매 읽기 뒤에 블록 하나를 프리페치하는데, 파서가 크로스 레퍼런스 섹션들 사이를 뛰어 다니는 동안에는 정확히 틀린 동작입니다

지속되는 순방향 읽기에서 한 칸, 두 칸, 네 칸, 여덟 칸 블록으로 자라며 순서가 어긋난 접근에는 즉시 무너지는 HotPDF 적응형 리드어헤드의 사다리 다이어그램
성장은 사다리 한 칸씩 걸어 올라가고 무너짐은 즉각입니다. 종량제 전송에서는 값싼 실수 쪽이 선호됩니다

분류는 적재 동안 HotPDF가 읽는 스트림이 끕니다. 여러분 코드도 래퍼를 통해 바이트를 끌어온다면, 이를 테면 파일을 해시하거나 첨부를 추출한다면, 매 읽기 뒤에 오프셋과 길이로 ObserveReadPattern을 불러 창이 그 트래픽에도 반응하게 하세요. 다음에 어떤 바이트가 필요한지 이미 안다면 PrefetchRange가 백그라운드 fetch를 곧장 시작하고, IsPrefetchActive가 아직 도는지 보고합니다

캐시가 가득 차도 뜨거운 블록은 지킨다

평범한 LRU 퇴출에는 알려진 약점이 있습니다. 큰 임베디드 이미지 통과 같은 긴 순방향 패스 하나가 파서가 계속 돌아오는 모든 블록을 밀어 내는데, 다음 페이지에서 다시 필요할 크로스 레퍼런스와 Catalog 블록도 포함입니다. THPDFCoalescingRandomAccessSource는 각 블록이 몇 번 요청됐는지 세고, 예산이 차면 새 블록은 자신이 대체할 블록과 같은 횟수 이상 요청된 적이 있을 때만 캐시에 들어옵니다. 아니면 읽기는 요청된 바이트만큼 여러분 소스로 곧장 가고 RejectionCount와 FrequencyRejectionCount가 이를 기록합니다

그 규칙은 기본으로 켜져 있습니다(AdaptiveAdmission 생성자 인수). ConfigureCacheAdmission은 살아 있는 래퍼에서 바이트 예산과 항목당 천장, 선택적 항목 수 한도, 승인 규칙을 바꾸고 실행 중인 프리페치를 취소하며 캐시를 그 자리에서 새 한도로 다듬습니다

전송을 실제로 멈추는 취소

프리페치는 단일 백그라운드 스레드에서 돌고 래퍼는 끝마치는 가치가 없어지는 즉시 취소합니다. 프리페치 중인 범위 밖 바이트의 포그라운드 읽기는 그것을 취소하므로 사용자가 요청한 페이지가 추측 트래픽 뒤에서 기다리지 않습니다. 무작위 읽기는 취소합니다. 래퍼 파괴나 CancelPrefetch, ClearCache 호출은 취소하고 스레드 종료를 기다립니다. 이들 각각은 프리페치 스레드가 여러분의 ReadAtCancellable에 넘기는 THPDFCancellationToken을 설정합니다

바이트가 실제로 멈추는지는 여러분의 오버라이드가 정합니다. THPDFRandomAccessSource의 기본 ReadAtCancellable은 평범한 ReadAt 전후로 토큰을 검사하는데, 파일 공유에는 충분하지만 반쯤 끝난 256 KiB HTTP 응답이 끝까지 달리게 둡니다. 응답 본문을 청크로 읽는 클라이언트는 청크 사이에 토큰을 검사하고 중단할 수 있습니다:

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와 그 콜백은 클라이언트의 API입니다. 이는
  // "Range: bytes=Offset-(Offset+Count-1)"를 보내고 본문 청크 사이에 콜백을 부릅니다
  Result := FClient.GetRange(FUrl, Offset, Count, Buffer, Status,
    function: Boolean
    begin
      Result := (CancellationToken <> nil) and
        CancellationToken.IsCancellationRequested;
    end);
  // 206 대신 200이면 서버가 Range를 무시하고 파일 전체를 보낸 뜻입니다
  if Status <> 206 then
    raise EStreamError.CreateFmt('Range request not honored (HTTP %d)', [Status]);
  if CancellationToken <> nil then
    CancellationToken.ThrowIfCancellationRequested('http range read');
end;

상태 검사는 대부분의 HTTP 소스가 처음 부딪히는 함정을 커버합니다. RFC 9110 §14는 서버가 Range 헤더를 무시하고 전체 표현과 함께 200으로 답하는 것을 허용하고, 어떤 CDN과 프록시 구성은 특정 파일에서 정확히 그렇게 합니다. 200 응답의 첫 Count바이트를 복사하는 소스는 어떤 오프셋을 요청했든 오프셋 0의 바이트를 파서에게 넘깁니다. 반환값도 중요합니다. 래퍼는 ReadAt이 음수 개수나 요청보다 많은 바이트를 보고하면 EStreamError를 발생시키고 0은 데이터 끝으로 취급합니다

여러분 소스가 받는 nil 아닌 유일한 토큰은 프리페치 스레드 소속입니다. 적재 동안의 파서 읽기는 nil 토큰으로 ReadAtCancellable에 닿으므로 적재 자체를 멈추는 건 별도 스위치입니다. THotPDF.OperationCancellationToken에 토큰을 할당하면 문서 적재가 진행하며 검사합니다. 같은 토큰 모델이 요청 큐를 이용한 백그라운드 렌더링에서 서술하는 큐를 끕니다. 뷰어가 하나의 닫기 핸들러에서 적재와 렌더링, 추측 네트워크 트래픽을 취소할 수 있는 이유입니다

범위 캐시 통계 읽기

GetStatistics는 THPDFRangeCacheStatistics 레코드를 채우는데, 전송 계층이 한 일을 캐시가 한 일과 갈라 놓습니다. SourceReadCount와 SourceBytesRead는 물리 트래픽입니다. CacheHitCount와 CacheMissCount는 논리 트래픽입니다. SequentialReadCount와 RandomReadCount는 접근 패턴이 어떻게 분류됐는지를, CurrentReadAheadBlocks와 PeakReadAheadBlocks는 창이 얼마나 열렸는지를 보여 주고 네 프리페치 카운터는 추측이 값을 했는지 알려 줍니다. CachedRangeCount, CachedBytes, EvictionCount, RejectionCount는 캐시 자체를 서술합니다

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]));

  // 대체로 순차적인 문서에서 쌓이는 거부. 더 방을 주세요
  if S.RejectionCount > S.CacheHitCount then
    Cached.ConfigureCacheAdmission(16 * 1024 * 1024, Cached.BlockSize, 0);
end;

세 가지 판독값이 무엇을 바꿀지 알려 줍니다. 높은 무작위 읽기 개수 곁의 많은 취소된 프리페치는 문서가 순서를 어기며 걷히고 있다는 뜻이므로 MaxReadAheadBlocks를 낮추고 버릴 대역폭 값을 치르기를 멈추세요. 최고 창이 1에 붙은 채 많은 miss는 사실상 순차인 패턴을 허용 오차가 거부한다는 뜻이므로 SequentialReadToleranceBytes를 올리세요. SourceBytesRead가 파일 크기를 한참 넘으면 블록이 다시 쓰이기 전에 퇴출되고 있다는 뜻이므로, 다른 무엇을 만지기 전에 MaxCacheBytes를 올리세요. 샘플의 거부 임계값은 우리 자체의 출발 휴리스틱이므로 여러분 트래픽에 맞춰 조율하세요

세 가지 THPDFRangeCacheStatistics 판독값을 MaxReadAheadBlocks, SequentialReadToleranceBytes, MaxCacheBytes 조정에 연결하는 HotPDF 패널
각 증상 판독값은 자기 처방을 이름 댑니다. 무작위 순회에서 창을 낮추는 것부터 블록이 흔들릴 때 캐시를 넓히는 것까지입니다

선형화된 파일은 계산 자체를 바꾼다

생산자를 통제한다면 문서를 선형화하는 편이 문제를 조율하는 대신 바꿔 버립니다. ISO 32000-1 부록 F는 첫 페이지의 객체와 힌트 테이블을 파일 앞쪽에 놓아, 뷰어가 나머지를 만지지 않고 여는 바이트들로 1페이지를 렌더링할 수 있습니다. HotPDF는 GetProgressiveLinearizedLoadInfo와 ReadProgressiveLinearizedFirstPageSection으로 그 경로를 노출하는데 둘 다 코얼레싱으로 감쌀 바로 그 THPDFRandomAccessSource를 받습니다. 쓰는 쪽은 힌트 테이블과 함께 선형화된 PDF 생성하기에서 다룹니다

두 기법은 겹쳐 씁니다. 코얼레싱은 다시 저장할 수 없는 서드파티 파일을 포함해 어떤 문서든 느린 링크 위에서 견딜 만하게 만들고, 선형화는 여러분이 직접 만든 문서에서 첫 페이지를 빨리 도착하게 합니다. 메모리에 담기엔 너무 큰 로컬 디스크의 파일은 왕복 지연을 상각할 것이 없는 다른 문제이고, 다이렉트 파일 API 워크플로의 매핑 파일과 레이지 스트림 경로가 더 잘 맞습니다

무작위 접근 소스 클래스와 코얼레싱 래퍼, 캐시 승인 정책, 점진 선형화 적재 호출은 모두 전체 소스를 갖춘 네이티브 Delphi, C++Builder PDF 컴포넌트인 HotPDF에 실려 나갑니다. 라이선싱과 전체 API 레퍼런스는 HotPDF Delphi PDF 컴포넌트 페이지에 있습니다