Skip to content

A fast, helpful, and open-source document parser

feat: implement bounded sliding window for OCR tasks

Vivek Patel1d8a93c7c1db
diff --git a/crates/liteparse/src/ocr_merge.rs b/crates/liteparse/src/ocr_merge.rs
index 6ea2cbd..2a8a4b9 100644
--- a/crates/liteparse/src/ocr_merge.rs
+++ b/crates/liteparse/src/ocr_merge.rs
@@ -56,6 +56,136 @@ pub(crate) struct RenderedPage {
pub image_rects: Vec<ImageBounds>,
}
+type OcrTaskResult = Result<Vec<OcrResult>, Box<dyn std::error::Error + Send + Sync>>;
+type OcrTaskMetadata = (usize, usize, f32, (bool, Vec<ImageBounds>));
+type OcrTaskOutput = (usize, usize, f32, (bool, Vec<ImageBounds>), OcrTaskResult);
+
+#[cfg(not(target_arch = "wasm32"))]
+pub(crate) struct OcrTaskPool {
+ max_workers: usize,
+ engine: Arc<dyn OcrEngine>,
+ language: String,
+ tasks: tokio::task::JoinSet<OcrTaskOutput>,
+ task_metadata: HashMap<tokio::task::Id, OcrTaskMetadata>,
+ completed: Vec<OcrTaskOutput>,
+}
+
+#[cfg(not(target_arch = "wasm32"))]
+impl OcrTaskPool {
+ pub(crate) fn new(engine: Arc<dyn OcrEngine>, language: &str, num_workers: usize) -> Self {
+ Self {
+ max_workers: num_workers.max(1),
+ engine,
+ language: language.to_string(),
+ tasks: tokio::task::JoinSet::new(),
+ task_metadata: HashMap::new(),
+ completed: Vec::new(),
+ }
+ }
+
+ pub(crate) fn available_capacity(&self) -> usize {
+ self.max_workers - self.tasks.len()
+ }
+
+ pub(crate) fn submit(&mut self, rendered: RenderedPage, page_number: usize) {
+ assert!(
+ self.tasks.len() < self.max_workers,
+ "OCR task pool is at capacity"
+ );
+
+ let engine = self.engine.clone();
+ let language = self.language.clone();
+ let metadata = (
+ rendered.idx,
+ page_number,
+ rendered.dpi,
+ (rendered.has_native_text, rendered.image_rects.clone()),
+ );
+ let task_metadata = metadata.clone();
+ let runtime = tokio::runtime::Handle::current();
+ let task = self.tasks.spawn(async move {
+ let options = OcrOptions {
+ language,
+ dpi: rendered.dpi,
+ };
+ let result = match tokio::task::spawn_blocking(move || {
+ runtime.block_on(engine.recognize(
+ &rendered.pixels,
+ rendered.width,
+ rendered.height,
+ &options,
+ ))
+ })
+ .await
+ {
+ Ok(result) => result,
+ Err(join_err) => {
+ Err(Box::new(join_err) as Box<dyn std::error::Error + Send + Sync>)
+ }
+ };
+ (
+ task_metadata.0,
+ task_metadata.1,
+ task_metadata.2,
+ task_metadata.3,
+ result,
+ )
+ });
+ self.task_metadata.insert(task.id(), metadata);
+ }
+
+ pub(crate) async fn complete_one(&mut self) {
+ let joined = self
+ .tasks
+ .join_next_with_id()
+ .await
+ .expect("OCR task pool is empty");
+ self.record_completion(joined);
+ }
+
+ pub(crate) fn complete_ready(&mut self) {
+ while let Some(joined) = self.tasks.try_join_next_with_id() {
+ self.record_completion(joined);
+ }
+ }
+
+ fn record_completion(
+ &mut self,
+ joined: Result<(tokio::task::Id, OcrTaskOutput), tokio::task::JoinError>,
+ ) {
+ match joined {
+ Ok((id, output)) => {
+ self.task_metadata.remove(&id);
+ self.completed.push(output);
+ }
+ Err(join_err) => {
+ let metadata = self
+ .task_metadata
+ .remove(&join_err.id())
+ .expect("OCR task metadata is missing");
+ self.completed.push((
+ metadata.0,
+ metadata.1,
+ metadata.2,
+ metadata.3,
+ Err(Box::new(join_err)),
+ ));
+ }
+ }
+ }
+
+ pub(crate) async fn finish_and_merge(
+ mut self,
+ pages: &mut [Page],
+ ocr_failure_fatal: bool,
+ ) -> Result<(), LiteParseError> {
+ while !self.tasks.is_empty() {
+ self.complete_one().await;
+ }
+ merge_ocr_task_results(pages, self.completed, ocr_failure_fatal)
+ }
+}
+
/// Why a page was flagged as needing more than the cheap text-only path.
/// Multiple reasons can apply to one page (e.g. a sparse page whose little
/// text is also garbled). Empty exactly when `needs_ocr` is false.
@@ -724,6 +854,7 @@ pub(crate) fn render_pages_for_ocr(
}
/// Run OCR on pre-rendered page bitmaps and merge results into `pages`.
+#[cfg(any(target_arch = "wasm32", test))]
pub(crate) async fn ocr_and_merge_rendered(
pages: &mut [Page],
rendered: Vec<RenderedPage>,
@@ -732,8 +863,6 @@ pub(crate) async fn ocr_and_merge_rendered(
num_workers: usize,
ocr_failure_fatal: bool,
) -> Result<(), LiteParseError> {
- type OcrTaskResult = Result<Vec<OcrResult>, Box<dyn std::error::Error + Send + Sync>>;
-
// Browser WASM uses the JavaScript event loop. It has no Tokio runtime or
// blocking thread pool. Run each JavaScript OCR callback directly so the
// returned Promise can make progress on the browser event loop.
@@ -758,79 +887,29 @@ pub(crate) async fn ocr_and_merge_rendered(
results
};
- // Phase 1: spawn one async task per page. A semaphore limits how many run
- // `recognize` concurrently to `num_workers`.
- //
- // The permit MUST be acquired in async context (`acquire_owned().await`),
- // not inside `spawn_blocking` via `block_on`. Acquiring it on a blocking
- // thread parks that OS thread until a permit is free; with more pages than
- // tokio's blocking pool (default `max_blocking_threads = 512`), every pool
- // thread ends up parked waiting on the semaphore. The single task holding
- // the permit then calls `recognize`, whose HTTP client resolves DNS via its
- // own internal `spawn_blocking` — which can never get a thread, so the
- // request never goes out, the permit is never released, and the whole OCR
- // pass deadlocks. Acquiring the permit asynchronously parks the lightweight
- // task instead, so only `num_workers` blocking threads are ever consumed.
#[cfg(not(target_arch = "wasm32"))]
- let task_results: Vec<(usize, usize, f32, (bool, Vec<ImageBounds>), OcrTaskResult)> = {
- let num_workers = num_workers.max(1);
- let semaphore = Arc::new(tokio::sync::Semaphore::new(num_workers));
- let mut handles = Vec::with_capacity(rendered.len());
-
- let handle = tokio::runtime::Handle::current();
-
+ {
+ let mut tasks = OcrTaskPool::new(ocr_engine, ocr_language, num_workers);
for r in rendered {
- let engine = ocr_engine.clone();
- let sem = semaphore.clone();
- let language = ocr_language.to_string();
let page_number = pages[r.idx].page_number;
- let rt_handle = handle.clone();
-
- handles.push((
- r.idx,
- page_number,
- r.dpi,
- (r.has_native_text, r.image_rects.clone()),
- tokio::spawn(async move {
- // Park the task (not an OS thread) until a permit is available.
- let _permit = sem.acquire_owned().await.expect("semaphore closed");
- let options = OcrOptions {
- language,
- dpi: r.dpi,
- };
- // Offload the (possibly CPU-blocking, e.g. Tesseract) recognize
- // onto a blocking thread. Because the permit is already held,
- // at most `num_workers` blocking threads are in use at once,
- // leaving the rest of the pool free for the HTTP client's
- // internal DNS resolution.
- match tokio::task::spawn_blocking(move || {
- rt_handle.block_on(engine.recognize(&r.pixels, r.width, r.height, &options))
- })
- .await
- {
- Ok(result) => result,
- Err(join_err) => {
- Err(Box::new(join_err) as Box<dyn std::error::Error + Send + Sync>)
- }
- }
- }),
- ));
+ if tasks.available_capacity() == 0 {
+ tasks.complete_one().await;
+ }
+ tasks.submit(r, page_number);
}
+ return tasks.finish_and_merge(pages, ocr_failure_fatal).await;
+ }
- let mut results = Vec::with_capacity(handles.len());
- for (idx, page_number, page_dpi, native, handle) in handles {
- let result = match handle.await {
- Ok(result) => result,
- Err(join_err) => {
- Err(Box::new(join_err) as Box<dyn std::error::Error + Send + Sync>)
- }
- };
- results.push((idx, page_number, page_dpi, native, result));
- }
- results
- };
+ #[cfg(target_arch = "wasm32")]
+ merge_ocr_task_results(pages, task_results, ocr_failure_fatal)
+}
- // Phase 3: collect results and merge into pages.
+fn merge_ocr_task_results(
+ pages: &mut [Page],
+ task_results: Vec<OcrTaskOutput>,
+ ocr_failure_fatal: bool,
+) -> Result<(), LiteParseError> {
+ // Collect results and merge them into their source pages.
// Track OCR task outcomes so we can distinguish a systemic failure (e.g.
// missing Tesseract language data, which fails identically on every page)
diff --git a/crates/liteparse/src/parser.rs b/crates/liteparse/src/parser.rs
index ed364ce..0574d46 100644
--- a/crates/liteparse/src/parser.rs
+++ b/crates/liteparse/src/parser.rs
@@ -798,10 +798,9 @@ impl LiteParse {
let t1 = web_time::Instant::now();
if let Some(engine) = ocr_engine {
- let round_rasters = self.config.num_workers.max(1);
// Extraction may have flattened SOME pages' form widgets into
- // page content in its (now dropped) document instance; re-apply
- // per round on exactly those pages so the rasters match what
+ // page content in its (now dropped) document instance; re-apply on
+ // exactly those pages so the rasters match what
// extraction saw. With `render_form_fields` the form environment
// paints the widgets instead, so no re-flatten is needed.
let reflatten_pages: std::collections::HashSet<u32> =
@@ -811,16 +810,67 @@ impl LiteParse {
std::collections::HashSet::new()
};
let ocr_input = repaired_input.as_ref().unwrap_or(validated_input);
- let mut round_start = 0usize;
- while round_start < pages.len() {
+ let mut scan_start = 0usize;
+
+ #[cfg(not(target_arch = "wasm32"))]
+ let mut ocr_tasks = ocr_merge::OcrTaskPool::new(
+ engine.clone(),
+ &self.config.ocr_language,
+ self.config.num_workers,
+ );
+ #[cfg(not(target_arch = "wasm32"))]
+ loop {
+ // Reap completions before deciding whether to render so every
+ // available worker can be refilled immediately.
+ ocr_tasks.complete_ready();
+
+ if scan_start >= pages.len() {
+ break;
+ }
+
+ let render_capacity = ocr_tasks.available_capacity();
+ if render_capacity == 0 {
+ ocr_tasks.complete_one().await;
+ continue;
+ }
+
+ let (rendered, next_start) = {
+ let lib = Library::init();
+ let document = self.open_document(&lib, ocr_input, password)?;
+ ocr_merge::render_pages_for_ocr(
+ &document,
+ &pages,
+ scan_start,
+ render_capacity,
+ self.config.dpi,
+ ocr_grayscale,
+ self.config.render_form_fields,
+ self.config.continue_on_page_error,
+ &reflatten_pages,
+ )?
+ // `lib` drops here, releasing the PDFium lock before the
+ // next await.
+ };
+ scan_start = next_start;
+
+ for page in rendered {
+ let page_number = pages[page.idx].page_number;
+ ocr_tasks.submit(page, page_number);
+ }
+ }
+
+ #[cfg(target_arch = "wasm32")]
+ while scan_start < pages.len() {
+ let render_capacity = self.config.num_workers.max(1);
+
let (rendered, next_start) = {
let lib = Library::init();
let document = self.open_document(&lib, ocr_input, password)?;
ocr_merge::render_pages_for_ocr(
&document,
&pages,
- round_start,
- round_rasters,
+ scan_start,
+ render_capacity,
self.config.dpi,
ocr_grayscale,
self.config.render_form_fields,
@@ -830,14 +880,14 @@ impl LiteParse {
// `lib` drops here, releasing the PDFium lock before the
// engine's async recognition below.
};
- round_start = next_start;
+ scan_start = next_start;
if rendered.is_empty() {
// The scan reached the end without finding another page
// that needs OCR.
continue;
}
- // `RenderedPage::idx` is absolute, so the whole slice is
- // passed regardless of where this round started.
+
+ // Browser callbacks run serially on the JavaScript event loop.
ocr_merge::ocr_and_merge_rendered(
&mut pages,
rendered,
@@ -848,6 +898,11 @@ impl LiteParse {
)
.await?;
}
+
+ #[cfg(not(target_arch = "wasm32"))]
+ ocr_tasks
+ .finish_and_merge(&mut pages, self.config.ocr_failure_fatal)
+ .await?;
}
let t_ocr = web_time::Instant::now();
log(&format!(
diff --git a/crates/liteparse/tests/integration_test.rs b/crates/liteparse/tests/integration_test.rs
index 1b0e5eb..658f61d 100644
--- a/crates/liteparse/tests/integration_test.rs
+++ b/crates/liteparse/tests/integration_test.rs
@@ -741,14 +741,106 @@ impl liteparse::ocr::OcrEngine for ProbeEngine {
}
}
-/// OCR runs in render→recognize rounds of `num_workers` pages. Whatever the
-/// round size, every page must be recognized exactly once and each page's OCR
-/// text must land on the page whose raster produced it — distinct page sizes
-/// make a misroute visible, which is the failure mode the per-round document
-/// reopen and form-widget re-flatten could introduce. `num_workers: 1` forces
-/// one page per round (four rounds over four pages) and must also serialize
-/// recognition; `num_workers: 4` covers the whole document in a single round
-/// with overlapping recognition. Both must agree page-for-page.
+struct RefillProbeEngine {
+ calls: std::sync::Arc<std::sync::atomic::AtomicUsize>,
+ in_flight: std::sync::Arc<std::sync::atomic::AtomicUsize>,
+ peak_in_flight: std::sync::Arc<std::sync::atomic::AtomicUsize>,
+ first_in_flight: std::sync::Arc<std::sync::atomic::AtomicBool>,
+ refilled_while_first_in_flight: std::sync::Arc<std::sync::atomic::AtomicBool>,
+}
+
+impl liteparse::ocr::OcrEngine for RefillProbeEngine {
+ fn name(&self) -> &str {
+ "refill-probe"
+ }
+
+ fn recognize<'a, 'b: 'a, 'c: 'a>(
+ &'a self,
+ _image_data: &'c [u8],
+ _width: u32,
+ _height: u32,
+ _options: &'b liteparse::ocr::OcrOptions,
+ ) -> std::pin::Pin<
+ Box<
+ dyn Future<
+ Output = Result<
+ Vec<liteparse::ocr::OcrResult>,
+ Box<dyn std::error::Error + Send + Sync>,
+ >,
+ > + Send
+ + '_,
+ >,
+ > {
+ use std::sync::atomic::Ordering;
+
+ let call = self.calls.fetch_add(1, Ordering::SeqCst);
+ let active = self.in_flight.fetch_add(1, Ordering::SeqCst) + 1;
+ self.peak_in_flight.fetch_max(active, Ordering::SeqCst);
+ if call == 0 {
+ self.first_in_flight.store(true, Ordering::SeqCst);
+ } else if call >= 2 && self.first_in_flight.load(Ordering::SeqCst) {
+ self.refilled_while_first_in_flight
+ .store(true, Ordering::SeqCst);
+ }
+
+ let first_in_flight = self.first_in_flight.clone();
+ let in_flight = self.in_flight.clone();
+ Box::pin(async move {
+ if call == 0 {
+ tokio::time::sleep(std::time::Duration::from_millis(200)).await;
+ first_in_flight.store(false, Ordering::SeqCst);
+ } else {
+ tokio::time::sleep(std::time::Duration::from_millis(20)).await;
+ }
+ in_flight.fetch_sub(1, Ordering::SeqCst);
+ Ok(Vec::new())
+ })
+ }
+}
+
+#[tokio::test]
+#[serial]
+async fn test_ocr_worker_is_refilled_before_slowest_request_finishes() {
+ use std::sync::Arc;
+ use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+
+ let calls = Arc::new(AtomicUsize::new(0));
+ let peak = Arc::new(AtomicUsize::new(0));
+ let refilled = Arc::new(AtomicBool::new(false));
+ let parser = LiteParse::new(LiteParseConfig {
+ ocr_enabled: true,
+ num_workers: 2,
+ dpi: 72.0,
+ quiet: true,
+ ..Default::default()
+ })
+ .with_ocr_engine(Arc::new(RefillProbeEngine {
+ calls: calls.clone(),
+ in_flight: Arc::new(AtomicUsize::new(0)),
+ peak_in_flight: peak.clone(),
+ first_in_flight: Arc::new(AtomicBool::new(false)),
+ refilled_while_first_in_flight: refilled.clone(),
+ }));
+
+ parser
+ .parse_input(PdfInput::Bytes(blank_pdf(&[(200, 200); 4])))
+ .await
+ .expect("OCR parse should succeed");
+
+ assert_eq!(calls.load(Ordering::SeqCst), 4);
+ assert_eq!(peak.load(Ordering::SeqCst), 2);
+ assert!(
+ refilled.load(Ordering::SeqCst),
+ "a free OCR worker should start the next page without waiting for the slowest request"
+ );
+}
+
+/// OCR keeps a bounded window of `num_workers` rendered pages. Every page must
+/// be recognized exactly once and each page's OCR text must land on the page
+/// whose raster produced it — distinct page sizes make a misroute visible when
+/// the document is reopened to refill the window. `num_workers: 1` serializes
+/// recognition; `num_workers: 4` overlaps the whole four-page document. Both
+/// must agree page-for-page.
#[tokio::test]
#[serial]
async fn test_ocr_rounds_cover_every_page_once() {
@@ -804,7 +896,7 @@ async fn test_ocr_rounds_cover_every_page_once() {
}
};
- // One page per round: four rounds, recognition fully serialized.
+ // A one-page window keeps recognition fully serialized.
let (parser, calls, peak) = run(1);
let serialized = parser
.parse_input(PdfInput::Bytes(blank_pdf(&page_sizes)))
@@ -822,8 +914,8 @@ async fn test_ocr_rounds_cover_every_page_once() {
"num_workers=1 must serialize recognition"
);
- // Round wide enough for the whole document: one round, overlapping
- // recognition, identical routing.
+ // A window wide enough for the document overlaps recognition while
+ // preserving identical routing.
let (parser, calls, peak) = run(4);
let overlapped = parser
.parse_input(PdfInput::Bytes(blank_pdf(&page_sizes)))
@@ -837,9 +929,9 @@ async fn test_ocr_rounds_cover_every_page_once() {
);
}
-/// A round is bounded by rasters rendered, not by page span, so OCR-needing
-/// pages that are sparsely scattered through a mostly-native-text document
-/// still fill a round and recognize concurrently.
+/// The initial window is bounded by rasters rendered, not by page span, so
+/// OCR-needing pages sparsely scattered through a mostly-native-text document
+/// still fill the worker pool and recognize concurrently.
///
/// This guards a real regression: bounding the round by page span instead
/// made each round contain only the OCR-needing pages that happened to fall
@@ -883,13 +975,13 @@ async fn test_ocr_rounds_fill_across_sparse_pages() {
among its {} pages",
result.pages.len()
);
- // The scan-ahead must gather a full round even though the OCR-needing
+ // The scan-ahead must fill the worker pool even though the OCR-needing
// pages are interleaved with native-text pages it skips.
assert_eq!(
peak.load(Ordering::SeqCst),
8,
- "rounds must fill to num_workers across skipped pages; a lower peak means \
- rounds are being cut short by page span"
+ "the OCR window must fill to num_workers across skipped pages; a lower peak means \
+ the window is being cut short by page span"
);
}