qubit_executor/executor/
executor.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_function::{
11    Callable,
12    Runnable,
13};
14
15use crate::{
16    TrackedTask,
17    service::SubmissionError,
18};
19
20/// Executes fallible one-time tasks according to an implementation-defined strategy.
21///
22/// `Executor` models an execution strategy, not a managed task service. An
23/// executor may run a task immediately, retry it, delay it, or schedule it on
24/// another runtime. Accepted task results are always exposed through a
25/// [`TrackedTask`]. The outer `Result` returned by [`Self::call`] and
26/// [`Self::execute`] reports submission failure only.
27///
28pub trait Executor: Send + Sync {
29    /// Submits a runnable task and returns a tracked task handle.
30    ///
31    /// This is the unit-returning counterpart of [`Self::call`]. The returned
32    /// carrier reports the runnable's `Result<(), E>` according to the concrete
33    /// executor's execution model.
34    ///
35    /// # Parameters
36    ///
37    /// * `task` - The fallible action to execute.
38    ///
39    /// # Returns
40    ///
41    /// A tracked handle for the accepted runnable.
42    ///
43    /// # Errors
44    ///
45    /// Returns [`SubmissionError`] if this executor cannot accept the runnable.
46    #[inline]
47    fn execute<T, E>(&self, task: T) -> Result<TrackedTask<(), E>, SubmissionError>
48    where
49        T: Runnable<E> + Send + 'static,
50        E: Send + 'static,
51    {
52        let mut task = task;
53        self.call(move || task.run())
54    }
55
56    /// Submits a callable task and returns a tracked task handle.
57    ///
58    /// # Parameters
59    ///
60    /// * `task` - The fallible computation to execute.
61    ///
62    /// # Returns
63    ///
64    /// A tracked handle for the accepted callable.
65    ///
66    /// # Errors
67    ///
68    /// Returns [`SubmissionError`] if this executor cannot accept the callable.
69    fn call<C, R, E>(&self, task: C) -> Result<TrackedTask<R, E>, SubmissionError>
70    where
71        C: Callable<R, E> + Send + 'static,
72        R: Send + 'static,
73        E: Send + 'static;
74}
qubit_executor/executor/executor.rs

qubit_executor/executor/
executor.rs
