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::tasks::runnable_once::{
24    BoxRunnableOnce,
25    LocalBoxRunnableOnce,
26};
27
28mod box_callable_once;
29pub use box_callable_once::BoxCallableOnce;
30mod local_box_callable_once;
31pub use local_box_callable_once::LocalBoxCallableOnce;
32
33// ============================================================================
34// CallableOnce Trait
35// ============================================================================
36
37/// A fallible one-time computation.
38///
39/// Conceptually this matches `FnOnce() -> Result<R, E>`: `call` consumes `self`
40/// and returns `Result<R, E>`, but the surface uses task-oriented naming and
41/// helpers instead of closure types. It is a semantic specialization of
42/// `SupplierOnce<Result<R, E>>` for executable computations and deferred tasks.
43///
44/// Choose **`CallableOnce`** when callers need the success value `R`. When only
45/// success or failure matters, use [`RunnableOnce`](crate::tasks::runnable_once::RunnableOnce),
46/// whose success type is `()`.
47///
48/// # Type Parameters
49///
50/// * `R` - The success value returned by the computation.
51/// * `E` - The error value returned when the computation fails.
52///
53/// # Examples
54///
55/// ```rust
56/// use qubit_function::{CallableOnce, BoxCallableOnce};
57///
58/// let task = || Ok::<i32, String>(21 * 2);
59/// assert_eq!(task.call(), Ok(42));
60/// ```
61///
62pub trait CallableOnce<R, E> {
63    /// Executes the computation, consuming `self`.
64    ///
65    /// # Returns
66    ///
67    /// Returns `Ok(R)` when the computation succeeds, or `Err(E)` when it
68    /// fails. The exact error meaning is defined by the concrete callable.
69    fn call(self) -> Result<R, E>;
70
71    /// Converts this callable into a boxed callable.
72    ///
73    /// # Returns
74    ///
75    /// A `BoxCallableOnce<R, E>` that executes this callable when `call()` is
76    /// invoked.
77    fn into_box(self) -> BoxCallableOnce<R, E>
78    where
79        Self: Sized + Send + 'static,
80    {
81        BoxCallableOnce::new(move || self.call())
82    }
83
84    /// Converts this callable into a local boxed callable.
85    ///
86    /// # Returns
87    ///
88    /// A `LocalBoxCallableOnce<R, E>` that may hold non-`Send` captures and
89    /// must be executed on the local thread.
90    fn into_local_box(self) -> LocalBoxCallableOnce<R, E>
91    where
92        Self: Sized + 'static,
93    {
94        LocalBoxCallableOnce::new(move || self.call())
95    }
96
97    /// Converts this callable into a closure.
98    ///
99    /// # Returns
100    ///
101    /// A closure implementing `FnOnce() -> Result<R, E>`.
102    fn into_fn(self) -> impl FnOnce() -> Result<R, E>
103    where
104        Self: Sized + 'static,
105    {
106        move || self.call()
107    }
108
109    /// Converts this callable into a boxed callable without consuming `self`.
110    ///
111    /// The method clones `self` and boxes the clone. Use this for cloneable
112    /// callable values that need to be reused after boxing.
113    ///
114    /// # Returns
115    ///
116    /// A new `BoxCallableOnce<R, E>` built from a clone of this callable.
117    fn to_box(&self) -> BoxCallableOnce<R, E>
118    where
119        Self: Clone + Send + Sized + 'static,
120    {
121        self.clone().into_box()
122    }
123
124    /// Converts this callable into a local boxed callable without consuming
125    /// `self`.
126    ///
127    /// The method clones `self` and boxes the clone without requiring `Send`.
128    ///
129    /// # Returns
130    ///
131    /// A new `LocalBoxCallableOnce<R, E>` built from a clone of this callable.
132    fn to_local_box(&self) -> LocalBoxCallableOnce<R, E>
133    where
134        Self: Clone + Sized + 'static,
135    {
136        self.clone().into_local_box()
137    }
138
139    /// Converts this callable into a closure without consuming `self`.
140    ///
141    /// The method clones `self` and returns a one-time closure that executes
142    /// the clone.
143    ///
144    /// # Returns
145    ///
146    /// A closure implementing `FnOnce() -> Result<R, E>`.
147    fn to_fn(&self) -> impl FnOnce() -> Result<R, E>
148    where
149        Self: Clone + Sized + 'static,
150    {
151        self.clone().into_fn()
152    }
153
154    /// Converts this callable into a runnable by discarding the success value.
155    ///
156    /// The returned runnable preserves errors and maps any `Ok(R)` to
157    /// `Ok(())`.
158    ///
159    /// # Returns
160    ///
161    /// A `BoxRunnableOnce<E>` that executes this callable and discards its
162    /// success value.
163    fn into_runnable(self) -> BoxRunnableOnce<E>
164    where
165        Self: Sized + Send + 'static,
166    {
167        BoxRunnableOnce::new(move || self.call().map(|_| ()))
168    }
169
170    /// Converts this callable into a local runnable by discarding the success
171    /// value.
172    ///
173    /// # Returns
174    ///
175    /// A `LocalBoxRunnableOnce<E>` that may hold non-`Send` captures and maps
176    /// any `Ok(R)` to `Ok(())`.
177    fn into_local_runnable(self) -> LocalBoxRunnableOnce<E>
178    where
179        Self: Sized + 'static,
180    {
181        LocalBoxRunnableOnce::new(move || self.call().map(|_| ()))
182    }
183}
qubit_function/tasks/callable_once.rs

qubit_function/tasks/
callable_once.rs
