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

qubit_function/mutators/stateful_mutator/
rc_stateful_mutator.rs
