Кэш страниц, ключёванный именем файла, покажет вчерашние страницы для PDF, перезаписанного за ночь новой ревизией под тем же именем. Кэш, ключёванный полным SHA-256 файла, никогда так не ошибётся, но на архиве сканов в 400 МБ хеш может занять дольше, чем рендер двух страниц, которые пользователь реально открывает. Рабочий ключ сидит между этими двумя, и его выбор заставляет принять и второе решение: что правка в памяти должна делать со страницами, уже лежащими на диске
Как дисковый ярус RenderCacheFolder стоит за кэшем в памяти
RenderCacheFolder в HotPDF добавляет персистентный ярус за растровым кэшем в памяти компонента HotPDF Delphi, и участвует он, только когда свойство держит непустой путь. Вызов RenderLoadedPageToBitmapCached(PageIndex, DPI) сначала проверяет память, ключуя по индексу страницы, DPI и текущим настройкам рендера. На промахе он спрашивает диск. Попадание на диске декодирует сохранённый PNG, возвращает его в память и вручает вам копию. И только когда оба яруса промахнулись, страница идёт через полный рендерер из статьи рендеринг загруженной PDF-страницы в TBitmap, и свежий битмап по дороге наружу пишется на диск
Раскладка папки проста настолько, что её можно разглядывать в Проводнике. Каждому документу — подпапка, чьё имя сочетает 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 задан позже |
LoadFromStream | SHA-256 целого потока | Один полный проход по источнику | Только если RenderCacheFolder был задан до загрузки |
LoadFromRandomAccessSource | SHA-256 целого источника | Один полный проход по источнику | Только если папка была задана сперва и каждый диапазон байтов доступен |
Любой источник с записью /Encrypt | Нет | Нет | Никогда; дисковый ярус обходится |
Для десктопного вьюера сэмплированный отпечаток — правильный дефолт, а полное хеширование при каждом открытии — неверный. Две сэмплированные области выбраны из структуры файла. 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
Видимость слоёв — хороший пример изменения, остающегося на диске. 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