qubit_function/mutators/stateful_mutator/
rc_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 `RcStatefulMutator` public type.
10
11#![allow(unused_imports)]
12
13use super::*;
14
15// ============================================================================
16// 3. RcMutator - Single-Threaded Shared Ownership Implementation
17// ============================================================================
18
19/// RcMutator struct
20///
21/// A mutator implementation based on `Rc<RefCell<dyn FnMut(&mut T)>>` for
22/// single-threaded shared ownership scenarios. This type allows multiple
23/// references to the same mutator without the overhead of thread safety.
24///
25/// # Features
26///
27/// - **Shared Ownership**: Cloneable via `Rc`, multiple owners allowed
28/// - **Single-Threaded**: Not thread-safe, cannot be sent across threads
29/// - **Interior Mutability**: Uses `RefCell` for runtime borrow checking
30/// - **Mutable State**: Can modify captured environment via `FnMut`
31/// - **Chainable**: Method chaining via `&self` (non-consuming)
32/// - **Performance**: More efficient than `ArcMutator` (no locking)
33///
34/// # Use Cases
35///
36/// Choose `RcMutator` when:
37/// - The mutator needs to be shared within a single thread
38/// - Thread safety is not required
39/// - Performance is important (avoiding lock overhead)
40///
41/// # Examples
42///
43/// ```rust
44/// use qubit_function::{Mutator, RcMutator};
45///
46/// let mutator = RcMutator::new(|x: &mut i32| *x *= 2);
47/// let clone = mutator.clone();
48///
49/// let mut value = 5;
50/// let mut m = mutator;
51/// m.apply(&mut value);
52/// assert_eq!(value, 10);
53/// ```
54///
55/// # Author
56///
57/// Haixing Hu
58pub struct RcStatefulMutator<T> {
59    pub(super) function: RcMutMutatorFn<T>,
60    pub(super) name: Option<String>,
61}
62
63impl<T> RcStatefulMutator<T> {
64    impl_mutator_common_methods!(
65        RcStatefulMutator<T>,
66        (FnMut(&mut T) + 'static),
67        |f| Rc::new(RefCell::new(f))
68    );
69
70    // Generate shared mutator methods (when, and_then, or_else, conversions)
71    impl_shared_mutator_methods!(
72        RcStatefulMutator<T>,
73        RcConditionalStatefulMutator,
74        into_rc,
75        StatefulMutator,
76        'static
77    );
78}
79
80impl<T> StatefulMutator<T> for RcStatefulMutator<T> {
81    fn apply(&mut self, value: &mut T) {
82        (self.function.borrow_mut())(value)
83    }
84
85    // Generate all conversion methods using the unified macro
86    impl_rc_conversions!(
87        RcStatefulMutator<T>,
88        BoxStatefulMutator,
89        BoxMutatorOnce,
90        FnMut(t: &mut T)
91    );
92}
93
94// Use macro to generate Clone implementation
95impl_mutator_clone!(RcStatefulMutator<T>);
96
97// Generate Debug and Display trait implementations
98impl_mutator_debug_display!(RcStatefulMutator<T>);
qubit_function/mutators/stateful_mutator/rc_stateful_mutator.rs

qubit_function/mutators/stateful_mutator/
rc_stateful_mutator.rs
