qubit_function/consumers/consumer_once/
box_consumer_once.rs

1/*******************************************************************************
2 *
3 *    Copyright (c) 2025 - 2026.
4 *    Haixing Hu, Qubit Co. Ltd.
5 *
6 *    All rights reserved.
7 *
8 ******************************************************************************/
9//! Defines the `BoxConsumerOnce` public type.
10
11#![allow(unused_imports)]
12
13use super::*;
14
15// ============================================================================
16// 2. BoxConsumerOnce - Single Ownership Implementation
17// ============================================================================
18
19/// BoxConsumerOnce struct
20///
21/// One-time consumer implementation based on `Box<dyn FnOnce(&T)>` for single ownership scenarios.
22/// This is the simplest consumer type for truly one-time use.
23///
24/// # Features
25///
26/// - **Single Ownership**: Not cloneable, transfers ownership on use
27/// - **Zero Overhead**: No reference counting or lock overhead
28/// - **One-time Use**: Consumes self on first call
29/// - **Builder Pattern**: Method chaining naturally consumes `self`
30///
31/// # Use Cases
32///
33/// Choose `BoxConsumerOnce` when:
34/// - Consumer is truly used only once
35/// - Building pipelines where ownership flows naturally
36/// - Consumer captures values that should be consumed
37/// - Performance critical and cannot accept shared overhead
38///
39/// # Performance
40///
41/// `BoxConsumerOnce` has the best performance:
42/// - No reference counting overhead
43/// - No lock acquisition or runtime borrow checking
44/// - Direct function call through vtable
45/// - Minimal memory footprint (single pointer)
46///
47/// # Examples
48///
49/// ```rust
50/// use qubit_function::{ConsumerOnce, BoxConsumerOnce};
51///
52/// let consumer = BoxConsumerOnce::new(|x: &i32| {
53///     println!("Value: {}", x);
54/// });
55/// consumer.accept(&5);
56/// ```
57///
58/// # Author
59///
60/// Haixing Hu
61pub struct BoxConsumerOnce<T> {
62    pub(super) function: Box<dyn FnOnce(&T)>,
63    pub(super) name: Option<String>,
64}
65
66// All methods require T: 'static because Box<dyn FnOnce(&T)> requires it
67impl<T> BoxConsumerOnce<T> {
68    // Generates: new(), new_with_name(), name(), set_name(), noop()
69    impl_consumer_common_methods!(BoxConsumerOnce<T>, (FnOnce(&T) + 'static), |f| Box::new(f));
70
71    // Generates: when() and and_then() methods that consume self
72    impl_box_consumer_methods!(BoxConsumerOnce<T>, BoxConditionalConsumerOnce, ConsumerOnce);
73}
74
75impl<T> ConsumerOnce<T> for BoxConsumerOnce<T> {
76    fn accept(self, value: &T) {
77        (self.function)(value)
78    }
79
80    impl_box_once_conversions!(BoxConsumerOnce<T>, ConsumerOnce, FnOnce(&T));
81}
82
83// Use macro to generate Debug and Display implementations
84impl_consumer_debug_display!(BoxConsumerOnce<T>);
85
86// ============================================================================
87// 3. Implement ConsumerOnce trait for closures
88// ============================================================================
89
90// Implement ConsumerOnce for all FnOnce(&T) using macro
91impl_closure_once_trait!(
92    ConsumerOnce<T>,
93    accept,
94    BoxConsumerOnce,
95    FnOnce(value: &T)
96);
qubit_function/consumers/consumer_once/box_consumer_once.rs

qubit_function/consumers/consumer_once/
box_consumer_once.rs
