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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
//! `StreamBuilder`'s data and pipeline configuration methods.
use crate::context::Receiver;
use crate::messages::Message;
use std::time::Duration;
pub struct StreamBuilder<T: Message> {
pub(super) receiver: Receiver<T>,
#[allow(clippy::type_complexity)]
pub(super) filter_fn: Option<Box<dyn Fn(&T) -> bool + Send + Sync>>,
#[allow(clippy::type_complexity)]
pub(super) map_fn: Option<Box<dyn Fn(T) -> T + Send + Sync>>,
pub(super) throttle_duration: Option<Duration>,
pub(super) debounce_duration: Option<Duration>,
pub(super) latest_only: bool,
#[allow(dead_code)]
pub(super) batch_size: Option<usize>,
#[allow(dead_code)]
pub(super) batch_timeout: Option<Duration>,
}
impl<T: Message + Send + 'static> StreamBuilder<T> {
/// Create a new stream builder from a receiver
pub fn new(receiver: Receiver<T>) -> Self {
Self {
receiver,
filter_fn: None,
map_fn: None,
throttle_duration: None,
debounce_duration: None,
latest_only: false,
batch_size: None,
batch_timeout: None,
}
}
crate::builder_setter!(
/// Filter messages based on a predicate
///
/// Only messages where the predicate returns `true` will be passed through.
///
/// # Example
///
/// ```rust
/// # use mecha10_core::prelude::*;
/// # use mecha10_core::stream::StreamBuilder;
/// # async fn example(receiver: Receiver<Image>) -> Result<()> {
/// let mut filtered = StreamBuilder::new(receiver)
/// .filter(|img| img.width >= 640)
/// .build();
/// # let _ = filtered.recv().await;
/// # Ok(())
/// # }
/// ```
predicate, filter, filter_fn, Fn(&T) -> bool + Send + Sync + 'static
);
crate::builder_setter!(
/// Throttle messages to a maximum rate
///
/// Messages will be rate-limited to at most one per `duration`.
/// If multiple messages arrive during the throttle period, only the
/// first one is kept and the rest are dropped.
///
/// # Example
///
/// ```rust
/// # use mecha10_core::prelude::*;
/// # async fn example(mut receiver: Receiver<Image>) -> Result<()> {
/// // Max 10 Hz
/// let throttled = receiver
/// .throttle(Duration::from_millis(100))
/// .build();
/// # Ok(())
/// # }
/// ```
into_some, throttle, throttle_duration, Duration
);
/// Keep only the latest message, dropping older ones
///
/// Useful for scenarios where you only care about the most recent
/// state and processing old messages is wasteful.
///
/// # Example
///
/// ```rust
/// # use mecha10_core::prelude::*;
/// # use mecha10_core::messages::Odometry;
/// # async fn example(receiver: Receiver<Odometry>) -> Result<()> {
/// let mut latest = receiver.latest().build();
/// # let _ = latest.recv().await;
/// # Ok(())
/// # }
/// ```
pub fn latest(mut self) -> Self {
self.latest_only = true;
self
}
crate::builder_setter!(
/// Transform messages using a mapping function
///
/// Applies the given function to each message. The function must return
/// the same type (for type-changing transformations, process messages manually).
///
/// # Example
///
/// ```rust
/// # use mecha10_core::prelude::*;
/// # use mecha10_core::stream::StreamBuilder;
/// # fn resize_to_thumbnail(img: Image) -> Image { img }
/// # fn normalize_brightness(_img: &mut Image) {}
/// # async fn example(receiver: Receiver<Image>, other: Receiver<Image>) -> Result<()> {
/// // Resize images to thumbnails (returns Image)
/// let mut thumbnails = StreamBuilder::new(receiver)
/// .map(|img| resize_to_thumbnail(img))
/// .build();
/// # let _ = thumbnails.recv().await;
///
/// // Normalize image brightness
/// let mut normalized = StreamBuilder::new(other)
/// .map(|mut img| {
/// normalize_brightness(&mut img);
/// img
/// })
/// .build();
/// # let _ = normalized.recv().await;
/// # Ok(())
/// # }
/// ```
predicate, map, map_fn, Fn(T) -> T + Send + Sync + 'static
);
crate::builder_setter!(
/// Debounce messages - ignore duplicates within a time window
///
/// Only the first message is kept; subsequent messages within the debounce
/// period are dropped. This is different from throttle - debounce resets
/// the timer on each new message.
///
/// Useful for:
/// - Button press handling (ignore bounces)
/// - Noisy sensor data
/// - Rapid user input events
///
/// # Example
///
/// ```rust
/// # use mecha10_core::prelude::*;
/// # async fn example(mut receiver: Receiver<Image>) -> Result<()> {
/// // Ignore duplicate bursts within 300ms
/// let mut debounced = receiver.debounce(Duration::from_millis(300));
///
/// // Only get one event per 300ms window
/// while let Some(image) = debounced.recv().await {
/// println!("Image: {}x{}", image.width, image.height);
/// }
/// # Ok(())
/// # }
/// ```
into_some, debounce, debounce_duration, Duration
);
}