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

qubit_function/functions/mutating_function/
arc_mutating_function.rs
