Skip to main content

rustduck_core/
processor.rs

1//! Typed, single-threaded `TSProcessor` lifecycle management.
2
3use 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/// Result of an owner-thread non-blocking termination check.
19#[derive(Debug, Clone, Copy, PartialEq, Eq)]
20#[non_exhaustive]
21pub enum WaitStatus {
22    /// Native processing is still active.
23    Pending,
24    /// Native processing has terminated.
25    Stopped,
26}
27
28/// A cloneable, thread-safe request-only processor stop token.
29///
30/// `request` may be called from any thread, including while the owner is in
31/// [`TSProcessor::start`]. It neither waits for termination nor exposes a
32/// native owner; the thread holding [`TSProcessor`] must still wait before it
33/// drops that owner. Requests after native deletion are no-ops.
34#[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
45// SAFETY: the token's C++ implementation serializes access to its native
46// processor pointer, waits for in-flight requests before deletion, and turns
47// requests after deletion into no-ops. It exposes no owner, wait, or delete
48// operation to the receiving thread. Rust endpoint access is synchronized by
49// its own mutex, and both endpoint types are Send + Sync.
50unsafe impl Send for AbortToken {}
51
52// SAFETY: `request` is the public operation and the C++ token protects its full
53// state with a mutex. The Rust endpoint state also uses a mutex, so concurrent
54// immutable Rust references are safe.
55unsafe impl Sync for AbortToken {}
56
57impl AbortToken {
58    /// Requests native processing termination without waiting for it.
59    ///
60    /// This is idempotent and remains safe while the owner is destroying the
61    /// processor; a request made after deletion is ignored. Bound memory queues
62    /// are aborted before the native request, waking blocked callbacks and callers.
63    pub fn request(&self) {
64        {
65            // Lock order is endpoint attachment, then queue. Owner cleanup
66            // detaches under this same lock, draining access to its endpoints.
67            // Release this guard before calling native code.
68            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            // The C++ token contains native exceptions and a closed token is a
83            // documented no-op. This request-only API intentionally has no
84            // caller-actionable failure mode.
85            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
97/// A `!Send + !Sync` TSDuck processor owner.
98///
99/// `native` is declared before the report, private handler, and endpoint
100/// leases. Therefore the native processor is deleted before any object it can
101/// borrow. `Drop` aborts and waits for active work before that deletion.
102pub 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    /// Creates a processor bound to `report`.
117    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    /// Returns the report retained for the processor's native lifetime.
144    pub fn report(&self) -> &Rc<Report> {
145        &self.report
146    }
147
148    /// Returns the observable host lifecycle state.
149    pub const fn state(&self) -> HostState {
150        self.state
151    }
152
153    /// Returns a cloneable token that can request termination from any thread.
154    ///
155    /// The token is request-only: native waiting and destruction remain on the
156    /// thread that owns this processor.
157    pub fn abort_token(&self) -> AbortToken {
158        self.abort_token.clone()
159    }
160
161    /// Starts native processing with typed plugins and optional memory endpoints.
162    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        // From here registrations can have modified native state. Store all
191        // dependencies before calling native code; any subsequent failure is
192        // terminal and releases the leases only after native deletion in Drop.
193        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    /// Requests processor abort. The host remains owned by this thread.
229    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    /// Performs a non-blocking owner-thread termination check.
238    ///
239    /// This is intentionally a native state probe, not a helper-thread wait.
240    /// A returned [`WaitStatus::Stopped`] has the same cleanup effect as
241    /// [`Self::wait_for_termination`].
242    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            // `isStarted` reports false only once native processing has ended.
256            // Call the native owner-thread wait anyway so this transition has
257            // exactly the same join/cleanup semantics as blocking wait.
258            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    /// Waits for native processing to terminate.
267    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    /// Takes the latest structured error produced by a bound memory endpoint.
283    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        // `native` drops first by field order. Its deletion precedes handler
359        // destruction and release of endpoint bindings.
360    }
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 a regressed implementation before joining its native owner.
402        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}