qubit-function 0.14.1

Functional programming traits and Box/Rc/Arc adapters for Rust, inspired by Java functional interfaces
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

/*******************************************************************************
 *
 *    Copyright (c) 2025 - 2026 Haixing Hu.
 *
 *    SPDX-License-Identifier: Apache-2.0
 *
 *    Licensed under the Apache License, Version 2.0.
 *
 ******************************************************************************/
// qubit-style: allow explicit-imports
//! Defines the `ArcStatefulConsumer` public type.

use super::{
    Arc,
    ArcConditionalStatefulConsumer,
    BoxConsumerOnce,
    BoxStatefulConsumer,
    Mutex,
    Predicate,
    RcStatefulConsumer,
    StatefulConsumer,
    impl_arc_conversions,
    impl_closure_trait,
    impl_consumer_clone,
    impl_consumer_common_methods,
    impl_consumer_debug_display,
    impl_shared_consumer_methods,
};

type ArcStatefulConsumerFn<T> = Arc<Mutex<dyn FnMut(&T) + Send>>;

// ============================================================================
// 4. ArcStatefulConsumer - Thread-Safe Shared Ownership Implementation
// ============================================================================

/// ArcStatefulConsumer struct
///
/// Consumer implementation based on `Arc<Mutex<dyn FnMut(&T) + Send>>` for
/// thread-safe shared ownership scenarios. This consumer can be safely cloned
/// and shared across multiple threads.
///
/// # Features
///
/// - **Shared Ownership**: Cloneable through `Arc`, allowing multiple owners
/// - **Thread Safety**: Implements `Send + Sync`, safe for concurrent use
/// - **Interior Mutability**: Uses `Mutex` for safe mutable access
/// - **Non-Consuming API**: `and_then` borrows `&self`, original object remains
///   usable
/// - **Cross-Thread Sharing**: Can be sent to other threads and used
///
/// # Use Cases
///
/// Choose `ArcStatefulConsumer` when:
/// - Need to share consumers across multiple threads
/// - Concurrent task processing (e.g., thread pools)
/// - Using the same consumer in multiple places simultaneously
/// - Need thread safety (Send + Sync)
///
/// # Performance Considerations
///
/// `ArcStatefulConsumer` has some performance overhead compared to `BoxStatefulConsumer`:
/// - **Reference Counting**: Atomic operations on clone/drop
/// - **Mutex Locking**: Each `accept` call requires lock acquisition
/// - **Lock Contention**: High concurrency may cause contention
///
/// These overheads are necessary for safe concurrent access. If thread safety
/// is not needed, consider using `RcStatefulConsumer` for less single-threaded sharing
/// overhead.
///
/// # Examples
///
/// ```rust
/// use qubit_function::{Consumer, StatefulConsumer, ArcStatefulConsumer};
/// use std::sync::{Arc, Mutex};
///
/// let log = Arc::new(Mutex::new(Vec::new()));
/// let l = log.clone();
/// let mut consumer = ArcStatefulConsumer::new(move |x: &i32| {
///     l.lock().expect("mutex should not be poisoned").push(*x * 2);
/// });
/// let mut clone = consumer.clone();
///
/// consumer.accept(&5);
/// assert_eq!(*log.lock().expect("mutex should not be poisoned"), vec![10]);
/// ```
///
pub struct ArcStatefulConsumer<T> {
    pub(super) function: ArcStatefulConsumerFn<T>,
    pub(super) name: Option<String>,
}

impl<T> ArcStatefulConsumer<T> {
    // Generates: new(), new_with_name(), name(), set_name(), noop()
    impl_consumer_common_methods!(ArcStatefulConsumer<T>, (FnMut(&T) + Send + 'static), |f| {
        Arc::new(Mutex::new(f))
    });

    // Generates: when() and and_then() methods that borrow &self (Arc can clone)
    impl_shared_consumer_methods!(
        ArcStatefulConsumer<T>,
        ArcConditionalStatefulConsumer,
        into_arc,
        StatefulConsumer,
        Send + Sync + 'static
    );
}

impl<T> StatefulConsumer<T> for ArcStatefulConsumer<T> {
    fn accept(&mut self, value: &T) {
        (self.function.lock())(value)
    }

    // Use macro to implement conversion methods
    impl_arc_conversions!(
        ArcStatefulConsumer<T>,
        BoxStatefulConsumer,
        RcStatefulConsumer,
        BoxConsumerOnce,
        FnMut(t: &T)
    );
}

// Use macro to generate Clone implementation
impl_consumer_clone!(ArcStatefulConsumer<T>);

// Use macro to generate Debug and Display implementations
impl_consumer_debug_display!(ArcStatefulConsumer<T>);

// ============================================================================
// 5. Implement Consumer trait for closures
// ============================================================================

// Implement Consumer for all FnMut(&T)
impl_closure_trait!(
    StatefulConsumer<T>,
    accept,
    BoxConsumerOnce,
    FnMut(value: &T)
);