qubit_function/functions/stateful_mutating_function/
arc_stateful_mutating_function.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9//! Defines the `ArcStatefulMutatingFunction` public type.
10
11#![allow(unused_imports)]
12
13use super::*;
14
15// =======================================================================
16// 5. ArcStatefulMutatingFunction - Thread-Safe Shared Ownership
17// =======================================================================
18
19/// ArcStatefulMutatingFunction struct
20///
21/// A stateful mutating function implementation based on
22/// `Arc<Mutex<dyn FnMut(&mut T) -> R + Send>>` for thread-safe shared
23/// ownership scenarios. This type allows the function to be safely shared
24/// and used across multiple threads.
25///
26/// # Features
27///
28/// - **Shared Ownership**: Cloneable via `Arc`, multiple owners allowed
29/// - **Thread-Safe**: Implements `Send + Sync`, safe for concurrent use
30/// - **Stateful**: Can modify captured environment (uses `FnMut`)
31/// - **Chainable**: Method chaining via `&self` (non-consuming)
32///
33/// # Use Cases
34///
35/// Choose `ArcStatefulMutatingFunction` when:
36/// - The function needs to be shared across multiple threads for stateful
37///   operations
38/// - Concurrent task processing (e.g., thread pools)
39/// - Thread safety is required (Send + Sync)
40///
41/// # Examples
42///
43/// ```rust
44/// use qubit_function::{StatefulMutatingFunction,
45///                       ArcStatefulMutatingFunction};
46///
47/// let counter = {
48///     let mut count = 0;
49///     ArcStatefulMutatingFunction::new(move |x: &mut i32| {
50///         count += 1;
51///         *x *= 2;
52///         count
53///     })
54/// };
55/// let mut clone = counter.clone();
56///
57/// let mut value = 5;
58/// assert_eq!(clone.apply(&mut value), 1);
59/// ```
60///
61/// # Author
62///
63/// Haixing Hu
64pub struct ArcStatefulMutatingFunction<T, R> {
65    pub(super) function: ArcStatefulMutatingFunctionFn<T, R>,
66    pub(super) name: Option<String>,
67}
68
69impl<T, R> ArcStatefulMutatingFunction<T, R> {
70    // Generates: new(), new_with_name(), new_with_optional_name(), name(), set_name()
71    impl_function_common_methods!(
72        ArcStatefulMutatingFunction<T, R>,
73        (FnMut(&mut T) -> R + Send + 'static),
74        |f| Arc::new(Mutex::new(f))
75    );
76
77    // Generates: when(), and_then(), compose()
78    impl_shared_function_methods!(
79        ArcStatefulMutatingFunction<T, R>,
80        ArcConditionalStatefulMutatingFunction,
81        into_arc,
82        Function,  // chains a non-mutating function after this mutating function
83        Send + Sync + 'static
84    );
85}
86
87// Generates: Clone implementation for ArcStatefulMutatingFunction<T, R>
88impl_function_clone!(ArcStatefulMutatingFunction<T, R>);
89
90// Generates: Debug and Display implementations for ArcStatefulMutatingFunction<T, R>
91impl_function_debug_display!(ArcStatefulMutatingFunction<T, R>);
92
93// Generates: identity() method for ArcStatefulMutatingFunction<T, T>
94impl_function_identity_method!(ArcStatefulMutatingFunction<T, T>, mutating);
95
96// Implement StatefulMutatingFunction trait for ArcStatefulMutatingFunction<T, R>
97impl<T, R> StatefulMutatingFunction<T, R> for ArcStatefulMutatingFunction<T, R> {
98    fn apply(&mut self, t: &mut T) -> R {
99        (self.function.lock())(t)
100    }
101
102    // Use macro to implement conversion methods
103    impl_arc_conversions!(
104        ArcStatefulMutatingFunction<T, R>,
105        BoxStatefulMutatingFunction,
106        RcStatefulMutatingFunction,
107        BoxMutatingFunctionOnce,
108        FnMut(input: &mut T) -> R
109    );
110}
111
112// =======================================================================
113// 6. Implement StatefulMutatingFunction trait for closures
114// =======================================================================
115
116impl<T, R, F> StatefulMutatingFunction<T, R> for F
117where
118    F: FnMut(&mut T) -> R,
119{
120    fn apply(&mut self, input: &mut T) -> R {
121        self(input)
122    }
123
124    fn into_box(self) -> BoxStatefulMutatingFunction<T, R>
125    where
126        Self: Sized + 'static,
127    {
128        BoxStatefulMutatingFunction::new(self)
129    }
130
131    fn into_rc(self) -> RcStatefulMutatingFunction<T, R>
132    where
133        Self: Sized + 'static,
134    {
135        RcStatefulMutatingFunction::new(self)
136    }
137
138    fn into_arc(self) -> ArcStatefulMutatingFunction<T, R>
139    where
140        Self: Sized + Send + 'static,
141    {
142        ArcStatefulMutatingFunction::new(self)
143    }
144
145    fn into_fn(self) -> impl FnMut(&mut T) -> R
146    where
147        Self: Sized + 'static,
148    {
149        self
150    }
151
152    fn to_box(&self) -> BoxStatefulMutatingFunction<T, R>
153    where
154        Self: Sized + Clone + 'static,
155    {
156        let cloned = self.clone();
157        BoxStatefulMutatingFunction::new(cloned)
158    }
159
160    fn to_rc(&self) -> RcStatefulMutatingFunction<T, R>
161    where
162        Self: Sized + Clone + 'static,
163    {
164        let cloned = self.clone();
165        RcStatefulMutatingFunction::new(cloned)
166    }
167
168    fn to_arc(&self) -> ArcStatefulMutatingFunction<T, R>
169    where
170        Self: Sized + Clone + Send + 'static,
171    {
172        let cloned = self.clone();
173        ArcStatefulMutatingFunction::new(cloned)
174    }
175
176    fn to_fn(&self) -> impl FnMut(&mut T) -> R
177    where
178        Self: Sized + Clone + 'static,
179    {
180        self.clone()
181    }
182
183    fn into_once(self) -> BoxMutatingFunctionOnce<T, R>
184    where
185        Self: Sized + 'static,
186    {
187        BoxMutatingFunctionOnce::new(self)
188    }
189
190    fn to_once(&self) -> BoxMutatingFunctionOnce<T, R>
191    where
192        Self: Sized + Clone + 'static,
193    {
194        BoxMutatingFunctionOnce::new(self.clone())
195    }
196}
qubit_function/functions/stateful_mutating_function/arc_stateful_mutating_function.rs

qubit_function/functions/stateful_mutating_function/
arc_stateful_mutating_function.rs
