This document describes the StandardPdfPipeline class and its threaded, queue-based architecture for processing PDF documents. The pipeline achieves true parallelism by running multiple stages concurrently with bounded queues connecting them, allowing OCR, layout detection, table structure prediction, and assembly to process different batches simultaneously.
The architecture is designed for production workloads, featuring per-run isolation, explicit backpressure, and deterministic shutdown propagation.
Sources: docling/pipeline/standard_pdf_pipeline.py1-14
The StandardPdfPipeline implements a producer-consumer pattern where pages flow through sequential stages, each running in its own thread. Pages are wrapped in ThreadedItem envelopes that track run identifiers, error state, and the page payload. Bounded ThreadedQueue instances connect stages, providing natural backpressure when downstream stages cannot keep up.
execute() call uses its own bounded queues and worker threads so that concurrent invocations never share mutable state. docling/pipeline/standard_pdf_pipeline.py5-6itertools.count() instead of relying on id(), which may clash after garbage collection. docling/pipeline/standard_pdf_pipeline.py7-8 docling/pipeline/standard_pdf_pipeline.py484-493close() propagates downstream so stages terminate deterministically without sentinels. docling/pipeline/standard_pdf_pipeline.py9-10Sources: docling/pipeline/standard_pdf_pipeline.py1-14 docling/pipeline/standard_pdf_pipeline.py484-493
The ThreadedItem is the primary unit of work traveling through the pipeline.
Natural Language Space to Code Entity Space: Item Tracking
ThreadedItem (docling/pipeline/standard_pdf_pipeline.py110-120) wraps each page. The run_id field distinguishes pages from concurrent document conversions, the payload holds the Page object, and is_failed/error track processing failures. If a stage encounters an error, it marks is_failed=True, allowing the item to flow through remaining stages without further processing.
Sources: docling/pipeline/standard_pdf_pipeline.py110-120
The ThreadedQueue class implements a bounded, thread-safe queue with blocking operations and explicit closure semantics. docling/pipeline/standard_pdf_pipeline.py149-161
| Method | Behavior |
|---|---|
put(item, timeout) | Blocks until queue accepts item or is closed. Returns False if closed. docling/pipeline/standard_pdf_pipeline.py163-181 |
get_batch(size, timeout) | Returns up to size items. Blocks until ≥1 item present or queue closed. docling/pipeline/standard_pdf_pipeline.py184-201 |
close() | Marks queue closed and wakes all waiting threads. docling/pipeline/standard_pdf_pipeline.py204-209 |
The queue uses deque for efficient O(1) operations and threading.Lock with threading.Condition variables for blocking coordination. The _not_full condition guards against producer overflow, while _not_empty guards against consumer underflow. docling/pipeline/standard_pdf_pipeline.py154-159
Queue State Transitions
Sources: docling/pipeline/standard_pdf_pipeline.py149-215
Each processing stage is represented by a ThreadedPipelineStage instance. docling/pipeline/standard_pdf_pipeline.py216-217 It manages a background threading.Thread that groups incoming items by run_id to maximize batch coherence before invoking the model. docling/pipeline/standard_pdf_pipeline.py270-305
Sources: docling/pipeline/standard_pdf_pipeline.py216-352
The pipeline consists of several stages connected by queues. The StandardPdfPipeline defines these in its internal RunContext. docling/pipeline/standard_pdf_pipeline.py469-477
Natural Language Space to Code Entity Space: Pipeline Flow
Sources: docling/pipeline/standard_pdf_pipeline.py469-477 docling/pipeline/standard_pdf_pipeline.py586-643
PagePreprocessingModel to generate scaled images. docling/pipeline/standard_pdf_pipeline.py354-442BaseOcrModel implementations). docling/pipeline/standard_pdf_pipeline.py601-611TableFormer to predict structure for detected table regions. docling/pipeline/standard_pdf_pipeline.py625-635PageAssembleModel to combine clusters and cells into a structured representation. docling/pipeline/standard_pdf_pipeline.py637-643Sources: docling/pipeline/standard_pdf_pipeline.py354-442 docling/pipeline/standard_pdf_pipeline.py586-643
The main thread in _build_document() alternates between feeding pages into the first stage and draining results from the output queue to prevent deadlocks and manage memory. docling/pipeline/standard_pdf_pipeline.py676-742
Sources: docling/pipeline/standard_pdf_pipeline.py676-742
Sources: docling/pipeline/standard_pdf_pipeline.py646-760
Each execute() call generates a unique run_id and creates a fresh RunContext with new queues and threads. docling/pipeline/standard_pdf_pipeline.py484-493 docling/pipeline/standard_pdf_pipeline.py469-477 Heavy models are shared read-only across all runs. docling/pipeline/standard_pdf_pipeline.py11-12
Sources: docling/pipeline/standard_pdf_pipeline.py469-493 docling/pipeline/standard_pdf_pipeline.py586-643
When a stage encounters an exception, it marks all items in that batch as failed and records the failure details in ThreadedItem.failure. docling/pipeline/standard_pdf_pipeline.py307-342 Failed items continue flowing through downstream stages without further processing (short-circuiting), allowing the main thread to collect the error at the end. docling/pipeline/standard_pdf_pipeline.py293-301
Sources: docling/pipeline/standard_pdf_pipeline.py307-342
The document_timeout (in ThreadedPdfPipelineOptions) limits total processing time for a single document. docling/pipeline/standard_pdf_pipeline.py682-700
run_id is added to timed_out_run_ids. docling/pipeline/standard_pdf_pipeline.py685timed_out_run_ids and skip processing for items belonging to that run. docling/pipeline/standard_pdf_pipeline.py293-301Sources: docling/pipeline/standard_pdf_pipeline.py682-700 docling/pipeline/standard_pdf_pipeline.py293-301 docling/pipeline/standard_pdf_pipeline.py745-753
Configures the threaded behavior and batching of the pipeline. docling/datamodel/pipeline_options.py48
| Option | Default | Description |
|---|---|---|
layout_batch_size | 64 | Pages per layout model batch |
table_batch_size | 4 | Pages per table model batch |
ocr_batch_size | 64 | Pages per OCR batch |
queue_max_size | 512 | Maximum items in each stage queue |
document_timeout | None | Maximum seconds per document |
Sources: docling/datamodel/pipeline_options.py48 docling/pipeline/standard_pdf_pipeline.py586-643
The sequential LegacyStandardPdfPipeline (docling/pipeline/legacy_standard_pdf_pipeline.py48) processes batches such that only one model is active at a time across the entire pipeline. The threaded pipeline allows different models to process different batches simultaneously, significantly improving throughput on multi-core systems or systems with GPU acceleration.
The ThreadedStandardPdfPipeline (docling/pipeline/threaded_standard_pdf_pipeline.py4) is a direct alias for StandardPdfPipeline, indicating that the threaded implementation is the standard approach for PDF processing in Docling.
Sources: docling/pipeline/legacy_standard_pdf_pipeline.py48 docling/pipeline/threaded_standard_pdf_pipeline.py4 docling/pipeline/standard_pdf_pipeline.py1-14
Refresh this wiki