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

qubit_function/functions/mutating_function/
arc_mutating_function.rs
