qubit_function/tasks/
runnable_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//! # RunnableWith Types
11//!
12//! Provides fallible, reusable actions that operate on a mutable input.
13//!
14//! A `RunnableWith<T, E>` is equivalent to
15//! `FnMut(&mut T) -> Result<(), E>`, but uses task-oriented vocabulary. Use it
16//! when the operation needs access to protected or caller-provided state and
17//! only success or failure should be reported.
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::callable_with::BoxCallableWith,
40};
41
42mod box_runnable_with;
43pub use box_runnable_with::BoxRunnableWith;
44mod rc_runnable_with;
45pub use rc_runnable_with::RcRunnableWith;
46mod arc_runnable_with;
47pub use arc_runnable_with::ArcRunnableWith;
48
49/// A fallible, reusable action that receives mutable input.
50///
51/// Conceptually this is `FnMut(&mut T) -> Result<(), E>` with task-oriented
52/// naming. It is useful for executor-style APIs that run an action with access
53/// to protected state, such as a value held under a lock.
54///
55/// # Type Parameters
56///
57/// * `T` - The mutable input type.
58/// * `E` - The error value returned when the action fails.
59///
60pub trait RunnableWith<T, E> {
61    /// Executes the action with mutable input.
62    ///
63    /// # Parameters
64    ///
65    /// * `input` - The mutable input passed to this task.
66    ///
67    /// # Returns
68    ///
69    /// Returns `Ok(())` when the action succeeds, or `Err(E)` when it fails.
70    /// The exact error meaning is defined by the concrete runnable.
71    fn run_with(&mut self, input: &mut T) -> Result<(), E>;
72
73    /// Converts this runnable into a boxed runnable.
74    ///
75    /// # Returns
76    ///
77    /// A `BoxRunnableWith<T, E>`.
78    fn into_box(mut self) -> BoxRunnableWith<T, E>
79    where
80        Self: Sized + 'static,
81    {
82        BoxRunnableWith::new(move |input| self.run_with(input))
83    }
84
85    /// Converts this runnable into an `Rc` runnable.
86    ///
87    /// # Returns
88    ///
89    /// A `RcRunnableWith<T, E>`.
90    fn into_rc(mut self) -> RcRunnableWith<T, E>
91    where
92        Self: Sized + 'static,
93    {
94        RcRunnableWith::new(move |input| self.run_with(input))
95    }
96
97    /// Converts this runnable into an `Arc` runnable.
98    ///
99    /// # Returns
100    ///
101    /// An `ArcRunnableWith<T, E>`.
102    fn into_arc(mut self) -> ArcRunnableWith<T, E>
103    where
104        Self: Sized + Send + 'static,
105    {
106        ArcRunnableWith::new(move |input| self.run_with(input))
107    }
108
109    /// Converts this runnable into a mutable closure.
110    ///
111    /// # Returns
112    ///
113    /// A closure implementing `FnMut(&mut T) -> Result<(), E>`.
114    fn into_fn(mut self) -> impl FnMut(&mut T) -> Result<(), E>
115    where
116        Self: Sized + 'static,
117    {
118        move |input| self.run_with(input)
119    }
120
121    /// Converts this runnable into a boxed runnable without consuming `self`.
122    ///
123    /// # Returns
124    ///
125    /// A `BoxRunnableWith<T, E>` built from a clone of this runnable.
126    fn to_box(&self) -> BoxRunnableWith<T, E>
127    where
128        Self: Clone + Sized + 'static,
129    {
130        self.clone().into_box()
131    }
132
133    /// Converts this runnable into an `Rc` runnable without consuming `self`.
134    ///
135    /// # Returns
136    ///
137    /// A `RcRunnableWith<T, E>` built from a clone of this runnable.
138    fn to_rc(&self) -> RcRunnableWith<T, E>
139    where
140        Self: Clone + Sized + 'static,
141    {
142        self.clone().into_rc()
143    }
144
145    /// Converts this runnable into an `Arc` runnable without consuming `self`.
146    ///
147    /// # Returns
148    ///
149    /// An `ArcRunnableWith<T, E>` built from a clone of this runnable.
150    fn to_arc(&self) -> ArcRunnableWith<T, E>
151    where
152        Self: Clone + Send + Sized + 'static,
153    {
154        self.clone().into_arc()
155    }
156
157    /// Converts this runnable into a mutable closure without consuming `self`.
158    ///
159    /// # Returns
160    ///
161    /// A closure implementing `FnMut(&mut T) -> Result<(), E>`.
162    fn to_fn(&self) -> impl FnMut(&mut T) -> Result<(), E>
163    where
164        Self: Clone + Sized + 'static,
165    {
166        self.clone().into_fn()
167    }
168
169    /// Converts this runnable into a callable returning unit.
170    ///
171    /// # Returns
172    ///
173    /// A `BoxCallableWith<T, (), E>` that runs this task and returns unit on
174    /// success.
175    fn into_callable_with(mut self) -> BoxCallableWith<T, (), E>
176    where
177        Self: Sized + 'static,
178    {
179        BoxCallableWith::new(move |input| self.run_with(input))
180    }
181}
qubit_function/tasks/runnable_with.rs

qubit_function/tasks/
runnable_with.rs
