qubit_function/consumers/stateful_consumer/
box_stateful_consumer.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9//! Defines the `BoxStatefulConsumer` public type.
10
11#![allow(unused_imports)]
12
13use super::*;
14
15// ============================================================================
16// 2. BoxStatefulConsumer - Single Ownership Implementation
17// ============================================================================
18
19/// BoxStatefulConsumer struct
20///
21/// Consumer implementation based on `Box<dyn FnMut(&T)>` for single ownership
22/// scenarios. When sharing is not needed, this is the simplest and most
23/// efficient consumer type.
24///
25/// # Features
26///
27/// - **Single Ownership**: Not cloneable, transfers ownership when used
28/// - **Zero Overhead**: No reference counting or lock overhead
29/// - **Mutable State**: Can modify captured environment through `FnMut`
30/// - **Builder Pattern**: Method chaining naturally consumes `self`
31///
32/// # Use Cases
33///
34/// Choose `BoxStatefulConsumer` when:
35/// - Consumer is used only once or in a linear flow
36/// - Building pipelines where ownership flows naturally
37/// - No need to share consumers across contexts
38/// - Performance critical and cannot accept sharing overhead
39///
40/// # Performance
41///
42/// `BoxStatefulConsumer` has the best performance among the three consumer types:
43/// - No reference counting overhead
44/// - No lock acquisition or runtime borrowing checks
45/// - Direct function calls through vtable
46/// - Minimal memory footprint (single pointer)
47///
48/// # Examples
49///
50/// ```rust
51/// use qubit_function::{Consumer, StatefulConsumer, BoxStatefulConsumer};
52/// use std::sync::{Arc, Mutex};
53///
54/// let log = Arc::new(Mutex::new(Vec::new()));
55/// let l = log.clone();
56/// let mut consumer = BoxStatefulConsumer::new(move |x: &i32| {
57///     l.lock().unwrap().push(*x);
58/// });
59/// consumer.accept(&5);
60/// assert_eq!(*log.lock().unwrap(), vec![5]);
61/// ```
62///
63/// # Author
64///
65/// Haixing Hu
66pub struct BoxStatefulConsumer<T> {
67    pub(super) function: Box<dyn FnMut(&T)>,
68    pub(super) name: Option<String>,
69}
70
71impl<T> BoxStatefulConsumer<T> {
72    // Generates: new(), new_with_name(), name(), set_name(), noop()
73    impl_consumer_common_methods!(BoxStatefulConsumer<T>, (FnMut(&T) + 'static), |f| Box::new(
74        f
75    ));
76
77    // Generates: when() and and_then() methods that consume self
78    impl_box_consumer_methods!(
79        BoxStatefulConsumer<T>,
80        BoxConditionalStatefulConsumer,
81        StatefulConsumer
82    );
83}
84
85impl<T> StatefulConsumer<T> for BoxStatefulConsumer<T> {
86    fn accept(&mut self, value: &T) {
87        (self.function)(value)
88    }
89
90    // Generates: into_box(), into_rc(), into_fn(), into_once()
91    impl_box_conversions!(
92        BoxStatefulConsumer<T>,
93        RcStatefulConsumer,
94        FnMut(&T),
95        BoxConsumerOnce
96    );
97}
98
99// Use macro to generate Debug and Display implementations
100impl_consumer_debug_display!(BoxStatefulConsumer<T>);
qubit_function/consumers/stateful_consumer/box_stateful_consumer.rs

qubit_function/consumers/stateful_consumer/
box_stateful_consumer.rs
