Skip to content

Keep a thread's PDFium up until its last runtime shuts down - #128

Merged
bobsingor merged 1 commit into
embedpdf/mainfrom
embedpdf/fix/thread-lifecycle-count
Nov 19, 2026
Merged

bobsingor merged 1 commit into
embedpdf/mainfrom
embedpdf/fix/thread-lifecycle-count

Conversation

@bobsingor

@bobsingor bobsingor commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

A second runtime on a thread could shut PDFium down under the first. On the native runtime, the one still open then crashed on its next content parse: EPDFAnnot_GetBlendMode() read address 0x8 in CPDF_StreamContentParser::OnOperator. Two local engines in one Node thread, one destroyed before the other, are enough, and Node's default runtime is the native one. WASM is not affected. Found while checking #127 on the native runtime.

Cause

With per-thread globals, a thread's PDFium is started by EPDF_InitThread() and torn down by EPDF_ShutdownThread(), which were FPDF_InitLibrary() and FPDF_DestroyLibrary() under another name. The engine makes one module object per runtime over the same native library, and each runtime calls the pair once. So with two runtimes on a thread:

  1. The first calls EPDF_InitThread(): PDFium starts.
  2. The second calls it too: nothing happens, because the thread is already started.
  3. The second shuts down: FPDF_DestroyLibrary() frees the thread's globals, among them the page module with the content-operator table, the font registry and the graphics module.
  4. The first parses content: g_opcodes is null.

The crash was seen in an appearance stream (CPDF_AnnotContext::SetForm), but nothing is wrong there: any content parse after step 3 does the same. On WASM each runtime is its own module instance with its own memory, so two runtimes never share a PDFium.

Change

EPDF_InitThread() and EPDF_ShutdownThread() are counted per thread (fpdfsdk/epdf_threading.cpp). Only the last EPDF_ShutdownThread() tears PDFium down.

  • A shutdown with no init before it still tears down, as FPDF_DestroyLibrary() does. Nothing changes for a caller that uses the pair once.
  • The count is EPDF_TLS, like the state it guards. Without per-thread globals it counts for the process.
  • public/epdf_view.h states the counting, and the ledger's per-thread-init rule names it and the test.

The engine needs no change: each WorkerHost already calls the pair once.

Tests

EPDFViewEmbedderTest.ThreadLifecycleIsCounted, in epdf_view_embeddertest.cpp. On a thread of its own, as a worker has: two inits, one shutdown, then an annotation's blend mode is read, which parses its appearance. Then the last shutdown, a new init, and the read again. Without the change it crashes at cpdf_streamcontentparser.cpp:643 on address 0x8, as the engine did.

It is compiled only with EPDF_THREAD_LOCAL_GLOBALS: without per-thread globals the thread would share the harness's PDFium, and the test's last shutdown would tear that down. It only reads, so it is not in the writers list.

Checked

macOS arm64, on 3b4fdaf:

  • Unit: 1402 pass.
  • Embedder: 1830 pass, 4 skipped, 12 fail. The same 12 fail with the change reverted.
  • Layer mode for EPDFViewEmbedderTest.*: 21 pass, none failing only in layer mode, no unlisted writer.
  • check-fork-tags.py: no untagged block. check-c-api.py: ok.

macOS arm64, on the same change before it was rebased onto #127 (on 47f0d99):

  • Pixel: 147 pass, 51 failures and 2 surprises. The runner's output is the same line for line with the change reverted.
  • check-globals.py on the release library: ok.
  • Thread soak, 8 threads, 40 iterations each, layer mode, without ThreadSanitizer: ok.
  • The engine on the native runtime, annotation-export.test.ts with prefer: 'native': the worker exits on the released library (f2ea759), and 9 of 9 pass on this build.
  • The engine's annotation and form suites on the native runtime, 33 files: 735 pass and that one crash on the released library, 736 of 736 on this build.

Linux x64 in Docker, on 3b4fdaf:

  • Unit: 1409 pass.
  • Embedder: 1844 pass, 4 skipped, none failed. The new test passes.
  • Layer mode for EPDFViewEmbedderTest.*: 21 pass, none failing only in layer mode, no unlisted writer.

Not run: the ThreadSanitizer soak, WASM.

Left

  • Release and the pin in embed-pdf-viewer. An engine test with two native engines on one thread can go in with the pin.
  • Not part of this: two WorkerHosts made over the same runtime object share one "initialized" entry in the engine's bootstrap.ts, so the first to shut down still ends PDFium for both. Only hand-written tests do that.

Two runtimes on one thread share that thread's PDFium on native: each is a
new module object over the same library. Each calls EPDF_InitThread and
EPDF_ShutdownThread once, and the first shutdown ran FPDF_DestroyLibrary for
both. The runtime still open then read content with the thread's globals
gone: EPDFAnnot_GetBlendMode crashed in CPDF_StreamContentParser::OnOperator
on a null operator table (a read of address 0x8). Two local engines in one
Node thread, one destroyed before the other, are enough. WASM is not
affected: each runtime there has its own memory.

EPDF_InitThread and EPDF_ShutdownThread are now counted per thread, and only
the last EPDF_ShutdownThread tears PDFium down. A shutdown with no init
before it still tears down, as FPDF_DestroyLibrary does.

Test: EPDFViewEmbedderTest.ThreadLifecycleIsCounted, on a thread of its own.
After two inits and one shutdown it reads an annotation's blend mode, which
parses the appearance; after the last shutdown a new init starts PDFium
again. Without the change it crashes at the line the engine crashed at.
@bobsingor
bobsingor merged commit 63f8a2f into embedpdf/main Nov 19, 2026
1 check passed
@bobsingor
bobsingor deleted the embedpdf/fix/thread-lifecycle-count branch November 19, 2026 23:15
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