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
use crate::render::Tail;
/// Maximum retained timing changes before consumers must resynchronize.
pub const CHANGE_CAPACITY: usize = 128;
/// A plugin's timing as its owning thread last read it. The latency is the one the plugin was
/// activated with: it changes only when the plugin is prepared again or reset, so processing and
/// rendering keep one alignment in between. The tail follows the plugin's reports.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct PluginTiming {
/// Applied processing latency in frames.
pub latency: u32,
/// Most recently observed native tail duration.
pub tail: Tail,
/// The plugin asked to be prepared again; processing is refused until it is.
pub restart_required: bool,
/// The plugin reported a new latency, which takes effect when it is prepared again or reset.
/// The chain keeps aligning to `latency` until then, and a render does not start.
pub latency_changed: bool,
}
impl PluginTiming {
/// The timing of a plugin with no restart or latency change pending.
#[must_use]
pub fn new(latency: u32, tail: Tail) -> PluginTiming {
PluginTiming {
latency,
tail,
restart_required: false,
latency_changed: false,
}
}
}
/// Latest timing observation for one plugin in a chain.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub struct SlotChange {
/// Zero-based plugin slot.
pub slot: usize,
/// Last observed timing and pending restart flags.
pub timing: PluginTiming,
}
/// Timing notifications coalesce by slot, retaining last-observed order. Intermediate values
/// are not an audit trail. On overflow use `snapshot` to replace the entire consumer view.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
#[non_exhaustive]
#[must_use]
pub struct ChangeBatch {
/// Coalesced slot changes in last-observed order.
pub changes: Vec<SlotChange>,
/// Whether overflow requires replacing the consumer view with `snapshot`.
pub resync_required: bool,
/// Last known timing per slot; `None` for a slot never observed.
pub snapshot: Vec<Option<PluginTiming>>,
}
/// No callbacks or I/O under the producer. The owning helper serializes access to this buffer.
pub struct ChangeBuffer {
pending: Vec<SlotChange>,
snapshot: Vec<Option<PluginTiming>>,
overflow: bool,
}
impl Default for ChangeBuffer {
fn default() -> Self {
Self {
pending: Vec::with_capacity(CHANGE_CAPACITY),
snapshot: Vec::new(),
overflow: false,
}
}
}
impl ChangeBuffer {
/// Records a changed timing value, coalescing that slot and tracking overflow.
pub fn observe(&mut self, slot: usize, timing: PluginTiming) {
if self.snapshot.len() <= slot {
self.snapshot.resize(slot + 1, None);
}
if self.snapshot[slot] == Some(timing) {
return;
}
self.snapshot[slot] = Some(timing);
self.pending.retain(|event| event.slot != slot);
if self.pending.len() == CHANGE_CAPACITY {
self.pending.remove(0);
self.overflow = true;
}
self.pending.push(SlotChange { slot, timing });
}
/// Drains pending changes and overflow, retaining and returning the latest complete snapshot.
pub fn take(&mut self) -> ChangeBatch {
// Preserve the producer's reserved storage while returning an owned batch.
let changes = self.pending.clone();
self.pending.clear();
ChangeBatch {
changes,
resync_required: std::mem::take(&mut self.overflow),
snapshot: self.snapshot.clone(),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn change_notifications_coalesce_and_resynchronize_without_a_consumer() {
let mut events = ChangeBuffer::default();
let timing = |latency| PluginTiming {
latency,
tail: Tail::Samples(latency),
restart_required: false,
latency_changed: false,
};
for slot in 0..CHANGE_CAPACITY + 10 {
events.observe(slot, timing(slot as u32));
}
events.observe(0, timing(999));
let batch = events.take();
assert!(batch.resync_required);
assert_eq!(batch.changes.len(), CHANGE_CAPACITY);
assert_eq!(batch.changes.last().unwrap().slot, 0);
assert_eq!(batch.snapshot[0], Some(timing(999)));
assert_eq!(batch.snapshot.len(), CHANGE_CAPACITY + 10);
let empty = events.take();
assert!(!empty.resync_required);
assert!(empty.changes.is_empty());
assert_eq!(empty.snapshot, batch.snapshot);
}
}