qubit_function/mutators/mutator/
arc_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 `ArcMutator` public type.
12
13#![allow(unused_imports)]
14
15use super::*;
16
17// ============================================================================
18// 5. ArcMutator - Thread-Safe Shared Ownership Implementation
19// ============================================================================
20
21/// ArcMutator struct
22///
23/// A stateless mutator implementation based on `Arc<dyn Fn(&mut T) + Send + Sync>`
24/// for thread-safe shared ownership scenarios. This type allows the mutator
25/// to be safely shared and used across multiple threads.
26///
27/// # Features
28///
29/// - **Shared Ownership**: Cloneable via `Arc`, multiple owners allowed
30/// - **Thread-Safe**: Implements `Send + Sync`, safe for concurrent use
31/// - **Stateless**: Cannot modify captured environment (uses `Fn` not `FnMut`)
32/// - **Chainable**: Method chaining via `&self` (non-consuming)
33///
34/// # Use Cases
35///
36/// Choose `ArcMutator` when:
37/// - The mutator needs to be shared across multiple threads for stateless 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::{Mutator, ArcMutator};
45///
46/// let mutator = ArcMutator::new(|x: &mut i32| *x *= 2);
47/// let clone = mutator.clone();
48///
49/// let mut value = 5;
50/// mutator.apply(&mut value);
51/// assert_eq!(value, 10);
52/// ```
53///
54pub struct ArcMutator<T> {
55    pub(super) function: ArcMutatorFn<T>,
56    pub(super) name: Option<String>,
57}
58
59impl<T> ArcMutator<T> {
60    // Generate common mutator methods (new, new_with_name, name, set_name, noop)
61    impl_mutator_common_methods!(ArcMutator<T>, (Fn(&mut T) + Send + Sync + 'static), |f| {
62        Arc::new(f)
63    });
64
65    // Generate shared mutator methods (when, and_then, or_else, conversions)
66    impl_shared_mutator_methods!(
67        ArcMutator<T>,
68        ArcConditionalMutator,
69        into_arc,
70        Mutator,
71        Send + Sync + 'static
72    );
73}
74
75impl<T> Mutator<T> for ArcMutator<T> {
76    fn apply(&self, value: &mut T) {
77        (self.function)(value)
78    }
79
80    // Use macro to implement conversion methods
81    impl_arc_conversions!(
82        ArcMutator<T>,
83        BoxMutator,
84        RcMutator,
85        BoxMutatorOnce,
86        Fn(input: &mut T)
87    );
88}
89
90// Generate Clone trait implementation for mutator
91impl_mutator_clone!(ArcMutator<T>);
92
93// Generate Debug and Display trait implementations
94impl_mutator_debug_display!(ArcMutator<T>);
95
96// ============================================================================
97// 6. Implement Mutator trait for closures
98// ============================================================================
99
100impl_closure_trait!(
101    Mutator<T>,
102    apply,
103    BoxMutatorOnce,
104    Fn(value: &mut T)
105);
qubit_function/mutators/mutator/arc_mutator.rs

qubit_function/mutators/mutator/
arc_mutator.rs
