qubit_function/mutators/stateful_mutator/
arc_stateful_mutator.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9//! Defines the `ArcStatefulMutator` public type.
10
11#![allow(unused_imports)]
12
13use super::*;
14
15// ============================================================================
16// 4. ArcMutator - Thread-Safe Shared Ownership Implementation
17// ============================================================================
18
19/// ArcMutator struct
20///
21/// A mutator implementation based on `Arc<Mutex<dyn FnMut(&mut T) + Send>>`
22/// for thread-safe shared ownership scenarios. This type allows the mutator
23/// to be safely shared and used across multiple threads.
24///
25/// # Features
26///
27/// - **Shared Ownership**: Cloneable via `Arc`, multiple owners allowed
28/// - **Thread-Safe**: Implements `Send + Sync`, safe for concurrent use
29/// - **Interior Mutability**: Uses `Mutex` for safe concurrent mutations
30/// - **Mutable State**: Can modify captured environment via `FnMut`
31/// - **Chainable**: Method chaining via `&self` (non-consuming)
32///
33/// # Use Cases
34///
35/// Choose `ArcMutator` when:
36/// - The mutator needs to be shared across multiple threads
37/// - Concurrent task processing (e.g., thread pools)
38/// - Thread safety is required (Send + Sync)
39///
40/// # Examples
41///
42/// ```rust
43/// use qubit_function::{Mutator, ArcMutator};
44///
45/// let mutator = ArcMutator::new(|x: &mut i32| *x *= 2);
46/// let clone = mutator.clone();
47///
48/// let mut value = 5;
49/// let mut m = mutator;
50/// m.apply(&mut value);
51/// assert_eq!(value, 10);
52/// ```
53///
54/// # Author
55///
56/// Haixing Hu
57pub struct ArcStatefulMutator<T> {
58    pub(super) function: ArcMutMutatorFn<T>,
59    pub(super) name: Option<String>,
60}
61
62impl<T> ArcStatefulMutator<T> {
63    impl_mutator_common_methods!(
64        ArcStatefulMutator<T>,
65        (FnMut(&mut T) + Send + 'static),
66        |f| Arc::new(Mutex::new(f))
67    );
68
69    // Generate shared mutator methods (when, and_then, or_else, conversions)
70    impl_shared_mutator_methods!(
71        ArcStatefulMutator<T>,
72        ArcConditionalStatefulMutator,
73        into_arc,
74        StatefulMutator,
75        Send + Sync + 'static
76    );
77}
78
79impl<T> StatefulMutator<T> for ArcStatefulMutator<T> {
80    fn apply(&mut self, value: &mut T) {
81        (self.function.lock())(value)
82    }
83
84    // Use macro to implement conversion methods
85    impl_arc_conversions!(
86        ArcStatefulMutator<T>,
87        BoxStatefulMutator,
88        RcStatefulMutator,
89        BoxMutatorOnce,
90        FnMut(input: &mut T)
91    );
92}
93
94// Use macro to generate Clone implementation
95impl_mutator_clone!(ArcStatefulMutator<T>);
96
97// Generate Debug and Display trait implementations
98impl_mutator_debug_display!(ArcStatefulMutator<T>);
99
100// ============================================================================
101// 5. Implement Mutator trait for closures
102// ============================================================================
103
104impl_closure_trait!(
105    StatefulMutator<T>,
106    apply,
107    BoxMutatorOnce,
108    FnMut(value: &mut T)
109);
qubit_function/mutators/stateful_mutator/arc_stateful_mutator.rs

qubit_function/mutators/stateful_mutator/
arc_stateful_mutator.rs
