Skip to content

Free the page a raw annotation handle is built on - #127

Merged
bobsingor merged 1 commit into
embedpdf/mainfrom
embedpdf/fix/raw-annot-page-leak
Nov 19, 2026
Merged

bobsingor merged 1 commit into
embedpdf/mainfrom
embedpdf/fix/raw-annot-page-leak

Conversation

@bobsingor

@bobsingor bobsingor commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Every handle from EPDFPage_GetAnnotRaw() or EPDFPage_CreateAnnotRaw() leaked one CPDF_Page: 11 blocks, about 1.4 KB, on native and WASM. It has done so since 61181c3 (Aug 6 2025), so in every 2.x and 3.x. The engine opens a raw handle for every annotation read. Reported in embedpdf/embed-pdf-viewer#1124.

Cause

The raw functions build a CPDF_Page from the page dictionary alone, for a page nobody loaded. They gave it to RawAnnotContext, a subclass of CPDF_AnnotContext with one more member: the page. FPDFPage_CloseAnnot() deletes a handle as CPDF_AnnotContext, whose destructor is not virtual, so the subclass's member was never destroyed.

Change

CPDF_AnnotContext owns the page itself, for the handles that made one. A handle for a loaded page borrows it, as before.

  • CPDF_AnnotContext::CreateOwningPage() makes a handle that keeps the page it was built on. Both raw functions use it, and RawAnnotContext is gone. The page is the first member, so it is destroyed last, after the members that point at it.
  • The class is final, so the same mistake no longer compiles.
  • CPDF_AnnotContext::CreateLinked() makes the handle FPDFAnnot_GetLinkedAnnot() returns. It shares a page its parent owns, so the two handles close in either order. A linked handle that only borrowed the page would dangle once its parent closed first; the leak hid that.
  • GetWidget() and FORM_SetFocusedAnnot() in fpdf_formfill.cpp return early for a handle that owns its page. They failed for it already, because its page view is never valid, but only after making a view keyed by that page, which would now outlive the page. No return value changes.
  • public/epdf_annot.h says how such a handle is closed, that a linked handle may be closed before or after it, and that the three form-fill calls fail for it.
  • The blocks in upstream files are tagged epdf-api (a core helper that backs an EPDF* function), and the ledger's rule names CreateOwningPage.

A named factory, not a second constructor: RetainPtr<T> converts to T* here, so an overload on the two is ambiguous.

Not chosen:

  • A virtual destructor. It frees the page, but a linked handle is made in fpdf_annot.cpp and cannot share a page that only a subclass knows.
  • Every handle retains its page. Less code, but an open handle would then keep a parsed page alive past FPDF_ClosePage(). That changes regular handles too, which is too wide for a fix that goes back to v2.

Tests

Three in epdf_annot_raw_embeddertest.cpp. All fail without the change.

  • ClosingAHandleFreesItsPage: a created and a read raw handle each hold the only other reference to their page, and closing drops it.
  • ALinkedHandleSharesThePage: a note and its popup; the parent closes first, the popup still works, and the page goes when both are closed. On a loaded page both handles borrow.
  • FormFillCallsMakeNoViewForAHandleWithoutAPage: the three form-fill calls fail for a raw handle to a widget, and the form environment has no view for its page afterwards.

The first two write, and are in testing/embedpdf_layer_mode_writers.txt.

Checked

macOS arm64, against the same tree without the change:

  • Embedder: 1829 pass, 4 skipped. The 12 failures are the ones that fail without the change.
  • Unit: 1402 pass.
  • Pixel: the same lists with and without the change (51 failures and 2 surprises, as on record for this Mac).
  • Layer mode over the whole suite: nothing new reported.
  • check-fork-tags.py: no untagged block. check-c-api.py: ok.
  • The annotation, form-fill, document and edit embedder tests with freed memory scribbled (MallocScribble): no crash, and only the baseline failures.
  • Leaks, counted by leaks --atExit on a Node loop over the C API, 12,000 raw handles created, read and closed: 133,200 blocks (16.4 MB) on the released library (f2ea759), 0 with this build. With a linked handle closed after its parent: 139,199 blocks before, 0 after.
  • The engine's annotation and form suites on the native runtime, memory scribbled: the same result on the released library and on this build.

Linux x64 in Docker, on f05c0fb (finished after the merge):

  • Unit: 1409 pass.
  • Embedder: 1843 pass, 4 skipped, none failed. The three new tests pass.
  • Layer mode for EPDFAnnotRawEmbedderTest.*: 8 pass, none failing only in layer mode, no unlisted writer.

WASM was not measured; it is the same C++.

Left

  • Release, the pin in embed-pdf-viewer, and the v2 backport.
  • The reply on the issue. A caller that worked around the leak by calling FPDF_ClosePage() on the pointer read at handle + 0x40 must drop that in the same upgrade: it would release the page a second time, and the offset no longer holds the page.

Every handle from EPDFPage_GetAnnotRaw() or EPDFPage_CreateAnnotRaw() leaked
one CPDF_Page (11 blocks, about 1.4 KB), on native and WASM, since 61181c3
(Aug 6 2025). The page was held by RawAnnotContext, a subclass of
CPDF_AnnotContext. FPDFPage_CloseAnnot() deletes a handle as
CPDF_AnnotContext, whose destructor is not virtual, so the subclass's member
was never destroyed. Reported in embedpdf/embed-pdf-viewer#1124.

CPDF_AnnotContext now owns the page itself, and is final:
- CreateOwningPage() makes a handle that keeps the page it was built on. The
  two raw functions use it, and RawAnnotContext is gone. The page is the first
  member, so it is destroyed last, after the members that point at it.
- CreateLinked() makes the handle FPDFAnnot_GetLinkedAnnot() returns. It
  shares a page its parent owns, so the two close in either order. A linked
  handle that only borrowed the page would dangle once its parent closed
  first; the leak hid that.
- GetWidget() and FORM_SetFocusedAnnot() return early for a handle that owns
  its page. They failed for it already, since its page view is never valid,
  but only after making a view keyed by that page, which would now outlive
  the page. No return value changes.

A handle for a loaded page borrows it, as before.

Tests in epdf_annot_raw_embeddertest.cpp, all failing without the change:
ClosingAHandleFreesItsPage, ALinkedHandleSharesThePage and
FormFillCallsMakeNoViewForAHandleWithoutAPage. The first two are listed as
layer-mode writers.

A caller that worked around the leak by closing the page it read at
handle + 0x40 must stop with this change: that releases the page a second
time, and the offset no longer holds the page.
@bobsingor
bobsingor merged commit 6a249a9 into embedpdf/main Nov 19, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant