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

qubit_function/tasks/
callable_once.rs
