qubit_function/tasks/
callable_with.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//! # CallableWith Types
11//!
12//! Provides fallible, reusable computations that operate on a mutable input.
13//!
14//! A `CallableWith<T, R, E>` is equivalent to
15//! `FnMut(&mut T) -> Result<R, E>`, but uses task-oriented vocabulary. Use it
16//! when the operation needs access to protected or caller-provided state and
17//! returns a success value.
18//!
19//! The trait itself does not require `Send`; concurrent executors should add
20//! `+ Send + 'static` at their API boundary.
21//!
22
23use std::cell::RefCell;
24use std::rc::Rc;
25use std::sync::Arc;
26
27use parking_lot::Mutex;
28
29use crate::{
30    functions::macros::impl_function_debug_display,
31    macros::{
32        impl_arc_conversions,
33        impl_box_conversions,
34        impl_closure_trait,
35        impl_common_name_methods,
36        impl_common_new_methods,
37        impl_rc_conversions,
38    },
39    tasks::runnable_with::BoxRunnableWith,
40};
41
42mod box_callable_with;
43pub use box_callable_with::BoxCallableWith;
44mod rc_callable_with;
45pub use rc_callable_with::RcCallableWith;
46mod arc_callable_with;
47pub use arc_callable_with::ArcCallableWith;
48
49/// A fallible, reusable computation that receives mutable input.
50///
51/// Conceptually this is `FnMut(&mut T) -> Result<R, E>` with task-oriented
52/// naming. It is useful for executor-style APIs that run a task with access to
53/// protected state, such as a value held under a lock.
54///
55/// # Type Parameters
56///
57/// * `T` - The mutable input type.
58/// * `R` - The success value returned by the computation.
59/// * `E` - The error value returned when the computation fails.
60///
61pub trait CallableWith<T, R, E> {
62    /// Executes the computation with mutable input.
63    ///
64    /// # Parameters
65    ///
66    /// * `input` - The mutable input passed to this task.
67    ///
68    /// # Returns
69    ///
70    /// Returns `Ok(R)` when the computation succeeds, or `Err(E)` when it
71    /// fails. The exact error meaning is defined by the concrete callable.
72    fn call_with(&mut self, input: &mut T) -> Result<R, E>;
73
74    /// Converts this callable into a boxed callable.
75    ///
76    /// # Returns
77    ///
78    /// A `BoxCallableWith<T, R, E>`.
79    fn into_box(mut self) -> BoxCallableWith<T, R, E>
80    where
81        Self: Sized + 'static,
82    {
83        BoxCallableWith::new(move |input| self.call_with(input))
84    }
85
86    /// Converts this callable into an `Rc` callable.
87    ///
88    /// # Returns
89    ///
90    /// A `RcCallableWith<T, R, E>`.
91    fn into_rc(mut self) -> RcCallableWith<T, R, E>
92    where
93        Self: Sized + 'static,
94    {
95        RcCallableWith::new(move |input| self.call_with(input))
96    }
97
98    /// Converts this callable into an `Arc` callable.
99    ///
100    /// # Returns
101    ///
102    /// An `ArcCallableWith<T, R, E>`.
103    fn into_arc(mut self) -> ArcCallableWith<T, R, E>
104    where
105        Self: Sized + Send + 'static,
106    {
107        ArcCallableWith::new(move |input| self.call_with(input))
108    }
109
110    /// Converts this callable into a mutable closure.
111    ///
112    /// # Returns
113    ///
114    /// A closure implementing `FnMut(&mut T) -> Result<R, E>`.
115    fn into_fn(mut self) -> impl FnMut(&mut T) -> Result<R, E>
116    where
117        Self: Sized + 'static,
118    {
119        move |input| self.call_with(input)
120    }
121
122    /// Converts this callable into a boxed callable without consuming `self`.
123    ///
124    /// # Returns
125    ///
126    /// A `BoxCallableWith<T, R, E>` built from a clone of this callable.
127    fn to_box(&self) -> BoxCallableWith<T, R, E>
128    where
129        Self: Clone + Sized + 'static,
130    {
131        self.clone().into_box()
132    }
133
134    /// Converts this callable into an `Rc` callable without consuming `self`.
135    ///
136    /// # Returns
137    ///
138    /// A `RcCallableWith<T, R, E>` built from a clone of this callable.
139    fn to_rc(&self) -> RcCallableWith<T, R, E>
140    where
141        Self: Clone + Sized + 'static,
142    {
143        self.clone().into_rc()
144    }
145
146    /// Converts this callable into an `Arc` callable without consuming `self`.
147    ///
148    /// # Returns
149    ///
150    /// An `ArcCallableWith<T, R, E>` built from a clone of this callable.
151    fn to_arc(&self) -> ArcCallableWith<T, R, E>
152    where
153        Self: Clone + Send + Sized + 'static,
154    {
155        self.clone().into_arc()
156    }
157
158    /// Converts this callable into a mutable closure without consuming `self`.
159    ///
160    /// # Returns
161    ///
162    /// A closure implementing `FnMut(&mut T) -> Result<R, E>`.
163    fn to_fn(&self) -> impl FnMut(&mut T) -> Result<R, E>
164    where
165        Self: Clone + Sized + 'static,
166    {
167        self.clone().into_fn()
168    }
169
170    /// Converts this callable into a runnable by discarding the success value.
171    ///
172    /// # Returns
173    ///
174    /// A `BoxRunnableWith<T, E>` preserving errors and mapping success to unit.
175    fn into_runnable_with(mut self) -> BoxRunnableWith<T, E>
176    where
177        Self: Sized + 'static,
178    {
179        BoxRunnableWith::new(move |input| self.call_with(input).map(|_| ()))
180    }
181}
qubit_function/tasks/callable_with.rs

qubit_function/tasks/
callable_with.rs
