qubit_executor/service/
executor_service.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9use std::future::Future;
10
11use qubit_function::{
12    Callable,
13    Runnable,
14};
15
16use super::{
17    RejectedExecution,
18    ShutdownReport,
19};
20
21/// Managed task service with submission and lifecycle control.
22///
23/// `ExecutorService` is intentionally separate from
24/// [`Executor`](crate::executor::Executor). An executor describes an
25/// execution strategy; an executor service accepts tasks into a managed service
26/// that may queue, schedule, assign workers, and track lifecycle.
27///
28/// `submit` and `submit_callable` return `Result` values whose outer `Ok`
29/// means only that the service accepted the task. It does **not** mean the task
30/// has started or succeeded. The task's final result is observed through the
31/// returned handle.
32///
33/// # Author
34///
35/// Haixing Hu
36pub trait ExecutorService: Send + Sync {
37    /// Handle returned for an accepted task.
38    type Handle<R, E>
39    where
40        R: Send + 'static,
41        E: Send + 'static;
42
43    /// Future returned when waiting for service termination.
44    type Termination<'a>: Future<Output = ()> + Send + 'a
45    where
46        Self: 'a;
47
48    /// Submits a runnable task to this service.
49    ///
50    /// # Parameters
51    ///
52    /// * `task` - A fallible background action with no business return value.
53    ///
54    /// # Returns
55    ///
56    /// `Ok(handle)` if the service accepts the task. This only reports
57    /// acceptance; it does not report task start or task success. Returns
58    /// `Err(RejectedExecution)` if the service refuses the task before
59    /// accepting it.
60    ///
61    /// # Errors
62    ///
63    /// Returns [`RejectedExecution`] when the service refuses the task before
64    /// accepting it.
65    #[inline]
66    fn submit<T, E>(&self, task: T) -> Result<Self::Handle<(), E>, RejectedExecution>
67    where
68        T: Runnable<E> + Send + 'static,
69        E: Send + 'static,
70    {
71        let mut task = task;
72        self.submit_callable(move || task.run())
73    }
74
75    /// Submits a callable task to this service.
76    ///
77    /// # Parameters
78    ///
79    /// * `task` - A fallible computation whose success value should be captured
80    ///   in the returned handle.
81    ///
82    /// # Returns
83    ///
84    /// `Ok(handle)` if the service accepts the task. This only reports
85    /// acceptance; task success, task failure, panic, or cancellation must be
86    /// observed through the returned handle. Returns `Err(RejectedExecution)` if
87    /// the service refuses the task before accepting it.
88    ///
89    /// # Errors
90    ///
91    /// Returns [`RejectedExecution`] when the service refuses the task before
92    /// accepting it.
93    fn submit_callable<C, R, E>(&self, task: C) -> Result<Self::Handle<R, E>, RejectedExecution>
94    where
95        C: Callable<R, E> + Send + 'static,
96        R: Send + 'static,
97        E: Send + 'static;
98
99    /// Initiates an orderly shutdown.
100    ///
101    /// After shutdown starts, new tasks are rejected. Already accepted tasks are
102    /// allowed to complete unless the concrete service documents stronger
103    /// cancellation behavior.
104    fn shutdown(&self);
105
106    /// Attempts to stop accepting and running tasks immediately.
107    ///
108    /// # Returns
109    ///
110    /// A count-based shutdown report describing the state observed at the time
111    /// of the request.
112    fn shutdown_now(&self) -> ShutdownReport;
113
114    /// Returns whether shutdown has been requested.
115    ///
116    /// # Returns
117    ///
118    /// `true` if this service is no longer accepting new tasks.
119    fn is_shutdown(&self) -> bool;
120
121    /// Returns whether the service has terminated.
122    ///
123    /// # Returns
124    ///
125    /// `true` only after shutdown has been requested and all accepted tasks have
126    /// completed or been cancelled.
127    fn is_terminated(&self) -> bool;
128
129    /// Waits until the service has terminated.
130    ///
131    /// # Returns
132    ///
133    /// A future that completes after shutdown has been requested and no accepted
134    /// tasks remain active.
135    fn await_termination(&self) -> Self::Termination<'_>;
136}
qubit_executor/service/executor_service.rs

qubit_executor/service/
executor_service.rs
