1use std::rc::Rc;
4use std::sync::{Arc, Mutex};
5
6use rustduck_sys::bridge::ffi;
7
8use crate::error::native_exception;
9use crate::host::{invalid_state, require_state};
10use crate::memory::{MemoryInputBinding, MemoryOutputBinding, install_dispatcher};
11use crate::{CallbackError, Error, HostState, MemoryInput, MemoryOutput, Report, Result};
12
13mod config;
14mod native_config;
15
16pub use config::{ProcessorConfig, ProcessorInput, ProcessorOutput};
17
18#[derive(Debug, Clone, Copy, PartialEq, Eq)]
20#[non_exhaustive]
21pub enum WaitStatus {
22 Pending,
24 Stopped,
26}
27
28#[derive(Clone)]
35pub struct AbortToken {
36 native: cxx::SharedPtr<ffi::RustDuckProcessorAbortToken>,
37 endpoints: Arc<Mutex<Option<AbortEndpoints>>>,
38}
39
40struct AbortEndpoints {
41 input: Option<Arc<MemoryInput>>,
42 output: Option<Arc<MemoryOutput>>,
43}
44
45unsafe impl Send for AbortToken {}
51
52unsafe impl Sync for AbortToken {}
56
57impl AbortToken {
58 pub fn request(&self) {
64 {
65 let endpoints = self
69 .endpoints
70 .lock()
71 .unwrap_or_else(|error| error.into_inner());
72 if let Some(endpoints) = endpoints.as_ref() {
73 if let Some(input) = &endpoints.input {
74 input.abort();
75 }
76 if let Some(output) = &endpoints.output {
77 output.abort();
78 }
79 }
80 }
81 if let Some(token) = self.native.as_ref() {
82 let _ = ffi::rustduck_processor_abort_token_request(token);
86 }
87 }
88
89 fn detach_endpoints(&self) {
90 self.endpoints
91 .lock()
92 .unwrap_or_else(|error| error.into_inner())
93 .take();
94 }
95}
96
97pub struct TSProcessor {
103 native: cxx::UniquePtr<ffi::RustDuckTSProcessor>,
104 report: Rc<Report>,
105 handler: Option<cxx::UniquePtr<ffi::RustDuckMemoryHandler>>,
106 input_binding: Option<MemoryInputBinding>,
107 output_binding: Option<MemoryOutputBinding>,
108 input: Option<Arc<MemoryInput>>,
109 output: Option<Arc<MemoryOutput>>,
110 abort_token: AbortToken,
111 native_shutdown_required: bool,
112 state: HostState,
113}
114
115impl TSProcessor {
116 pub fn new(report: Rc<Report>) -> Result<Self> {
118 let native = ffi::rustduck_processor_new(report.native())
119 .map_err(|error| native_exception("TSProcessor::new", error))?;
120 let Some(native_ref) = native.as_ref() else {
121 return Err(Error::NativeFailure {
122 operation: "TSProcessor::new",
123 });
124 };
125 let abort_token = AbortToken {
126 native: ffi::rustduck_processor_abort_token(native_ref),
127 endpoints: Arc::new(Mutex::new(None)),
128 };
129 Ok(Self {
130 native,
131 report,
132 handler: None,
133 input_binding: None,
134 output_binding: None,
135 input: None,
136 output: None,
137 abort_token,
138 native_shutdown_required: false,
139 state: HostState::Created,
140 })
141 }
142
143 pub fn report(&self) -> &Rc<Report> {
145 &self.report
146 }
147
148 pub const fn state(&self) -> HostState {
150 self.state
151 }
152
153 pub fn abort_token(&self) -> AbortToken {
158 self.abort_token.clone()
159 }
160
161 pub fn start(&mut self, config: &ProcessorConfig) -> Result<()> {
163 require_state("TSProcessor", "start", self.state, HostState::Created)?;
164 config::validate(config)?;
165
166 let input = config::memory_input(config);
167 let output = config::memory_output(config);
168 if input.is_some() || output.is_some() {
169 install_dispatcher()?;
170 }
171 let handler = if input.is_some() || output.is_some() {
172 let handler = ffi::rustduck_memory_handler_new()
173 .map_err(|error| native_exception("TSProcessor::memory_handler", error))?;
174 if handler.is_null() {
175 return Err(Error::NativeFailure {
176 operation: "TSProcessor::memory_handler",
177 });
178 }
179 Some(handler)
180 } else {
181 None
182 };
183
184 let input_binding = input.as_ref().map(|endpoint| endpoint.bind()).transpose()?;
185 let output_binding = output
186 .as_ref()
187 .map(|endpoint| endpoint.bind())
188 .transpose()?;
189
190 self.handler = handler;
194 self.input_binding = input_binding;
195 self.output_binding = output_binding;
196 self.input = input;
197 self.output = output;
198 *self
199 .abort_token
200 .endpoints
201 .lock()
202 .unwrap_or_else(|error| error.into_inner()) = Some(AbortEndpoints {
203 input: self.input.as_ref().map(Arc::clone),
204 output: self.output.as_ref().map(Arc::clone),
205 });
206
207 self.native_shutdown_required = true;
208 if let Err(error) = self.register_memory_handlers() {
209 self.fail_memory_endpoints();
210 self.state = HostState::Failed;
211 return Err(error);
212 }
213
214 let native_config = self.native_config(config)?;
215 let started = ffi::rustduck_processor_start(self.native.pin_mut(), &native_config)
216 .map_err(|error| self.fail_after_native_exception("TSProcessor::start", error))?;
217 if !started {
218 self.fail_memory_endpoints();
219 self.state = HostState::Failed;
220 return Err(Error::NativeFailure {
221 operation: "TSProcessor::start",
222 });
223 }
224 self.state = HostState::Running;
225 Ok(())
226 }
227
228 pub fn abort(&mut self) -> Result<()> {
230 require_state("TSProcessor", "abort", self.state, HostState::Running)?;
231 self.fail_memory_endpoints();
232 self.state = HostState::Stopping;
233 ffi::rustduck_processor_abort(self.native.pin_mut())
234 .map_err(|error| self.fail_after_native_exception("TSProcessor::abort", error))
235 }
236
237 pub fn try_wait(&mut self) -> Result<WaitStatus> {
243 if !self.state.is_active() {
244 return Err(invalid_state("TSProcessor", "try_wait", self.state));
245 }
246 let started = ffi::rustduck_processor_is_started(
247 self.native
248 .as_ref()
249 .expect("TSProcessor construction rejects null owners"),
250 )
251 .map_err(|error| self.fail_after_native_exception("TSProcessor::try_wait", error))?;
252 if started {
253 Ok(WaitStatus::Pending)
254 } else {
255 ffi::rustduck_processor_wait(self.native.pin_mut()).map_err(|error| {
259 self.fail_after_native_exception("TSProcessor::try_wait", error)
260 })?;
261 self.finish_wait();
262 Ok(WaitStatus::Stopped)
263 }
264 }
265
266 pub fn wait_for_termination(&mut self) -> Result<()> {
268 if !self.state.is_active() {
269 return Err(invalid_state(
270 "TSProcessor",
271 "wait_for_termination",
272 self.state,
273 ));
274 }
275 ffi::rustduck_processor_wait(self.native.pin_mut()).map_err(|error| {
276 self.fail_after_native_exception("TSProcessor::wait_for_termination", error)
277 })?;
278 self.finish_wait();
279 Ok(())
280 }
281
282 pub fn take_memory_error(&self) -> Option<CallbackError> {
284 self.input
285 .as_ref()
286 .and_then(|endpoint| endpoint.take_callback_error())
287 .or_else(|| {
288 self.output
289 .as_ref()
290 .and_then(|endpoint| endpoint.take_callback_error())
291 })
292 }
293
294 fn finish_wait(&mut self) {
295 self.abort_token.detach_endpoints();
296 self.close_memory_outputs();
297 self.native_shutdown_required = false;
298 self.state = HostState::Stopped;
299 }
300
301 fn native_config(&self, config: &ProcessorConfig) -> Result<ffi::RustDuckProcessorConfig> {
302 native_config::build(
303 config,
304 self.input_binding.as_ref(),
305 self.output_binding.as_ref(),
306 )
307 }
308
309 fn register_memory_handlers(&mut self) -> Result<()> {
310 let Some(handler) = self.handler.as_ref() else {
311 return Ok(());
312 };
313 if self.input_binding.is_some() {
314 ffi::rustduck_processor_register_input(self.native.pin_mut(), handler)
315 .map_err(|error| native_exception("TSProcessor::register_input", error))?;
316 }
317 if self.output_binding.is_some() {
318 ffi::rustduck_processor_register_output(self.native.pin_mut(), handler)
319 .map_err(|error| native_exception("TSProcessor::register_output", error))?;
320 }
321 Ok(())
322 }
323
324 fn fail_after_native_exception(
325 &mut self,
326 operation: &'static str,
327 error: cxx::Exception,
328 ) -> Error {
329 self.fail_memory_endpoints();
330 self.state = HostState::Failed;
331 native_exception(operation, error)
332 }
333
334 fn fail_memory_endpoints(&self) {
335 if let Some(endpoint) = &self.input {
336 endpoint.abort();
337 }
338 if let Some(endpoint) = &self.output {
339 endpoint.abort();
340 }
341 }
342
343 fn close_memory_outputs(&self) {
344 if let Some(endpoint) = &self.output {
345 endpoint.close();
346 }
347 }
348}
349
350impl Drop for TSProcessor {
351 fn drop(&mut self) {
352 self.abort_token.detach_endpoints();
353 if self.native_shutdown_required {
354 self.fail_memory_endpoints();
355 let _ = ffi::rustduck_processor_abort(self.native.pin_mut());
356 let _ = ffi::rustduck_processor_wait(self.native.pin_mut());
357 }
358 }
361}
362
363#[cfg(test)]
364mod tests {
365 use std::num::NonZeroUsize;
366 use std::sync::mpsc;
367 use std::thread;
368 use std::time::Duration;
369
370 use super::*;
371 use crate::{MemoryQueuePolicy, PluginOptions, TS_PACKET_SIZE};
372
373 fn assert_token_wakes_callback(
374 config: ProcessorConfig,
375 wait_for_callback: impl FnOnce() -> bool,
376 rescue: impl FnOnce(),
377 ) {
378 let (token_sender, token_receiver) = mpsc::channel();
379 let (done_sender, done_receiver) = mpsc::channel();
380 let owner = thread::spawn(move || {
381 let mut processor =
382 TSProcessor::new(Report::stderr().expect("report")).expect("processor");
383 token_sender
384 .send(processor.abort_token())
385 .expect("send token");
386 let started = processor.start(&config);
387 if started.is_ok() {
388 processor
389 .wait_for_termination()
390 .expect("wait after cancellation");
391 }
392 drop(processor);
393 done_sender.send(()).expect("send owner completion");
394 });
395 let token = token_receiver
396 .recv_timeout(Duration::from_secs(5))
397 .expect("token");
398 let waiting = wait_for_callback();
399 let requester = thread::spawn(move || token.request());
400 let completed = done_receiver.recv_timeout(Duration::from_secs(2));
401 rescue();
403 requester.join().expect("requester join");
404 owner.join().expect("owner join");
405 assert!(waiting, "native callback must reach the queue wait");
406 assert!(
407 completed.is_ok(),
408 "token must wake the blocked native callback"
409 );
410 }
411
412 #[test]
413 fn abort_token_wakes_input_callbacks_during_start_and_processing() {
414 let _lock = crate::host::native_test_lock();
415 for initially_queued in [false, true] {
416 let input = MemoryInput::new(
417 NonZeroUsize::new(TS_PACKET_SIZE).expect("capacity"),
418 MemoryQueuePolicy::Backpressure,
419 )
420 .expect("input");
421 if initially_queued {
422 input.push(&[0x47; TS_PACKET_SIZE]).expect("initial packet");
423 }
424 assert_token_wakes_callback(
425 ProcessorConfig {
426 initial_input_packets: 1,
427 max_input_packets: 1,
428 input: Some(ProcessorInput::Memory(Arc::clone(&input))),
429 output: Some(ProcessorOutput::Native(PluginOptions::without_arguments(
430 "drop",
431 ))),
432 ..ProcessorConfig::default()
433 },
434 || input.inner.wait_for_waiter(),
435 || input.abort(),
436 );
437 }
438 }
439
440 #[test]
441 fn abort_token_wakes_backpressured_output_callback() {
442 let _lock = crate::host::native_test_lock();
443 let output = MemoryOutput::new(
444 NonZeroUsize::new(TS_PACKET_SIZE).expect("capacity"),
445 MemoryQueuePolicy::Backpressure,
446 )
447 .expect("output");
448 assert_token_wakes_callback(
449 ProcessorConfig {
450 max_output_packets: 1,
451 input: Some(ProcessorInput::Native(PluginOptions::new("null", ["3"]))),
452 output: Some(ProcessorOutput::Memory(Arc::clone(&output))),
453 ..ProcessorConfig::default()
454 },
455 || output.inner.wait_for_waiter(),
456 || output.abort(),
457 );
458 }
459
460 #[test]
461 fn abort_token_preserves_draining_output_after_wait_and_owner_drop() {
462 let _lock = crate::host::native_test_lock();
463 let output = MemoryOutput::new(
464 NonZeroUsize::new(TS_PACKET_SIZE).expect("capacity"),
465 MemoryQueuePolicy::Backpressure,
466 )
467 .expect("output");
468 let mut processor = TSProcessor::new(Report::null().expect("report")).expect("processor");
469 let token = processor.abort_token();
470 processor
471 .start(&ProcessorConfig {
472 input: Some(ProcessorInput::Native(PluginOptions::new("null", ["1"]))),
473 output: Some(ProcessorOutput::Memory(Arc::clone(&output))),
474 ..ProcessorConfig::default()
475 })
476 .expect("start");
477 processor.wait_for_termination().expect("wait");
478 token.request();
479 drop(processor);
480 token.request();
481 assert_eq!(
482 output.recv_shared().expect("drain").expect("packet").len(),
483 TS_PACKET_SIZE
484 );
485 assert_eq!(output.recv_shared().expect("EOF"), None);
486 }
487
488 #[test]
489 fn rejects_untyped_memory_plugin_before_native_state_changes() {
490 let _lock = crate::host::native_test_lock();
491 let report = Report::null().expect("report");
492 let mut processor = TSProcessor::new(report).expect("processor");
493 let config = ProcessorConfig {
494 input: Some(ProcessorInput::Native(PluginOptions::without_arguments(
495 "memory",
496 ))),
497 ..ProcessorConfig::default()
498 };
499 assert!(matches!(
500 processor.start(&config),
501 Err(Error::InvalidArgument { .. })
502 ));
503 assert_eq!(processor.state(), HostState::Created);
504 }
505
506 #[test]
507 fn abort_token_is_send_and_sync_and_becomes_a_no_op_after_owner_drop() {
508 fn assert_send_sync<T: Send + Sync>() {}
509 assert_send_sync::<AbortToken>();
510
511 let token = {
512 let _lock = crate::host::native_test_lock();
513 let report = Report::null().expect("report");
514 let processor = TSProcessor::new(report).expect("processor");
515 processor.abort_token()
516 };
517 thread::spawn(move || token.request())
518 .join()
519 .expect("post-drop request must not access deleted native processor");
520 }
521
522 #[test]
523 fn failed_native_start_keeps_memory_lease_until_owner_drop() {
524 let _lock = crate::host::native_test_lock();
525 let report = Report::null().expect("report");
526 let input = MemoryInput::new(
527 NonZeroUsize::new(TS_PACKET_SIZE).expect("capacity"),
528 MemoryQueuePolicy::Drop,
529 )
530 .expect("input");
531 let mut processor = TSProcessor::new(report).expect("processor");
532 let config = ProcessorConfig {
533 input: Some(ProcessorInput::Memory(Arc::clone(&input))),
534 output: Some(ProcessorOutput::Native(PluginOptions::without_arguments(
535 "rustduck-definitely-not-a-plugin",
536 ))),
537 ..ProcessorConfig::default()
538 };
539 assert!(matches!(
540 processor.start(&config),
541 Err(Error::NativeFailure {
542 operation: "TSProcessor::start"
543 })
544 ));
545 assert_eq!(processor.state(), HostState::Failed);
546 assert!(matches!(input.bind(), Err(Error::InvalidState { .. })));
547 drop(processor);
548 input.bind().expect("lease released after owner deletion");
549 }
550}