qubit_function/tasks/
callable_once.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9//! # Callable Once Types
10//!
11//! Provides fallible, one-time, zero-argument computations.
12//!
13//! A `CallableOnce<R, E>` is equivalent to `FnOnce() -> Result<R, E>`, but uses
14//! task-oriented vocabulary. Use it when the operation is a computation or task
15//! whose success value matters. Use `RunnableOnce<E>` when the operation only
16//! needs to report success or failure.
17//!
18//! The trait itself does not require `Send`; concurrent executors should add
19//! `+ Send + 'static` at their API boundary.
20//!
21//! # Author
22//!
23//! Haixing Hu
24
25use crate::{
26    functions::macros::impl_function_debug_display,
27    macros::{
28        impl_box_once_conversions,
29        impl_closure_once_trait,
30        impl_common_name_methods,
31        impl_common_new_methods,
32    },
33    suppliers::supplier_once::SupplierOnce,
34    tasks::runnable_once::BoxRunnableOnce,
35};
36
37mod box_callable_once;
38pub use box_callable_once::BoxCallableOnce;
39
40// ============================================================================
41// CallableOnce Trait
42// ============================================================================
43
44/// A fallible one-time computation.
45///
46/// Conceptually this matches `FnOnce() -> Result<R, E>`: `call` consumes `self`
47/// and returns `Result<R, E>`, but the surface uses task-oriented naming and
48/// helpers instead of closure types. It is a semantic specialization of
49/// `SupplierOnce<Result<R, E>>` for executable computations and deferred tasks.
50///
51/// Choose **`CallableOnce`** when callers need the success value `R`. When only
52/// success or failure matters, use [`RunnableOnce`](crate::tasks::runnable_once::RunnableOnce),
53/// whose success type is `()`.
54///
55/// # Type Parameters
56///
57/// * `R` - The success value returned by the computation.
58/// * `E` - The error value returned when the computation fails.
59///
60/// # Examples
61///
62/// ```rust
63/// use qubit_function::{CallableOnce, BoxCallableOnce};
64///
65/// let task = || Ok::<i32, String>(21 * 2);
66/// assert_eq!(task.call(), Ok(42));
67/// ```
68///
69/// # Author
70///
71/// Haixing Hu
72pub trait CallableOnce<R, E> {
73    /// Executes the computation, consuming `self`.
74    ///
75    /// # Returns
76    ///
77    /// Returns `Ok(R)` when the computation succeeds, or `Err(E)` when it
78    /// fails. The exact error meaning is defined by the concrete callable.
79    fn call(self) -> Result<R, E>;
80
81    /// Converts this callable into a boxed callable.
82    ///
83    /// # Returns
84    ///
85    /// A `BoxCallableOnce<R, E>` that executes this callable when `call()` is
86    /// invoked.
87    fn into_box(self) -> BoxCallableOnce<R, E>
88    where
89        Self: Sized + 'static,
90    {
91        BoxCallableOnce::new(move || self.call())
92    }
93
94    /// Converts this callable into a closure.
95    ///
96    /// # Returns
97    ///
98    /// A closure implementing `FnOnce() -> Result<R, E>`.
99    fn into_fn(self) -> impl FnOnce() -> Result<R, E>
100    where
101        Self: Sized + 'static,
102    {
103        move || self.call()
104    }
105
106    /// Converts this callable into a boxed callable without consuming `self`.
107    ///
108    /// The method clones `self` and boxes the clone. Use this for cloneable
109    /// callable values that need to be reused after boxing.
110    ///
111    /// # Returns
112    ///
113    /// A new `BoxCallableOnce<R, E>` built from a clone of this callable.
114    fn to_box(&self) -> BoxCallableOnce<R, E>
115    where
116        Self: Clone + Sized + 'static,
117    {
118        self.clone().into_box()
119    }
120
121    /// Converts this callable into a closure without consuming `self`.
122    ///
123    /// The method clones `self` and returns a one-time closure that executes
124    /// the clone.
125    ///
126    /// # Returns
127    ///
128    /// A closure implementing `FnOnce() -> Result<R, E>`.
129    fn to_fn(&self) -> impl FnOnce() -> Result<R, E>
130    where
131        Self: Clone + Sized + 'static,
132    {
133        self.clone().into_fn()
134    }
135
136    /// Converts this callable into a runnable by discarding the success value.
137    ///
138    /// The returned runnable preserves errors and maps any `Ok(R)` to
139    /// `Ok(())`.
140    ///
141    /// # Returns
142    ///
143    /// A `BoxRunnableOnce<E>` that executes this callable and discards its
144    /// success value.
145    fn into_runnable(self) -> BoxRunnableOnce<E>
146    where
147        Self: Sized + 'static,
148    {
149        BoxRunnableOnce::new(move || self.call().map(|_| ()))
150    }
151}
qubit_function/tasks/callable_once.rs

qubit_function/tasks/
callable_once.rs
