qubit_function/functions/mutating_function/
arc_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 `ArcMutatingFunction` public type.
10
11#![allow(unused_imports)]
12
13use super::*;
14
15// =======================================================================
16// 5. ArcMutatingFunction - Thread-Safe Shared Ownership
17// =======================================================================
18
19/// ArcMutatingFunction struct
20///
21/// A mutating function implementation based on
22/// `Arc<dyn Fn(&mut T) -> R + Send + Sync>` for thread-safe shared ownership
23/// scenarios. This type allows the function to be safely shared and used
24/// 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/// - **Stateless**: Cannot modify captured environment (uses `Fn` not
31///   `FnMut`)
32/// - **Chainable**: Method chaining via `&self` (non-consuming)
33///
34/// # Use Cases
35///
36/// Choose `ArcMutatingFunction` when:
37/// - The function needs to be shared across multiple threads for stateless
38///   operations
39/// - Concurrent task processing (e.g., thread pools)
40/// - Thread safety is required (Send + Sync)
41///
42/// # Examples
43///
44/// ```rust
45/// use qubit_function::{MutatingFunction, ArcMutatingFunction};
46///
47/// let func = ArcMutatingFunction::new(|x: &mut i32| {
48///     *x *= 2;
49///     *x
50/// });
51/// let clone = func.clone();
52///
53/// let mut value = 5;
54/// assert_eq!(func.apply(&mut value), 10);
55/// ```
56///
57/// # Author
58///
59/// Haixing Hu
60pub struct ArcMutatingFunction<T, R> {
61    pub(super) function: Arc<dyn Fn(&mut T) -> R + Send + Sync>,
62    pub(super) name: Option<String>,
63}
64
65impl<T, R> ArcMutatingFunction<T, R> {
66    // Generates: new(), new_with_name(), new_with_optional_name(), name(), set_name()
67    impl_function_common_methods!(
68        ArcMutatingFunction<T, R>,
69        (Fn(&mut T) -> R + Send + Sync + 'static),
70        |f| Arc::new(f)
71    );
72
73    // Generates: when(), and_then(), compose()
74    impl_shared_function_methods!(
75        ArcMutatingFunction<T, R>,
76        ArcConditionalMutatingFunction,
77        into_arc,
78        Function,  // chains a non-mutating function after this mutating function
79        Send + Sync + 'static
80    );
81}
82
83// Generates: Clone implementation for ArcMutatingFunction<T, R>
84impl_function_clone!(ArcMutatingFunction<T, R>);
85
86// Generates: Debug and Display implementations for ArcMutatingFunction<T, R>
87impl_function_debug_display!(ArcMutatingFunction<T, R>);
88
89// Generates: identity() method for ArcMutatingFunction<T, T>
90impl_function_identity_method!(ArcMutatingFunction<T, T>, mutating);
91
92impl<T, R> MutatingFunction<T, R> for ArcMutatingFunction<T, R> {
93    fn apply(&self, input: &mut T) -> R {
94        (self.function)(input)
95    }
96
97    // Use macro to implement conversion methods
98    impl_arc_conversions!(
99        ArcMutatingFunction<T, R>,
100        BoxMutatingFunction,
101        RcMutatingFunction,
102        BoxMutatingFunctionOnce,
103        Fn(input: &mut T) -> R
104    );
105}
106
107// =======================================================================
108// 6. Implement MutatingFunction trait for closures
109// =======================================================================
110
111impl_closure_trait!(
112    MutatingFunction<T, R>,
113    apply,
114    BoxMutatingFunctionOnce,
115    Fn(input: &mut T) -> R
116);
qubit_function/functions/mutating_function/arc_mutating_function.rs

qubit_function/functions/mutating_function/
arc_mutating_function.rs
