qubit_batch/lib.rs
1/*******************************************************************************
2 *
3 * Copyright (c) 2025 - 2026 Haixing Hu.
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 *
7 * Licensed under the Apache License, Version 2.0.
8 *
9 ******************************************************************************/
10//! Batch-oriented task execution utilities.
11//!
12//! This crate focuses on one-shot execution of whole task batches rather than
13//! single-task submission services.
14//!
15//! Core types are re-exported from the crate root, so callers can import the
16//! executor trait, result type, and concrete implementation together.
17//!
18//! ```rust
19//! use qubit_batch::{
20//! BatchExecutor,
21//! BatchOutcome,
22//! SequentialBatchExecutor,
23//! };
24//!
25//! let outcome: BatchOutcome<&'static str> = SequentialBatchExecutor::new()
26//! .for_each([1, 2, 3], |value| {
27//! assert!(value > 0);
28//! Ok::<(), &'static str>(())
29//! })
30//! .expect("array length should be exact");
31//!
32//! assert!(outcome.is_success());
33//! ```
34//!
35//! [`BatchExecutionState`] is public so runtime-specific executor crates can
36//! reuse the same accounting and outcome-building rules as the built-in
37//! executors.
38//!
39//! # Progress Interval Semantics
40//!
41//! Progress reporting has explicit lifecycle events plus optional running
42//! events. A `report_interval` is a throttle checked only when an implementation
43//! reaches one of its running-progress points; it is not a timer guarantee that
44//! a running event is emitted immediately when that duration passes. Passing
45//! [`std::time::Duration::ZERO`] disables time throttling, so each
46//! implementation-defined running-progress point reports as soon as it is
47//! reached. Sequential variants reach those points between tasks or items.
48//! Chunked processing reaches them after a chunk completes. Parallel variants
49//! report from a scoped reporter thread; with a positive interval they can also
50//! emit periodic running events while workers are active, while zero interval
51//! reports on worker completion signals and does not spin in a tight loop.
52//!
53
54#![deny(missing_docs)]
55#![deny(unsafe_op_in_unsafe_fn)]
56
57pub mod execute;
58pub mod process;
59pub(crate) mod utils;
60
61pub use execute::{
62 BatchCallResult,
63 BatchExecutionError,
64 BatchExecutionState,
65 BatchExecutor,
66 BatchOutcome,
67 BatchOutcomeBuildError,
68 BatchOutcomeBuilder,
69 BatchTaskError,
70 BatchTaskFailure,
71 ParallelBatchExecutor,
72 ParallelBatchExecutorBuildError,
73 ParallelBatchExecutorBuilder,
74 SequentialBatchExecutor,
75 SequentialBatchExecutorBuilder,
76};
77pub use process::{
78 BatchProcessError,
79 BatchProcessResult,
80 BatchProcessResultBuildError,
81 BatchProcessResultBuilder,
82 BatchProcessor,
83 ChunkedBatchProcessError,
84 ChunkedBatchProcessor,
85 ChunkedBatchProcessorBuilder,
86 ParallelBatchProcessor,
87 ParallelBatchProcessorBuildError,
88 ParallelBatchProcessorBuilder,
89 SequentialBatchProcessor,
90 SequentialBatchProcessorBuilder,
91};