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

RenderCacheFolder в HotPDF: дисковый кэш страниц на Delphi

Кэш страниц, ключёванный именем файла, покажет вчерашние страницы для PDF, перезаписанного за ночь новой ревизией под тем же именем. Кэш, ключёванный полным SHA-256 файла, никогда так не ошибётся, но на архиве сканов в 400 МБ хеш может занять дольше, чем рендер двух страниц, которые пользователь реально открывает. Рабочий ключ сидит между этими двумя, и его выбор заставляет принять и второе решение: что правка в памяти должна делать со страницами, уже лежащими на диске

Как дисковый ярус RenderCacheFolder стоит за кэшем в памяти

RenderCacheFolder в HotPDF добавляет персистентный ярус за растровым кэшем в памяти компонента HotPDF Delphi, и участвует он, только когда свойство держит непустой путь. Вызов RenderLoadedPageToBitmapCached(PageIndex, DPI) сначала проверяет память, ключуя по индексу страницы, DPI и текущим настройкам рендера. На промахе он спрашивает диск. Попадание на диске декодирует сохранённый PNG, возвращает его в память и вручает вам копию. И только когда оба яруса промахнулись, страница идёт через полный рендерер из статьи рендеринг загруженной PDF-страницы в TBitmap, и свежий битмап по дороге наружу пишется на диск

Схема HotPDF поиска в рендер-кэше для RenderLoadedPageToBitmapCached: сперва проверяется ярус в памяти, ключёванный страницей, DPI и вариантом рендеринга, затем дисковый ярус RenderCacheFolder из PNG-файлов с атомарной заменой, затем интерпретатор потока содержимого, и каждое попадание возвращает копию во владении вызывающего
HotPDF сперва смотрит в память, затем на диск и лишь потом растрирует; попадание на диске возвращается в память, и каждый путь вручает вам копию, которой вы владеете и обязаны освободить

Раскладка папки проста настолько, что её можно разглядывать в Проводнике. Каждому документу — подпапка, чьё имя сочетает 16 hex-символов ключа документа с 16 hex-символами ключа настроек рендера, и каждая страница ложится туда как <page>@<dpi>.png. index.txt в корне перечисляет документы в порядке MRU под тегом схемы; если тег не совпал, вся папка чистится при первом использовании. Записи PNG и индекса сначала идут во временный файл, затем подменяются через MoveFileExW с флагом замены существующего, поэтому краш посреди записи оставляет прежний файл или никакого. PNG, не сумевший декодироваться, удаляется и считается промахом

Три предела не дают папке расти без границ:

  • RenderCacheMaxDocuments (по умолчанию 20) ограничивает число подпапок документов, выгоняя первой наименее недавно использованную
  • RenderCacheMaxBytes (по умолчанию 524288000, или 500 МБ) ограничивает суммарный размер всех PNG под корнем
  • Каждая папка документа держит максимум 200 изображений страниц; этот потолок зашит в THotPDF и свойства не имеет

RenderCacheCapacity (по умолчанию 8) к диску отношения не имеет. Он считает страницы, удерживаемые в памяти

uses
  SysUtils, Graphics, HPDFDoc;

procedure WarmThumbnails(const FileName: string);
var
  Pdf: THotPDF;
  Bmp: TBitmap;
  I: Integer;
begin
  Pdf := THotPDF.Create(nil);
  try
    // Дисковый ярус читает папку и оба предела один раз, при первом
    // кэшированном рендере, поэтому задайте их до этого вызова
    Pdf.RenderCacheFolder := IncludeTrailingPathDelimiter(
      GetEnvironmentVariable('LOCALAPPDATA')) + 'MyViewer\PageCache';
    Pdf.RenderCacheMaxDocuments := 50;
    Pdf.RenderCacheMaxBytes := Int64(1024) * 1024 * 1024; // 1 ГиБ
    Pdf.RenderCacheCapacity := 16;                        // страницы в памяти

    if Pdf.LoadFromFile(FileName) > 0 then
      for I := 0 to Pdf.LoadedPageCount - 1 do
      begin
        Bmp := Pdf.RenderLoadedPageToBitmapCached(I, 96);
        if Bmp <> nil then
        try
          // Отдайте копию полосе миниатюр здесь
        finally
          Bmp.Free; // кэширующий вызов всегда возвращает копию во владении вызывающего
        end;
      end;
  finally
    Pdf.Free; // дисковые записи переживают до следующей сессии
  end;
end;

Прогоните эту процедуру дважды на одном файле — и второй проход не растрирует ничего, что влезло в пределы. Дисковый кэш создаётся при первом кэшированном рендере и живёт, пока жив экземпляр THotPDF, поэтому смена папки или любого предела после этого момента не перенесёт и не перенастроит его. Ещё два условия держат страницу вне диска. Битмап выше дефолтного поштучного потолка кэша в памяти (64 МиБ 32-битных пикселей — страница 4096 × 4096) не сохраняется. И дисковый ярус опрашивается, только пока RenderFallbackPolicy остаётся в дефолте rfpIgnore, поскольку PNG несёт пиксели, но ни одной из диагностик отката, которые докладывает более строгая политика

Почему очевидные ключи кэша проваливаются?

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

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

Как HotPDF снимает отпечаток источника PDF

HotPDF опознаёт PDF, загруженный через LoadFromFile, хешируя его размер, время последней записи и первые и последние 64 КиБ через SHA-256, а поток или random-access источник — через SHA-256 всего содержимого. Идентичность снимается один раз, при успешной загрузке, и первые 16 hex-символов дайджеста (64 бита) становятся ключом документа

ИсточникИдентичностьЦенаКогда снимается
LoadFromFileРазмер + время последней записи + первые и последние 64 КиБ, хешированные SHA-256Максимум 128 КиБ чтения, при любом размере файлаПри каждой успешной загрузке, даже если RenderCacheFolder задан позже
LoadFromStreamSHA-256 целого потокаОдин полный проход по источникуТолько если RenderCacheFolder был задан до загрузки
LoadFromRandomAccessSourceSHA-256 целого источникаОдин полный проход по источникуТолько если папка была задана сперва и каждый диапазон байтов доступен
Любой источник с записью /EncryptНетНетНикогда; дисковый ярус обходится
Карта идентичности источников для дискового рендер-кэша HotPDF: LoadFromFile хэширует размер, LastWriteTime и первые и последние 64 КиБ, LoadFromStream и LoadFromRandomAccessSource хэшируют всё содержимое лишь когда RenderCacheFolder был выставлен сперва, а любой трейлер с /Encrypt не снимает идентичность вовсе
файлы снимаются по отпечатку с концов, потому что там живут header, xref и трейлер; потоки платят за полный хэш, лишь если вы сперва попросили кэш, а шифрованные документы никогда не пишутся на диск

Для десктопного вьюера сэмплированный отпечаток — правильный дефолт, а полное хеширование при каждом открытии — неверный. Две сэмплированные области выбраны из структуры файла. Header сидит в начале; трейлер и последняя секция перекрёстных ссылок — в конце (ISO 32000-1 §7.5). Инкрементальное обновление дописывает новое тело, секцию перекрёстных ссылок и трейлер (§7.5.6), что меняет размер и хвост разом, а любой обычный полный перезаписывающий сейв поднимает время последней записи. Ниже 128 КиБ два сэмпла перекрываются и покрывают каждый байт, так что маленькие документы всё равно хешируются целиком

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

У потока таймстампа нет. Контент — единственная честная идентичность, поэтому HotPDF платит за полный проход SHA-256, только когда дисковый кэш был запрошен до загрузки, а код, зовущий LoadFromStream без папки кэша, не платит ничего сверху. Отсюда порядок двух строк имеет значение:

procedure OpenDownloadedPdf(Pdf: THotPDF; Data: TStream;
  const CacheRoot: string);
begin
  // Неверный порядок для потоков: контентный хэш считается, только когда
  // папка уже выставлена, так что этот документ обошёл бы дисковый ярус
  //   Pdf.LoadFromStream(Data);
  //   Pdf.RenderCacheFolder := CacheRoot;

  Pdf.RenderCacheFolder := CacheRoot; // выставляем сперва
  Data.Position := 0;
  if Pdf.LoadFromStream(Data) <= 0 then
    raise Exception.Create('The stream is not a loadable PDF');
end;

Random-access источник, который ещё скачивается, не получает идентичности вовсе — вместо хеша того, что уже приехало. Если вычисление идентичности упадёт по любой причине, загрузка всё равно завершится успехом, а документ будет рендериться только через память

Что происходит с закэшированными страницами после правки?

Правка загруженного документа никогда ничего не удаляет из дискового рендер-кэша HotPDF. Правка сбрасывает идентичность документа, поэтому остаток этой загрузки обходит дисковый ярус, а сохранённые страницы остаются валидными для нетронутого файла, с которого они отрендерены. Записи покидают диск только через пределы документов и байтов, потолок в 200 страниц, PNG, не сумевший декодироваться, или смену схемы

Ключ описывает файл на диске. Как только вы поставили штамп на страницу или поменяли аннотацию, документ в памяти ему больше не соответствует, поэтому ни чтение, ни запись под этим ключом не были бы честными. InvalidateRenderedPageCache и постраничная инвалидация, которую триггерят правки, оба стирают идентичность и оставляют папку в покое. Вторая проверка покрывает пути правок, ничего не инвалидирующие: перед каждым дисковым поиском THotPDF спрашивает, несёт ли какой-нибудь загруженный объект несохранённые изменения, и если да — трактует документ как не имеющий идентичности

Настройки рендера идут в другую сторону. Присвоение PageRenderBackend (что за вас делает UseNativeGDIRenderBackend), вызов ConfigureRenderICCWorkflow или ClearRenderICCWorkflow вымывает страницы в памяти, но сохраняет идентичность, потому что документ всё ещё соответствует своему файлу. Эти настройки меняют пиксели, не появляясь в ключе памяти, поэтому дисковый ключ вплетает имя бэкенда, флаг компенсации чёрной точки и SHA-256-дайджесты ICC proof- и output-профилей. Ключ памяти уже покрывает цветовое намерение, output dithering, превью overprint, режим luminosity mask, политику отката и видимость каждой группы optional content

Семантика инвалидации дискового кэша RenderCacheFolder в HotPDF: правка загруженного документа или любого грязного объекта сбрасывает идентичность источника, так что ярус обходится; смена рендер-бэкенда или ICC-воркфлоу сохраняет идентичность под новым ключом варианта, а save плюс перезагрузка переключевывает документ
правка никогда не удаляет сохранённую папку, смена настроек рендерит под другим ключом, и лишь save плюс перезагрузка зарабатывают правленному документу свежую идентичность

Видимость слоёв — хороший пример изменения, остающегося на диске. SetLoadedOptionalContentGroupVisible записывает переопределение в память, не трогая ни одного PDF-объекта, поэтому документ сохраняет идентичность, и переключённый вид рендерится в собственную подпапку рядом с дефолтной:

procedure ShowLayer(Pdf: THotPDF; const LayerName: AnsiString;
  PageIndex: Integer; out Bmp: TBitmap);
var
  I: Integer;
begin
  for I := 0 to Pdf.GetLoadedOptionalContentGroupCount - 1 do
    if Pdf.GetLoadedOptionalContentGroupName(I) = LayerName then
      Pdf.SetLoadedOptionalContentGroupVisible(I, True);

  // Тот же ключ документа, другой ключ настроек рендера: эта страница читается
  // из второй папки или пишется в неё, а дефолтный вид не тронут
  Bmp := Pdf.RenderLoadedPageToBitmapCached(PageIndex, 150);
end;

Правленый документ возвращается на дисковый ярус, только став новым файлом. Сохраните его и загрузите результат:

procedure CommitEditsAndRekey(Pdf: THotPDF; const EditedFile: string);
begin
  // После правки: освежите страницы в памяти. Идентичность источника
  // уже стёрта, поэтому папка исходного документа не читается
  // и не пишется
  Pdf.InvalidateRenderedPageCache;

  // Сохранённый файл имеет собственные размер и время последней записи, а значит
  // и собственную идентичность; рендеры после этой загрузки кэшируются под новым ключом
  Pdf.SaveLoadedDocument(EditedFile);
  if Pdf.LoadFromFile(EditedFile) <= 0 then
    raise Exception.Create('Could not reload the edited document');
end;

Папка исходного документа остаётся где была и стареет через RenderCacheMaxDocuments и RenderCacheMaxBytes как любая другая запись. Откройте нетронутый оригинал — и его страницы всё ещё там

Зашифрованные источники, junction и разделяемые корни

Дисковый рендер-кэш HotPDF нарочно отказывает двум входам: страницам зашифрованного PDF и подпапкам документов, являющимся junction или другими reparse point. Оба правила меняют попадания в кэше на безопасность

Зашифрованные PDF остаются в памяти

Отрендеренная страница — расшифрованный контент. Записать её обычным PNG в папку кэша — значит оставить читаемую копию защищённого паролем документа на диске, вне защиты, которую выбрал её автор (ISO 32000-1 §7.6). HotPDF не снимает идентичность ни с какого источника, чей трейлер несёт запись /Encrypt, открыт ли он с паролем или с пустым пользовательским паролем. Такие документы по-прежнему используют ярус памяти, исчезающий вместе с процессом

Связанные папки документов пропускаются

Корень кэша выбираете вы, и навести его на junction можно. Подпапки под ним — другое дело: кэш создаёт, трогает и удаляет их самостоятельно при стартовой чистке, поиске, сохранении и всех трёх пределах вытеснения. Если кто-то с правом записи в корень подменил папку документа junction на другой каталог, каждая из этих операций последует за ним, и вытеснение удалит файлы в другом месте. Каждая точка входа сначала читает атрибуты папки и пропускает всё, помеченное как reparse point. Поиск считает промах, сохранение — сбой записи, а вытеснение оставляет её в покое

Unicode-пути и один корень на процесс

RenderCacheFolder — Unicode string, и атомарная замена зовёт wide Windows API, поэтому путь профиля вне системной кодовой страницы (имя пользователя китайскими иероглифами на английской Windows, скажем) доезжает до кэша целым. Несколько экземпляров THotPDF в одном процессе, разрешающихся в один корень — сравнённых без учёта регистра после расширения пути, — делят один индекс со счётчиком ссылок и один лок. Это важно для пределов: отдельные копии index.txt принуждали бы бюджет 500 МБ каждая к частичному виду и позволили бы папке вырасти сверх него несколько раз

Совместное использование кончается на границе процесса. Два процесса на одном корне держат раздельные индексы в памяти, поэтому каждому одновременно работающему приложению — свой корень. Воркер-потоки внутри одного процесса — можно: PrefetchLoadedPages и очередь из статьи фоновый рендеринг с очередью запросов идут через тот же кэшированный путь и тот же лок

Настройки, которые надо выставить до поставки

  • Задайте папку и оба предела до первого кэшированного рендера, а для загрузок из потока или random-access источника — до загрузки
  • Ожидайте рендеринг только в памяти для зашифрованных PDF, для документов, правленных после загрузки, и всякий раз, когда RenderFallbackPolicy не rfpIgnore
  • Дайте каждому работающему приложению собственный корень кэша в пользовательском расположении вроде %LOCALAPPDATA%

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