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
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
//! The chain's control of its realtime endpoint: creating it for the prepared configuration, and
//! starting, resynchronizing and stopping the helper's worker. While the endpoint runs, the chain
//! replaces one slot's instance between quanta and refuses what would reconfigure or reset the
//! chain under it.
use std::sync::Arc;
use std::time::Duration;
use plughost_core::InputError;
use plughost_core::ipc::shared::realtime::{Control, MAX_LANES, Ring, RingDescriptor};
use plughost_core::ipc::shared::{SlotConfig, clock};
use super::*;
use crate::realtime::{
DryDelay, Fallback, RealtimeConfig, RealtimeEndpoint, RealtimeStatus, State,
};
/// The control thread's handle on the chain's endpoint.
pub(super) struct Realtime {
pub(super) state: Arc<State>,
/// The control mapping of the chain's ring.
pub(super) control: Arc<Control>,
pub(super) config: RealtimeConfig,
/// The helper's worker runs.
pub(super) running: bool,
/// The dry path's storage capacity the callback has, in frames.
dry_capacity: usize,
/// When the current generation started, in [`clock`] ticks.
started: u64,
/// Late completions the rings of the chains the endpoint left in recoveries counted.
pub(super) late: u64,
}
impl Realtime {
/// Frames the endpoint adds to the chain's latency.
fn added(&self) -> u32 {
(self.config.latency * self.config.quantum) as u32
}
/// The time since the worker last completed a quantum, or since the generation started,
/// while a submitted quantum is outstanding. The worker stamps its heartbeat only when it
/// completes one.
fn stalled(&self, running: bool) -> Duration {
let (submitted, completed) = self.control.progress();
if !running || submitted <= completed {
return Duration::ZERO;
}
let heartbeat = self.control.worker().1;
clock::duration(clock::now().saturating_sub(heartbeat.max(self.started)))
}
}
impl Drop for Realtime {
fn drop(&mut self) {
self.state.close();
}
}
impl Chain {
/// Creates the realtime endpoint for the prepared chain, replacing one created before, which
/// then plays its fallback for good, as does an endpoint after the chain that has it is
/// prepared again or dropped; [`Chain::recover_realtime`] moves it to another chain. Each
/// callback is one quantum of `config.quantum` frames, at most the prepared maximum block
/// size, in the prepared precision. Move the returned endpoint to the audio callback's thread;
/// it plays its fallback until [`Chain::start_realtime`].
pub fn realtime_endpoint(
&mut self,
config: &RealtimeConfig,
) -> Result<RealtimeEndpoint, Error> {
self.refuse_while_realtime()?;
let chain = self.config.as_ref().ok_or(Error::NotPrepared)?;
let invalid = |error| Error::Input { slot: None, error };
if config.quantum == 0 || config.quantum > chain.max_block_size {
return Err(invalid(InputError::RealtimeQuantum));
}
if !(1..=MAX_LANES - 2).contains(&config.latency) {
return Err(invalid(InputError::RealtimeLatency));
}
let dry = config.fallback == Fallback::Dry;
if dry && chain.input_channels() != chain.output_channels() {
return Err(invalid(InputError::RealtimeDry));
}
let ring = self.install_ring(config)?;
let chain = self.config.as_ref().ok_or(Error::NotPrepared)?;
let state = Arc::new(State::default());
let added = config.latency * config.quantum;
let dry_capacity = self.latency as usize + added + config.quantum;
let dry = dry.then(|| {
let mut delay = DryDelay::new(chain.input_channels(), dry_capacity);
delay.set_delay(self.latency as usize + added);
Box::new(delay)
});
let control = ring.control();
let endpoint = RealtimeEndpoint::new(ring, Arc::clone(&state), config, chain, dry);
self.realtime = Some(Realtime {
control,
state,
config: *config,
running: false,
dry_capacity,
started: 0,
late: 0,
});
Ok(endpoint)
}
/// Creates a ring of `config`'s shape for the prepared chain and installs it in the helper.
pub(super) fn install_ring(&mut self, config: &RealtimeConfig) -> Result<Ring, Error> {
let chain = self.config.as_ref().ok_or(Error::NotPrepared)?;
let lanes = config.latency + 2;
let first = self.generation.checked_add(1).ok_or(Error::Protocol)?;
self.generation = first + lanes as u64;
let descriptor = RingDescriptor {
control: first,
first_lane: first + 1,
lanes,
config: SlotConfig {
sample_format: chain.sample_format,
max_frames: config.quantum,
input_channels: chain.input_channels(),
output_channels: chain.output_channels(),
},
};
let ring = Ring::new(descriptor).map_err(shared::storage_error)?;
let response = self.helper.install_ring(
&ring,
|tokens| Request::RealtimeInstall {
ring: descriptor,
tokens,
},
self.timeouts.control,
)?;
expect_done(response)?;
Ok(ring)
}
/// Starts the realtime endpoint: its callbacks submit their quanta from now on, numbered
/// from 1, and play the chain's output `latency` callbacks later. Returns the endpoint's
/// whole latency in frames, the chain's plus `latency * quantum`. After a resync, call
/// [`Chain::resync_realtime`]; stopping the endpoint, [`Chain::reset`]ting the chain and
/// starting it again works too.
pub fn start_realtime(&mut self) -> Result<u32, Error> {
self.start_generation(None)
}
/// Starts the endpoint's next generation once the helper's worker runs, handing the callback
/// `ring` for it.
pub(super) fn start_generation(&mut self, ring: Option<Box<Ring>>) -> Result<u32, Error> {
let realtime = self.realtime.as_ref().ok_or(Error::NotPrepared)?;
if realtime.running {
return Ok(self.latency.saturating_add(realtime.added()));
}
let config = self.config.as_ref().ok_or(Error::NotPrepared)?;
let generation = realtime.state.generation() + 1;
let quantum_seconds =
(realtime.config.latency * realtime.config.quantum) as f64 / config.sample_rate;
let deadline = clock::ticks(Duration::from_secs_f64(quantum_seconds));
let added = realtime.added();
let dry_delay = self.dry_delay()?;
let realtime = self.realtime.as_ref().ok_or(Error::NotPrepared)?;
realtime.control.start(generation, deadline);
let response = self.request(Request::RealtimeStart, self.timeouts.control)?;
expect_done(response)?;
let latency = self.latency;
let realtime = self.realtime.as_mut().ok_or(Error::NotPrepared)?;
if let Some(ring) = ring {
realtime.state.send_ring(ring);
}
realtime.started = clock::now();
realtime.state.start(generation, latency, dry_delay as u64);
realtime.running = true;
Ok(latency.saturating_add(added))
}
/// Resynchronizes the running realtime endpoint without stopping it, and returns its whole
/// latency in frames, as [`Chain::start_realtime`] does. Call it from the control thread once
/// [`RealtimeStatus::resync`] is set; nothing resynchronizes on its own. The callbacks stop
/// submitting and play the fallback ([`crate::FallbackReason::Resync`]) while every plugin is
/// reset as by [`Chain::reset`], which ends the notes the plugins hold and applies a latency
/// they announced. The helper's worker goes on and numbers the new generation's quanta from
/// 1; its first output plays as is `latency` callbacks later, as after a start, and the
/// first callback ends the notes earlier outputs delivered through `produced`.
///
/// A plugin whose reset does not return within the control timeout, as when it holds up
/// the worker, fails it with [`Error::TimedOut`], and the endpoint plays its fallback until
/// the application recovers. A stopped endpoint has nothing to resynchronize: the call
/// returns its latency, as [`Chain::start_realtime`] would, and changes nothing.
pub fn resync_realtime(&mut self) -> Result<u32, Error> {
let realtime = self.realtime.as_ref().ok_or(Error::NotPrepared)?;
if !realtime.running {
return Ok(self.latency.saturating_add(realtime.added()));
}
realtime.state.halt();
let generation = realtime.state.generation() + 1;
// No callback submits now, so the control thread may clear the submitted sequence; the
// worker adopts the generation before the helper resets the plugins.
realtime.control.resync(generation);
match self.request(Request::RealtimeResync, self.timeouts.control)? {
Response::Timing { latency, tail, .. } => {
self.latency = latency;
self.tail = tail;
}
_ => return Err(self.protocol_error()),
}
let dry_delay = self.dry_delay()?;
let latency = self.latency;
let realtime = self.realtime.as_mut().ok_or(Error::NotPrepared)?;
realtime.started = clock::now();
realtime.state.start(generation, latency, dry_delay as u64);
Ok(latency.saturating_add(realtime.added()))
}
/// The dry path's delay for a generation at the chain's current latency. The callback gets
/// storage enough for it, which it takes as it follows the generation.
fn dry_delay(&mut self) -> Result<usize, Error> {
let config = self.config.as_ref().ok_or(Error::NotPrepared)?;
let realtime = self.realtime.as_mut().ok_or(Error::NotPrepared)?;
let delay = self.latency as usize + realtime.added() as usize;
let capacity = delay + realtime.config.quantum;
if realtime.config.fallback == Fallback::Dry && capacity > realtime.dry_capacity {
realtime
.state
.send_dry(Box::new(DryDelay::new(config.input_channels(), capacity)));
realtime.dry_capacity = capacity;
}
Ok(delay)
}
/// Stops the realtime endpoint between quanta; its callbacks play the fallback until it is
/// started again. A callback in progress is waited for, as [`Chain::resync_realtime`] and
/// [`Chain::recover_realtime`] do, so that none submits after the endpoint stopped.
pub fn stop_realtime(&mut self) -> Result<(), Error> {
let Some(realtime) = &mut self.realtime else {
return Ok(());
};
if !realtime.running {
return Ok(());
}
realtime.state.stop();
realtime.running = false;
let response = self.request(Request::RealtimeStop, self.timeouts.control)?;
expect_done(response)
}
/// What the realtime endpoint did, or `None` without one. Call it from a control thread: it
/// also releases the ring the endpoint stopped using after a recovery.
pub fn realtime_status(&self) -> Option<RealtimeStatus> {
let realtime = self.realtime.as_ref()?;
realtime.state.reclaim();
let running = realtime.state.running();
Some(realtime.state.status(
realtime.late + realtime.control.worker().0,
realtime.stalled(running),
realtime.added(),
))
}
pub(super) fn realtime_running(&self) -> bool {
self.realtime
.as_ref()
.is_some_and(|realtime| realtime.running)
}
/// Refuses what would reconfigure or reset the chain under a running endpoint.
pub(super) fn refuse_while_realtime(&self) -> Result<(), Error> {
if self.realtime_running() {
return Err(Error::RealtimeRunning);
}
Ok(())
}
}