技术文章

HotPDF RenderCacheFolder:Delphi 磁盘页面缓存

按文件名做键的页面缓存,会在一份 PDF 隔夜被同名新修订覆盖之后,端出昨天的页面。按文件全量 SHA-256 做键的缓存从不犯这个错,但对一份 400 MB 的扫描档案,哈希可能比渲染用户实际打开的那两页还慢。能用的键落在两者之间,而选键也逼出第二个决定:内存中的编辑对已经躺在磁盘上的页面意味着什么

RenderCacheFolder 磁盘层如何垫在内存缓存之后

HotPDF RenderCacheFolder 在 HotPDF Delphi 组件的内存光栅缓存后面加了一个持久层,且只在属性持非空路径时才介入。调用 RenderLoadedPageToBitmapCached(PageIndex, DPI) 先查内存,键由页码、DPI 和当前渲染设置构成。未命中就问磁盘。磁盘命中则解码存储的 PNG,提升回内存,交给你一份副本。只有两层都未命中,页面才走把已加载 PDF 页面渲染成 TBitmap所描述的完整渲染器,而新鲜位图在出来的路上写进磁盘

HotPDF 图示 RenderLoadedPageToBitmapCached 的渲染缓存查找:先查按页面、DPI 与渲染变体为键的内存层,再查带原子替换的 RenderCacheFolder PNG 磁盘层,再走内容流解释器,每次命中都返回调用者所有的副本
HotPDF 先查内存、再查磁盘,最后才栅格化;磁盘命中会提升回内存,每条路径交给你的都是你拥有且必须释放的副本

文件夹布局朴素到可以在资源管理器里直接检查。每份文档一个子文件夹,名字由 16 个十六进制字符的文档键加 16 个十六进制字符的渲染设置键组成,每页以 <page>@<dpi>.png 落在那里。根上的 index.txt 在一个 schema 标签下按最近使用顺序列出文档;标签不匹配,整个文件夹在首次使用时被清空。PNG 与索引写入先落临时文件,再以 MoveFileExW 加替换标志换进正式位置,所以写到一半崩溃,留下的要么是旧文件、要么没有文件。解码失败的 PNG 被删掉并计为未命中

三条上限让文件夹不至于无限生长:

  • RenderCacheMaxDocuments(默认 20)限制文档子文件夹的数量,最久未用的先被逐出
  • RenderCacheMaxBytes(默认 524288000,即 500 MB)限制根下所有 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 GiB
    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 MiB 的 32 位像素,即 4096 × 4096 一页)不存;而且只有 RenderFallbackPolicy 保持默认 rfpIgnore 时才查磁盘层,因为更严的政策要上报的回退诊断是 PNG 带不来的

为什么显而易见的缓存键都会失败?

最先想到的三个键各有各的死法。文件路径败给覆盖。对 PDF 字节内存副本做哈希看着安全,直到你注意到就地读文件的解析器没理由留着这样一份副本;对从未填充的缓冲做哈希得到空键,而把空键当「跳过磁盘」的缓存,留下一个配置正确却永远收不到 PNG 的文件夹。从磁盘对整个文件做哈希可行,代价是每次打开读遍每个字节

更难的陷阱是失效。这样的组件必须在每次加载开始、每次编辑之后和销毁时清空内存页面,而诱人的做法是在同样的地方删掉文档的磁盘文件夹。这么做的结果是每个查看器会话退出时清掉自己的缓存,第二天早晨照样冷启动。编辑之后从未变的源重新算键更糟:编辑后的渲染落在原文件的键下,被端给下一个打开未修改 PDF 的人。同一性与失效必须作为一个整体设计;任何一个做错,你发布的要么是从不命中的缓存,要么是端出文件里没有的页面的缓存

HotPDF 怎么给 PDF 源做指纹

对经 LoadFromFile 加载的 PDF,HotPDF 用 SHA-256 哈希它的大小、最后写入时间以及头尾各 64 KiB 来识别;对流或随机访问源,则用整个内容的 SHA-256。同一性在加载成功的那一刻捕获一次,摘要的前 16 个十六进制字符(64 位)成为文档键

源同一性代价捕获时机
LoadFromFile大小 + 最后写入时间 + 头尾各 64 KiB,用 SHA-256 哈希至多读 128 KiB,与文件大小无关每次成功加载,即使 RenderCacheFolder 之后才设置
LoadFromStream整个流的 SHA-256对源完整过一遍仅当加载前已设置 RenderCacheFolder
LoadFromRandomAccessSource整个源的 SHA-256对源完整过一遍仅当先设置了文件夹且每个字节范围都可用
带 /Encrypt 表项的任何源无无从不;磁盘层被绕过
HotPDF 磁盘渲染缓存的源同一性地图:LoadFromFile 哈希大小、LastWriteTime 与头尾各 64 KiB,LoadFromStream 与 LoadFromRandomAccessSource 仅在先设置了 RenderCacheFolder 时才哈希全部内容,任何带 /Encrypt 的 trailer 完全不捕获同一性
文件从两端取指纹,因为文件头、xref 和 trailer 都在那里;流只有在你先要了缓存时才为完整哈希买单;加密文档永远不写盘

对桌面查看器,取样指纹是正确的默认,每次打开全量哈希是错误的。两个取样区域取自文件结构:文件头在开头;trailer 和最后一个交叉引用节在末尾(ISO 32000-1 §7.5)。增量更新追加新的主体、交叉引用节和 trailer(§7.5.6),大小与尾部一起变化;任何普通的全量重写都会动最后写入时间。128 KiB 以下两个样本重叠、覆盖每个字节,小文档反正被完整哈希

能溜过去的是大文件中部同尺寸的就地修改,外加随后恢复原始时间戳的工具。刻意在改内容的同时保留修改时间的编辑器存在,但罕见;对这种文件,缓存端出过期页面。相反的情形对你有利: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;

仍在下载中的随机访问源得不到任何同一性,而不是得到已到字节的哈希。计算同一性因任何原因抛异常时,加载照样成功,文档只走内存渲染

编辑之后,缓存的页面会怎样?

编辑已加载的文档从不删除 HotPDF 磁盘渲染缓存里的任何东西。编辑丢弃的是文档的同一性,于是该次加载的其余部分绕过磁盘层,而已存储的页面对它们渲染自的那个未修改文件仍然有效。条目离开磁盘只有几条路:文档与字节上限、200 页上限、解码失败的 PNG、或 schema 变更

键描述的是磁盘上的一个文件。给页面盖章或改注解之后,内存中的文档不再匹配它,在那个键下读写都不诚实。InvalidateRenderedPageCache 和编辑触发的按页失效都只清同一性、不碰文件夹。第二道检查兜住从不失效的编辑路径:每次磁盘查找之前,THotPDF 询问是否有加载对象带着未保存的更改,有就把文档当没有同一性

渲染设置朝反方向走。赋值 PageRenderBackend(UseNativeGDIRenderBackend 会替你做)、调 ConfigureRenderICCWorkflow 或 ClearRenderICCWorkflow,会清空内存页面但保留同一性,因为文档仍匹配它的文件。这些设置改变像素却不出现在内存键里,所以磁盘键把后端名称、黑点补偿标志和 ICC 打样与输出 profile 的 SHA-256 摘要折进键里。内存键已经覆盖色彩意图、输出抖动、叠印预览、亮度蒙版模式、回退政策和每个可选内容组的可见性

HotPDF 的 RenderCacheFolder 磁盘缓存失效语义:编辑加载中的文档或任何脏对象会丢弃源同一性从而绕过该层,更改渲染后端或 ICC 工作流在新变体键下保留同一性,保存再重新加载则给文档换新键
编辑从不删除已存储的文件夹,设置变更换个键渲染,只有保存再重新加载才能让编辑后的文档赢得新的同一性

图层可见性是「变化留在磁盘上」的好例子。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)。所以对 trailer 带 /Encrypt 表项的任何源——无论用密码打开还是用户密码为空——HotPDF 都不捕获同一性。这些文档仍用内存层,它随进程消失

链接的文档文件夹被跳过

缓存根由你选,指到 junction 上没问题。它下面的子文件夹是另一回事:缓存在启动清理、查找、存储和全部三条逐出上限中都会自己创建、触碰和删除它们。如果对根有写权限的人把某个文档文件夹换成指向别处的 junction,上面每个操作都会跟进去,逐出就会删到别处。每个入口先读文件夹属性,凡带 reparse point 标志的一律跳过:查找计一次未命中,存储计一次写入失败,逐出绕开它

Unicode 路径与每进程一个根

RenderCacheFolder 是 Unicode string,原子替换调宽字符 Windows API,所以系统代码页之外的 profile 路径(比如英文 Windows 上的中文用户名)完好到达缓存。同一进程里解析到同一个根的多个 THotPDF 实例——路径展开后、大小写不敏感比较——共享一份引用计数的索引和一把锁。这对上限很要紧:index.txt 的各自副本会各按局部视图执行 500 MB 预算,让文件夹超出好几倍

共享止步于进程边界。同一根上的两个进程各持内存索引,所以每个并发运行的应用应有自己的根。一个进程内的工作线程没问题:PrefetchLoadedPages 和用请求队列做后台渲染里的队列走同一条缓存路径、同一把锁

发布前要设对的选项

  • 第一次缓存渲染之前设置文件夹与两条上限;流或随机访问加载则要在加载之前
  • 加密 PDF、加载后编辑过的文档、以及 RenderFallbackPolicy 不是 rfpIgnore 时,预期只有内存渲染
  • 给每个运行中的应用自己的缓存根,放在 %LOCALAPPDATA% 这类每用户位置

持久页面缓存在整天反复打开同一批文档的查看器里才值回磁盘空间,那正是本博客Delphi 自定义 PDF 查看器架构背后的工作负载。磁盘层、内存光栅缓存和页面渲染器都是 HotPDF Delphi PDF component 的一部分,Delphi 与 C++Builder 均可用