Performance and Isolation Trade-offs

The single-forked-child (3.x) and shared-server (4.x) shapes are close cousins: one parsing JVM serving all concurrency, with the front-end/watchdog restarting it on failure. The practical 4.x default choice is between per-client (strongest isolation) and shared-server (highest throughput).

The pipes per-request overhead — temp-spool of large payloads, socket IPC, and result serialization — is roughly fixed per request. It therefore dominates when parse time is small (many tiny documents) and amortizes away as documents get larger and parsing dominates.

Relative throughput at matched concurrency (requesting threads = worker count), normalized to a single in-JVM parser of the same total heap (= 1.00; higher is faster). These are representative figures from one benchmark (16-core host, JDK 17, loopback HTTP, plain-text extraction) and are meant to show the shape of the trade-off, not to be quoted as absolutes:

Two things to note:

How a document reaches the parser matters as much as the parsing mode. The classic endpoints (/tika, /rmeta, /meta) receive the document in the HTTP request body and return the extract in the response, so every request pays to move the bytes in and the result back out — and in 4.x that now crosses the process boundary to a forked worker. The pipes endpoints (/pipes, /async) instead take only a small fetch/emit tuple: the worker reads the document straight from the configured fetcher — a file system, Amazon S3, Google Cloud Storage, Azure Blob Storage, and so on — and the configured emitter writes the result straight to its destination, which need not be a file at all: an object store, a search index (OpenSearch, Solr, Elasticsearch), a database, a queue. The bytes never travel over HTTP and the result is never passed back through the front-end.

Whenever a fetcher can reach your inputs and an emitter your destination, the fetch/emit endpoints skip the HTTP body transfer and the result passback — a saving that holds for any fetcher and emitter. What that is worth in throughput depends on the store, and the only combination measured here is local file system on both ends. Those figures, relative to a 3.x single in-JVM parser (= 1.00; higher is faster; one 16-core host, plain-text recursive metadata, concurrency = worker count, per-client isolation):

Two things to read from it:

So a file-system fetch-and-emit workload need not choose between 3.x throughput and 4.x isolation: measured file system to file system, /pipes (and /async) delivered both. With other fetchers and emitters you keep the isolation and the skipped HTTP-body/passback, and the extract can land straight in a search index or database instead of round-tripping back through your client — but the throughput then also rides on that store’s own latency and bandwidth, which we have not measured, so treat those cases as architecturally similar rather than numerically equal. The upload endpoints remain the convenient choice for interactive, single-document requests where the bytes are already in hand and isolation — not raw throughput — is what you are buying.

Pipes adds a fixed floor of roughly tens of milliseconds per request from the IPC round-trip, visible at the median on fast parses.

For the tail, isolating the parse JVM from the HTTP front-end (both pipes modes) keeps a slow or pathological document off the request-accept path. In per-client mode a single slow document occupies only one of numClients workers; in shared-server and single-child modes it occupies one of the shared thread pool’s slots. In practice shared-server can show the best worst-case latency of the shapes here, because it combines a large single heap (fewer, shorter GC stalls than several small heaps) with a front-end that is never blocked by parsing.

The output format also matters: full XHTML, Markdown, plain text, and recursive metadata JSON impose different serialization costs on the same parse. Compare like with like when benchmarking.

Per-client mode runs numClients heaps; size each for the worst-case single document. Shared-server and single-JVM modes run one heap; size it for the worst-case concurrent load (see Shared-server sizing). Per-client therefore uses more total resident memory but bounds per-document usage: a memory-hungry document can only exhaust its own worker’s heap, not the pool’s. For the per-fork -Xmx and CPU rules of thumb, see Forked-JVM CPU and Heap Sizing.

Every shape below except 3.x --noFork recovers automatically from a crash, OutOfMemoryError, or timeout. They differ in how many in-flight requests a single failure takes down, and whether the HTTP endpoint stays up:

3.x already provides process isolation in its default configuration: the forked child survives a parser crash, OOM, or timeout because the watchdog restarts it. Only the legacy --noFork mode parses in the server process itself and has no recovery. So the 4.x change is a finer granularity of isolation, not isolation where there was none — per-client mode narrows the blast radius from "all in-flight" to "one request," and both pipes modes keep the HTTP front-end serving while a worker restarts.

The numbers above are illustrative. Throughput depends on your document mix, document sizes, requested output format, concurrency, host CPU/heap, and disk speed (large payloads spool to a temp directory). Measure with your corpus:

Levers that were tried against the isolated-mode throughput gap and do not close it, recorded here so they need not be re-litigated:

What is left is structural: the fixed per-request IPC + temp-spool + result serialization cost, and running several CPU-partitioned JVMs instead of one. The productive directions are shrinking that per-request cost (RAM-disk temp directory, keeping more payloads inline, leaner serialization) and fork-pool sizing — not a single JVM flag.