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
140
141
142

/*******************************************************************************
 *
 *    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 `ArcStatefulBiConsumer` public type.

use super::{
    Arc,
    ArcConditionalStatefulBiConsumer,
    BiPredicate,
    BoxBiConsumerOnce,
    BoxStatefulBiConsumer,
    Mutex,
    RcStatefulBiConsumer,
    StatefulBiConsumer,
    impl_arc_conversions,
    impl_closure_trait,
    impl_consumer_clone,
    impl_consumer_common_methods,
    impl_consumer_debug_display,
    impl_shared_consumer_methods,
};

type ArcStatefulBiConsumerFn<T, U> = Arc<Mutex<dyn FnMut(&T, &U) + Send>>;

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

/// ArcStatefulBiConsumer struct
///
/// A bi-consumer implementation based on
/// `Arc<Mutex<dyn FnMut(&T, &U) + Send>>` for thread-safe shared
/// ownership scenarios. This consumer can be safely cloned and shared
/// across multiple threads.
///
/// # Features
///
/// - **Shared Ownership**: Cloneable via `Arc`, multiple owners allowed
/// - **Thread-Safe**: Implements `Send + Sync`, safe for concurrent use
/// - **Interior Mutability**: Uses `Mutex` for safe mutable access
/// - **Non-Consuming API**: `and_then` borrows `&self`, original remains
///   usable
/// - **Cross-Thread Sharing**: Can be sent to and used by other threads
///
/// # Use Cases
///
/// Choose `ArcStatefulBiConsumer` when:
/// - Need to share bi-consumer across multiple threads
/// - Concurrent task processing (e.g., thread pools)
/// - Using the same consumer in multiple places simultaneously
/// - Thread safety (Send + Sync) is required
///
/// # Performance Considerations
///
/// `ArcStatefulBiConsumer` has some overhead compared to `BoxStatefulBiConsumer`:
/// - **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 `RcStatefulBiConsumer` for lower
/// overhead in single-threaded sharing.
///
/// # Examples
///
/// ```rust
/// use qubit_function::{BiConsumer, ArcStatefulBiConsumer, StatefulBiConsumer};
/// use std::sync::{Arc, Mutex};
///
/// let log = Arc::new(Mutex::new(Vec::new()));
/// let l = log.clone();
/// let mut consumer = ArcStatefulBiConsumer::new(move |x: &i32, y: &i32| {
///     l.lock().expect("mutex should not be poisoned").push(*x + *y);
/// });
/// let mut clone = consumer.clone();
///
/// consumer.accept(&5, &3);
/// assert_eq!(*log.lock().expect("mutex should not be poisoned"), vec![8]);
/// ```
///
pub struct ArcStatefulBiConsumer<T, U> {
    pub(super) function: ArcStatefulBiConsumerFn<T, U>,
    pub(super) name: Option<String>,
}

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

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

impl<T, U> StatefulBiConsumer<T, U> for ArcStatefulBiConsumer<T, U> {
    fn accept(&mut self, first: &T, second: &U) {
        (self.function.lock())(first, second)
    }

    // Use macro to implement conversion methods
    impl_arc_conversions!(
        ArcStatefulBiConsumer<T, U>,
        BoxStatefulBiConsumer,
        RcStatefulBiConsumer,
        BoxBiConsumerOnce,
        FnMut(t: &T, u: &U)
    );
}

// Use macro to generate Clone implementation
impl_consumer_clone!(ArcStatefulBiConsumer<T, U>);

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

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

// Implements BiConsumer for all FnMut(&T, &U)
impl_closure_trait!(
    StatefulBiConsumer<T, U>,
    accept,
    BoxBiConsumerOnce,
    FnMut(first: &T, second: &U)
);