Техническая статья

HotPDF: потоковая загрузка PDF по сети в Delphi

PDF, мгновенно открывающийся с локального диска, может показывать первую страницу несколько секунд, когда те же байты приезжают с HTTP-сервера, отвечающего на range-запросы, — хотя файл всего несколько мегабайтов и канал быстрый. Полоса не проблема. Проблема — счётчик запросов, а лекарство — превратить сотни крошечных разрозненных чтений в несколько десятков кэшированных блоков и читать вперёд, только пока паттерн доступа остаётся последовательным

Почему один и тот же PDF загружается мгновенно локально и еле ползёт по сети?

Парсер PDF не читает файл от начала до конца. Он по нему перемещается. Структура из ISO 32000-1 §7.5 ставит точку входа в конец: парсер прыгает в последний килобайт за startxref, скачет назад к таблице перекрёстных ссылок, разрешает словарь trailer, следует ссылкой к каталогу, затем к корню дерева страниц, затем к узлу страницы, затем к словарю ресурсов той страницы. Каждый прыжок читает десятки байтов с другого смещения, а инкрементно обновлённый файл повторяет прогулку по разу на ревизию через цепочку /Prev

На локальном файле такой паттерн почти бесплатен: операционная система уже держит окружающие 4 КиБ страницы в файловом кэше, и второе чтение стоит копирования памяти. У сетевого транспорта такой локальности нет. Каждое чтение становится запросом с собственной задержкой, и арифметика беспощадна: при 40 мс на круг 300 мелких чтений складываются в двенадцать секунд ожидания при проводах, по большей части простаивающих. Читать меньше — не вариант: парсеру нужны ровно те байты, что он просит. Может измениться то, сколько каждый физический запрос привозит обратно

Оборачиваем ваш транспорт в THPDFCoalescingRandomAccessSource

HotPDF грузит документы из любого класса, наследующего THPDFRandomAccessSource, и THPDFCoalescingRandomAccessSource садится между тем классом и парсером. Каждое чтение округляется вверх до выровненного блока, и блок остаётся в памяти. BlockSize по умолчанию 262 144 байта, MaxCacheBytes — 2 097 152, так что восемь блоков остаются резидентными, а при полном бюджете уходит наименее недавно использованный. 40-байтовый поиск ключа trailer парсером подтягивает окружающие его 256 КиБ, и следующая дюжина чтений в той окрестности (записи перекрёстных ссылок, каталог, ключи дерева страниц) выходит из памяти

Ваш собственный класс остаётся тонким. Обязательны два метода: GetSize и ReadAt. Переопределите ReadAtCancellable, если ваш HTTP-клиент умеет рвать запрос в полёте, и IsRangeAvailable, когда источник — ещё идущая закачка. Обёртка задаёт тот вопрос перед каждой выборкой: если целого блока ещё нет, она повторяет попытку ровно с запрошенными байтами, а если нет и их — чтение возвращается коротким вместо блокировки

Диаграмма слияния блоков HotPDF: разрозненные парсерные позиционирования округляются вверх в кэшированные блоки 256 KiB, так что последующие чтения в том же соседстве обслуживаются из памяти
чтения по умолчанию округляются вверх до кэшированных блоков 256 КиБ, так что разброс парсера стоит одну сетевую передачу на окрестность
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 КиБ, бюджет 8 МиБ
  Cached := THPDFCoalescingRandomAccessSource.Create(Raw, True, 262144, 8388608);
  Cached.MaxReadAheadBlocks := 8;   // допустимый диапазон 1..32
  Pdf := THotPDF.Create(nil);
  try
    // OwnsSource=True снова: Pdf освобождает 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 обернёт его за вас, пользуясь политикой сырого кэша, которую можно прочесть и поменять через GetCacheAdmissionPolicy и SetCacheAdmissionPolicy для слоя clkRawCompressed: восемь записей, 2 МиБ в сумме, 256 КиБ на запись. Передадите собственный THPDFCoalescingRandomAccessSource — он будет использован ровно в той конфигурации, что задана. Для всего, что пересекает сеть, собирайте обёртку сами: вы получаете ручки упреждающего чтения и полную запись статистики, тогда как автоматический путь репортит лишь счётчики попаданий, промахов, допусков и вытеснений через GetCacheAdmissionStatistics

Насколько далеко вперёд стоит читать?

Адаптивное упреждающее чтение решает поминутно для каждого документа. При взведённом AdaptiveReadAheadEnabled каждое чтение, которое парсер делает через загруженный документ, классифицируется как последовательное или случайное, а окно предзагрузки следует за счётом. Два подряд идущих чтения вперёд открывают окно на два блока, четыре — на четыре, шесть — на восемь. Окно никогда не превышает MaxReadAheadBlocks и никогда — числа блоков, влезающих в MaxCacheBytes, так что маленький кэш нельзя утопить его же предзагрузкой

Чтение, прыгающее назад или приземляющееся слишком далеко за концом предыдущего, роняет счёт ниже нуля. Окно закрывается, любая предзагрузка, идущая в другую сторону, отменяется, а SuppressedPrefetchCount растёт. Два последовательных чтения спустя окно переоткрывается на одном блоке. Эта задержка и есть суть: одно удачное смежное чтение посреди охоты за перекрёстными ссылками не перезапускает спекуляцию

SequentialReadToleranceBytes, по умолчанию 4 096, определяет «слишком далеко». Парсер, идущий по потоку содержимого, не выдаёт идеально смежных смещений; он перескакивает поле длины тут, словарь встроенного изображения там. Чтения, приземлившиеся в пределах допуска от предыдущего конца, всё ещё считаются идущими вперёд. Зададите слишком низко — нормальный последовательный скан классифицируется как случайный, и упреждающее чтение так и не включится. Слишком высоко — настоящий случайный доступ выглядит последовательным, и вы возите мегабайты, которые никто не читает. Сеттер принимает любое значение от нуля до BlockSize и сбрасывает счёт при изменении

Рост постепенный, схлопывание мгновенное, и эта асимметрия намеренная. Перезагрузка на случайной нагрузке сжигает реальную полосу, а на тарифицируемом транспорте — реальные деньги; недозагрузка на последовательной стоит пары лишних кругов. Держите AdaptiveReadAheadEnabled включённым. Выключенный, он предзагружает один блок после каждого чтения вне зависимости от паттерна — ровно неверное поведение, пока парсер скачет между секциями перекрёстных ссылок

Диаграмма-лестница адаптивного read-ahead в HotPDF: рост на один, два, четыре и восемь блоков при устойчивых чтениях вперёд с немедленным схлопыванием при неупорядоченном доступе
рост поднимается по лестнице по ступеньке за раз, тогда как схлопывание мгновенно — дешёвая ошибка предпочтительна на тарифицируемых каналах

Классификация ведётся по тому stream, из которого HotPDF читает во время загрузки. Если ваш собственный код тоже тянет байты через обёртку, скажем для хеширования файла или извлечения вложения, зовите после каждого чтения ObserveReadPattern со смещением и длиной, чтобы окно реагировало и на тот трафик. Когда вы заранее знаете, какие байты понадобятся следующими, PrefetchRange стартует фоновую выборку напрямую; IsPrefetchActive репортит, бежит ли ещё одна

Держим горячие блоки, когда кэш полон

У простого вытеснения по давности использования есть известная слабость. Один длинный проход вперёд, скажем через крупное встроенное изображение, выталкивает каждый блок, к которому парсер возвращается снова и снова, включая блоки перекрёстных ссылок и каталога, понадобящиеся на следующей странице. THPDFCoalescingRandomAccessSource считает, сколько раз каждый блок спрашивали, и при полном бюджете новый блок входит в кэш, только если его запрашивали не реже блока, который он заменил бы. Иначе чтение идёт прямиком в ваш источник ровно за запрошенными байтами, а RejectionCount и FrequencyRejectionCount это записывают

То правило включено по умолчанию (аргумент конструктора AdaptiveAdmission). ConfigureCacheAdmission меняет байтовый бюджет, потолок на запись, опциональный предел числа записей и правило допуска на живой обёртке; она отменяет любую идущую предзагрузку и тут же подрезает кэш под новые лимиты

Отмена, которая действительно останавливает передачу

Предзагрузка бежит в одиночном фоновом потоке, и обёртка отменяет её, как только та перестаёт стоить завершения. Приоритетное чтение байтов вне диапазона предзагрузки её отменяет, так что страница, которую попросил пользователь, никогда не ждёт за спекулятивным трафиком. Случайное чтение её отменяет. Разрушение обёртки, вызов CancelPrefetch или ClearCache отменяет её и ждёт выхода потока. Каждое из этих действий взводит THPDFCancellationToken, который поток предзагрузки передаёт в ваш ReadAtCancellable

Остановятся ли байты на деле, зависит от вашего переопределения. Дефолтный ReadAtCancellable на THPDFRandomAccessSource проверяет токен до и после обычного ReadAt, чего хватает для файлового ресурса, но позволяет наполовину приехавшему HTTP-ответу на 256 КиБ доработать до конца. Клиент, читающий тело ответа кусками, может проверять токен между кусками и рвать связь:

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);
  // 200 вместо 206 значит, что сервер проигнорировал 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 и прокси делают ровно это с определёнными файлами. Источник, копирующий первые Count байтов 200-ответа, сунет парсеру байты со смещения ноль, каким бы смещением его ни спросили. Важны и возвращаемые значения: обёртка бросает EStreamError, если ReadAt отчитался об отрицательном счётчике или большем числе байтов, чем просили, а ноль трактует как конец данных

Единственный не-nil токен, который получает ваш источник, принадлежит потоку предзагрузки. Парсерные чтения во время загрузки приходят в ваш ReadAtCancellable с nil-токеном, так что остановка самой загрузки — отдельный выключатель: назначьте токен в 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, означает, что допуск отвергает паттерн, фактически последовательный, — поднимите SequentialReadToleranceBytes. SourceBytesRead, сильно превышающий размер файла, означает, что блоки вытесняются прежде, чем их используют снова; поднимите MaxCacheBytes, прежде чем трогать что-либо ещё. Порог отказа в примере — наша собственная стартовая эвристика, так что настраивайте его по своему трафику

Панель HotPDF: сопоставление трёх показаний THPDFRangeCacheStatistics с настройками MaxReadAheadBlocks, SequentialReadToleranceBytes и MaxCacheBytes
каждое прочтение симптома называет своё лекарство — от опускания окна при случайных блужданиях до расширения кэша, когда блоки мечутся

Линеаризованные файлы меняют арифметику

Если продюсер ваш, линеаризация документа меняет саму задачу, а не её настройку. ISO 32000-1 Annex F кладёт объекты первой страницы и таблицу подсказок в начало файла, так что вьювер может отрисовать первую страницу из стартовых байтов, не трогая остальных. HotPDF выставляет тот путь через GetProgressiveLinearizedLoadInfo и ReadProgressiveLinearizedFirstPageSection, принимающие тот же THPDFRandomAccessSource, который вы обернули бы для слияния; пишущая сторона разобрана в статье о генерации линеаризованных PDF с таблицами подсказок

Две техники складываются. Слияние делает терпимым по медленному каналу любой документ, включая файлы третьих сторон, которые вы не можете пересохранить; линеаризация ускоряет приезд первой страницы на документах, которые производите сами. Файлы на локальном диске, слишком крупные для памяти, — другая задача, без задержки кругов, которую можно амортизировать, и пути через отображённый файл и ленивые stream из статьи о рабочем процессе прямого файлового API подходят им лучше

Классы источников с произвольным доступом, сливающая обёртка, политики допуска кэша и вызовы прогрессивной линеаризованной загрузки поставляются с HotPDF — нативным PDF-компонентом для Delphi и C++Builder с полными исходниками. Лицензирование и полный справочник API — на странице компонента HotPDF Delphi PDF