qubit_function/tasks/runnable_once/
box_runnable_once.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9//! Defines the `BoxRunnableOnce` public type.
10
11#![allow(unused_imports)]
12
13use super::*;
14
15// ============================================================================
16// BoxRunnableOnce
17// ============================================================================
18
19/// Box-based one-time runnable.
20///
21/// `BoxRunnableOnce<E>` stores a `Box<dyn FnOnce() -> Result<(), E>>` and can be
22/// executed only once. It is the boxed concrete implementation of
23/// [`RunnableOnce`].
24///
25/// # Type Parameters
26///
27/// * `E` - The error value returned when the action fails.
28///
29/// # Examples
30///
31/// ```rust
32/// use qubit_function::{BoxRunnableOnce, RunnableOnce};
33///
34/// let task = BoxRunnableOnce::new(|| Ok::<(), String>(()));
35/// assert_eq!(task.run(), Ok(()));
36/// ```
37///
38/// # Author
39///
40/// Haixing Hu
41pub struct BoxRunnableOnce<E> {
42    /// The one-time closure executed by this runnable.
43    pub(super) function: Box<dyn FnOnce() -> Result<(), E>>,
44    /// The optional name of this runnable.
45    pub(super) name: Option<String>,
46}
47
48impl<E> BoxRunnableOnce<E> {
49    impl_common_new_methods!(
50        (FnOnce() -> Result<(), E> + 'static),
51        |function| Box::new(function),
52        "runnable"
53    );
54
55    /// Creates a boxed runnable from a one-time supplier.
56    ///
57    /// This is an explicit bridge from `SupplierOnce<Result<(), E>>` to
58    /// `RunnableOnce<E>`.
59    ///
60    /// # Parameters
61    ///
62    /// * `supplier` - The supplier that produces the runnable result.
63    ///
64    /// # Returns
65    ///
66    /// A new `BoxRunnableOnce<E>`.
67    #[inline]
68    pub fn from_supplier<S>(supplier: S) -> Self
69    where
70        S: SupplierOnce<Result<(), E>> + 'static,
71    {
72        Self::new(move || supplier.get())
73    }
74
75    impl_common_name_methods!("runnable");
76
77    /// Chains another runnable after this runnable succeeds.
78    ///
79    /// The second runnable is not executed if this runnable returns `Err`.
80    ///
81    /// # Parameters
82    ///
83    /// * `next` - The runnable to execute after this runnable succeeds.
84    ///
85    /// # Returns
86    ///
87    /// A new runnable executing both actions in sequence.
88    #[inline]
89    pub fn and_then<N>(self, next: N) -> BoxRunnableOnce<E>
90    where
91        N: RunnableOnce<E> + 'static,
92        E: 'static,
93    {
94        let name = self.name;
95        let function = self.function;
96        BoxRunnableOnce::new_with_optional_name(
97            move || {
98                function()?;
99                next.run()
100            },
101            name,
102        )
103    }
104
105    /// Runs this runnable before a callable.
106    ///
107    /// The callable is not executed if this runnable returns `Err`.
108    ///
109    /// # Parameters
110    ///
111    /// * `callable` - The callable to execute after this runnable succeeds.
112    ///
113    /// # Returns
114    ///
115    /// A callable producing the second computation's result.
116    #[inline]
117    pub fn then_callable<R, C>(self, callable: C) -> BoxCallableOnce<R, E>
118    where
119        C: CallableOnce<R, E> + 'static,
120        R: 'static,
121        E: 'static,
122    {
123        let name = self.name;
124        let function = self.function;
125        BoxCallableOnce::new_with_optional_name(
126            move || {
127                function()?;
128                callable.call()
129            },
130            name,
131        )
132    }
133}
134
135impl<E> RunnableOnce<E> for BoxRunnableOnce<E> {
136    /// Executes the boxed runnable.
137    #[inline]
138    fn run(self) -> Result<(), E> {
139        (self.function)()
140    }
141
142    impl_box_once_conversions!(BoxRunnableOnce<E>, RunnableOnce, FnOnce() -> Result<(), E>);
143
144    /// Converts this boxed runnable into a boxed callable while preserving its
145    /// name.
146    #[inline]
147    fn into_callable(self) -> BoxCallableOnce<(), E>
148    where
149        Self: Sized + 'static,
150    {
151        let name = self.name;
152        let function = self.function;
153        BoxCallableOnce::new_with_optional_name(function, name)
154    }
155}
156
157impl<E> SupplierOnce<Result<(), E>> for BoxRunnableOnce<E> {
158    /// Executes the boxed runnable as a one-time supplier of `Result<(), E>`.
159    #[inline]
160    fn get(self) -> Result<(), E> {
161        self.run()
162    }
163}
164
165impl_closure_once_trait!(
166    RunnableOnce<E>,
167    run,
168    BoxRunnableOnce,
169    FnOnce() -> Result<(), E>
170);
171
172impl_supplier_debug_display!(BoxRunnableOnce<E>);
qubit_function/tasks/runnable_once/box_runnable_once.rs

qubit_function/tasks/runnable_once/
box_runnable_once.rs
