qubit_task/service/
task_execution_service_builder.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 ******************************************************************************/
10use qubit_thread_pool::{
11    ExecutorServiceBuilderError,
12    ThreadPoolBuilder,
13};
14
15use super::task_execution_service::TaskExecutionService;
16
17/// Builder for [`TaskExecutionService`], used to configure the backing [`super::ThreadPool`]
18/// before the service is created.
19///
20/// # Design
21///
22/// Configuration is delegated to [`ThreadPoolBuilder`] (pool sizes, queue capacity,
23/// thread name prefix, and so on). This type exists so future **service-level** options
24/// can be added without pushing every thread-pool construction detail onto
25/// [`TaskExecutionService`].
26///
27/// # Relation to [`TaskExecutionService::builder`]
28///
29/// [`TaskExecutionService::builder`] returns `TaskExecutionServiceBuilder::default()`.
30/// For default pool settings you can use [`TaskExecutionService::new`] or
31/// `TaskExecutionService::builder().build()`.
32///
33/// # Example: custom pool, then build the service
34///
35/// ```
36/// use qubit_task::service::{
37///     TaskExecutionServiceBuilder, ThreadPoolBuilder, ExecutorServiceBuilderError,
38/// };
39///
40/// fn main() -> Result<(), ExecutorServiceBuilderError> {
41///     let _service = TaskExecutionServiceBuilder::default()
42///         .thread_pool(
43///             ThreadPoolBuilder::default()
44///                 .pool_size(4)
45///                 .queue_capacity(256),
46///         )
47///         .build()?;
48///     Ok(())
49/// }
50/// ```
51///
52#[derive(Debug, Default, Clone)]
53pub struct TaskExecutionServiceBuilder {
54    pool_builder: ThreadPoolBuilder,
55}
56
57impl TaskExecutionServiceBuilder {
58    /// Sets the [`ThreadPoolBuilder`] used when [`Self::build`] creates the pool.
59    ///
60    /// # Example
61    ///
62    /// ```
63    /// use qubit_task::service::{
64    ///     TaskExecutionServiceBuilder, ThreadPoolBuilder, ExecutorServiceBuilderError,
65    /// };
66    ///
67    /// fn main() -> Result<(), ExecutorServiceBuilderError> {
68    ///     let _service = TaskExecutionServiceBuilder::default()
69    ///         .thread_pool(ThreadPoolBuilder::default().pool_size(2))
70    ///         .build()?;
71    ///     Ok(())
72    /// }
73    /// ```
74    ///
75    /// # Parameters
76    ///
77    /// * `pool_builder` - Builder that produces the backing [`super::ThreadPool`].
78    ///
79    /// # Returns
80    ///
81    /// `self` for fluent configuration.
82    #[inline]
83    pub fn thread_pool(mut self, pool_builder: ThreadPoolBuilder) -> Self {
84        self.pool_builder = pool_builder;
85        self
86    }
87
88    /// Builds a [`TaskExecutionService`] from the current configuration.
89    ///
90    /// # Example
91    ///
92    /// ```
93    /// use qubit_task::service::{TaskExecutionServiceBuilder, ExecutorServiceBuilderError};
94    ///
95    /// fn main() -> Result<(), ExecutorServiceBuilderError> {
96    ///     let _service = TaskExecutionServiceBuilder::default().build()?;
97    ///     Ok(())
98    /// }
99    /// ```
100    ///
101    /// # Returns
102    ///
103    /// `Ok(TaskExecutionService)` when [`ThreadPoolBuilder`] settings are valid and
104    /// workers start successfully; otherwise [`ExecutorServiceBuilderError`].
105    pub fn build(self) -> Result<TaskExecutionService, ExecutorServiceBuilderError> {
106        let pool = self.pool_builder.build()?;
107        Ok(TaskExecutionService::from_thread_pool(pool))
108    }
109}
qubit_task/service/task_execution_service_builder.rs

qubit_task/service/
task_execution_service_builder.rs
