Concurrency

Copy Markdown View Source

A %PdfElixide.Document{} is safe to pass to another process. Native document reads use shared access, so workers extracting from one open document do not queue behind each other at the handle boundary. Values already cached on the Elixir struct — the version, source path, and usually the page count — need no native access. You normally do not need to open the same file once per worker or keep a document inside the process that opened it. Use separate handles only to isolate repeated extraction of the same page from the /ActualText behavior below. Each handle loads and caches its own document.

alias PdfElixide.Document

doc = Document.open!("path/to/file.pdf")

# One handle, one page per worker. This avoids the /ActualText hazard below.
pages =
  doc
  |> Task.async_stream(&PdfElixide.Document.Page.text!/1, ordered: true)
  |> Enum.map(fn {:ok, text} -> text end)

# Close once the workers are done. `close/1` waits for calls already in flight,
# but a read that starts afterwards gets an ordinary :closed error.
:ok = Document.close(doc)

The exclusive calls

These document operations take the native handle exclusively. They wait for in-flight native calls on that handle and block new ones for their duration.

  • PdfElixide.Document.authenticate/2 waits for current readers and blocks new ones while it authenticates. Call it before fanning the document out to workers, not after.
  • PdfElixide.Document.clear_search_index/1 waits for current searches before releasing the index, so the memory is gone when it returns. Its sibling PdfElixide.Document.prepare_search/1 is an ordinary shared read.
  • PdfElixide.Document.close/1 waits for every in-flight call to return rather than interrupting it — immediately means as soon as the handle is idle, not preemptively, and an extraction can hold its share of the lock for seconds. Afterwards every reader gets {:error, %PdfElixide.Error{reason: :closed}}, an ordinary error rather than a crash. A worker racing a close may therefore return this error. Close only once the workers are done.

The /ActualText hazard

Some tagged PDFs declare competing /ActualText replacements for the same marked content. Repeated extractions of the same page on one handle can then return inconsistent replacement text without an accompanying error, whether the calls overlap or run one after another.

Fanning work out by page avoids cross-contamination between workers that never share a page. Avoid running two whole-document text-family extractions on one handle at once when these PDFs are in scope.

Throughput is not linear

Concurrency does not guarantee linear scaling. First-time extraction can still contend while the document is being loaded and decoded, while repeated work may benefit more from cached data. Benchmark representative PDFs rather than expecting speedup proportional to the worker count.

Captured diagnostics are not per-process

Diagnostics capture is global to the VM, and a captured record is forwarded by whichever process next returns from a library call, so it carries no Logger metadata identifying the work that produced it. See PdfElixide.Logging.

The other handles

PdfElixide.Editor is different in kind, because it mutates. Every call that writes or changes the document takes the handle exclusively, so concurrent editing of a single editor serializes instead of running in parallel. Give each process its own editor if you need them to work at once.

The editor's shared reads are PdfElixide.Editor.page_count/1, PdfElixide.Editor.modified?/1, PdfElixide.Editor.rotation/2, PdfElixide.Editor.flatten_warnings/1 and PdfElixide.Editor.closed?/1. They do not wait on each other, but any of them will queue behind an in-flight exclusive operation such as a save on the same handle. For flatten_warnings/1, this ensures an in-flight save finishes before the warnings are read.

PdfElixide.Form.fields/1 inherits whichever source it is handed — a shared read on a document, the editor's exclusive lock on an editor — so listing fields from an editor serializes even though it only reads.

PdfElixide.Signature.list/1, PdfElixide.Signature.unsigned_fields/1, PdfElixide.Signature.count/1 and PdfElixide.Signature.dss/1 are shared reads on both sources. Given an editor they read the document that editor was opened from, which needs no exclusive lock, so listing signatures does not serialize the way listing fields does.

Every other public signature operation takes a signature or security-store struct, plain bytes, or scalar values rather than a handle, so it takes no handle lock. Nothing else running on the source document can delay it, and closing the document does not stop it answering. Certificates and timestamps reached from a signature are plain values too, so their operations are lock-free for the same reason.

PdfElixide.Form.put_values/2 validates values together but does not make their writes atomic. PdfElixide.Form.update_value/3 is likewise a read followed by a write, so another process holding the same editor can write in between.

PdfElixide.Document.Image, PdfElixide.Document.Font and PdfElixide.Document.Table handles are shareable the same way as a document, and without the /ActualText hazard above. Concurrent to_binary/2, data/1 and table rendering calls can run alongside each other. Their close/1 is the exclusive operation and waits for in-flight calls in the same way as a document's close/1.