Skip to main content

video_interop/
beam.rs

1use std::panic::{AssertUnwindSafe, catch_unwind};
2use std::process;
3use std::sync::atomic::{AtomicU8, AtomicUsize, Ordering};
4use std::sync::mpsc::{Receiver, Sender, channel};
5use std::sync::{Arc, Mutex, MutexGuard, TryLockError};
6use std::thread::{self, JoinHandle};
7use std::time::{Duration, Instant};
8
9use rustler::env::{OwnedEnv, SavedTerm};
10use rustler::types::reference::Reference;
11use rustler::{Encoder, LocalPid, NifStruct, Resource, ResourceArc, Term};
12
13use crate::{
14    AcquireSync, DispatcherError, Format, FrameDescriptor, OwnedFrame, PrepareError, Rect, Storage,
15};
16
17mod atoms {
18    rustler::atoms! {
19        video_interop_release,
20        video_interop_abandoned
21    }
22}
23
24const HEALTHY: u8 = 0;
25const STOPPING: u8 = 1;
26const STOPPED: u8 = 2;
27const FAILED: u8 = 3;
28
29#[derive(Clone, NifStruct)]
30#[module = "VideoInterop.Lease"]
31pub struct Lease<'a> {
32    pub owner: LocalPid,
33    pub token: Term<'a>,
34    pub holder: Reference<'a>,
35    pub abandonment_guard: Term<'a>,
36}
37
38#[derive(Clone, NifStruct)]
39#[module = "VideoInterop.Frame"]
40pub struct Frame<'a> {
41    pub coded_width: u32,
42    pub coded_height: u32,
43    pub visible_rect: Rect,
44    pub format: Option<Format>,
45    pub storage: Storage,
46    pub acquire_sync: AcquireSync,
47    pub lease: Option<Lease<'a>>,
48}
49
50#[derive(Clone, Copy, Debug, Eq, PartialEq)]
51pub enum DispatcherHealth {
52    Healthy,
53    Stopping,
54    Stopped,
55    Failed,
56}
57
58enum MessageKind {
59    Release,
60    Abandoned,
61}
62
63struct DispatchCommand {
64    kind: MessageKind,
65    owner: Option<LocalPid>,
66    environment: OwnedEnv,
67    token: Option<SavedTerm>,
68    holder: Option<SavedTerm>,
69}
70
71enum WorkerCommand {
72    Dispatch(DispatchCommand),
73    Stop,
74    #[cfg(feature = "test-support")]
75    DelayForTest(Duration),
76    #[cfg(feature = "test-support")]
77    FailForTest,
78}
79
80struct DispatcherState {
81    worker: Option<JoinHandle<()>>,
82    stop_enqueued: bool,
83    joining: bool,
84}
85
86/// Lifecycle-owned dispatcher for normal and fallback lease messages.
87///
88/// A producer or consumer owns the root Rustler resource. Prepared and claimed
89/// leases hold counted clients that pin the resource until release has been
90/// queued. Guards also pin the resource, but become inert after lifecycle close
91/// so stale already-retired BEAM terms cannot keep shutdown waiting forever.
92///
93/// The lifecycle owner must call [`ReleaseDispatcher::close_and_join`] from a
94/// dirty-I/O NIF after every holder and claim drains. Resource destructors never
95/// wait or join. Dropping the last reference before an explicit join is fatal
96/// to prevent a worker from executing unloaded NIF code.
97pub struct ReleaseDispatcher {
98    sender: Sender<WorkerCommand>,
99    state: Mutex<DispatcherState>,
100    health: Arc<AtomicU8>,
101    undelivered_commands: Arc<AtomicUsize>,
102    active_clients: AtomicUsize,
103}
104
105#[derive(Clone)]
106pub struct DispatcherProbe {
107    health: Arc<AtomicU8>,
108    undelivered_commands: Arc<AtomicUsize>,
109}
110
111impl DispatcherProbe {
112    pub fn health(&self) -> DispatcherHealth {
113        decode_health(self.health.load(Ordering::Acquire))
114    }
115
116    pub fn undelivered_commands(&self) -> usize {
117        self.undelivered_commands.load(Ordering::Acquire)
118    }
119}
120
121#[rustler::resource_impl]
122impl Resource for ReleaseDispatcher {}
123
124impl ReleaseDispatcher {
125    /// Starts a dispatcher and returns its lifecycle-owner resource.
126    pub fn start(name: impl Into<String>) -> Result<ResourceArc<Self>, DispatcherError> {
127        let (sender, receiver) = channel();
128        let health = Arc::new(AtomicU8::new(HEALTHY));
129        let worker_health = Arc::clone(&health);
130        let undelivered_commands = Arc::new(AtomicUsize::new(0));
131        let worker_undelivered = Arc::clone(&undelivered_commands);
132
133        let worker = thread::Builder::new()
134            .name(name.into())
135            .spawn(move || dispatch_worker(receiver, worker_health, worker_undelivered))
136            .map_err(|error| DispatcherError::new(error.to_string()))?;
137
138        Ok(ResourceArc::new(Self {
139            sender,
140            state: Mutex::new(DispatcherState {
141                worker: Some(worker),
142                stop_enqueued: false,
143                joining: false,
144            }),
145            health,
146            undelivered_commands,
147            active_clients: AtomicUsize::new(0),
148        }))
149    }
150
151    #[cfg(feature = "test-support")]
152    #[doc(hidden)]
153    pub fn inject_startup_failure_for_test() -> Result<ResourceArc<Self>, DispatcherError> {
154        Err(DispatcherError::new("injected dispatcher startup failure"))
155    }
156
157    pub fn health(&self) -> DispatcherHealth {
158        decode_health(self.health.load(Ordering::Acquire))
159    }
160
161    pub fn probe(&self) -> DispatcherProbe {
162        DispatcherProbe {
163            health: Arc::clone(&self.health),
164            undelivered_commands: Arc::clone(&self.undelivered_commands),
165        }
166    }
167
168    /// Stops admission, waits for all prepared/claimed clients, drains the FIFO,
169    /// and joins the worker. This function blocks and must only be called by a
170    /// lifecycle-owned dirty-I/O NIF (or a native non-BEAM thread).
171    ///
172    /// A timeout leaves the dispatcher in `Stopping`; the owner resource and
173    /// worker remain live. A later call retries the join.
174    pub fn close_and_join(&self, timeout: Duration) -> Result<(), DispatcherError> {
175        let deadline = Instant::now()
176            .checked_add(timeout)
177            .ok_or_else(|| DispatcherError::new("dispatcher close timeout is too large"))?;
178        self.begin_close()?;
179        self.wait_for_clients(deadline)?;
180        self.enqueue_stop_once(deadline)?;
181        self.wait_for_worker_exit_and_join(deadline)
182    }
183
184    fn begin_close(&self) -> Result<(), DispatcherError> {
185        loop {
186            match decode_health(self.health.load(Ordering::SeqCst)) {
187                DispatcherHealth::Healthy => {
188                    if self
189                        .health
190                        .compare_exchange(HEALTHY, STOPPING, Ordering::SeqCst, Ordering::SeqCst)
191                        .is_ok()
192                    {
193                        return Ok(());
194                    }
195                }
196                DispatcherHealth::Stopping | DispatcherHealth::Stopped => return Ok(()),
197                DispatcherHealth::Failed => {
198                    return Err(DispatcherError::new("dispatcher is Failed"));
199                }
200            }
201        }
202    }
203
204    fn wait_for_clients(&self, deadline: Instant) -> Result<(), DispatcherError> {
205        while self.active_clients.load(Ordering::SeqCst) != 0 {
206            sleep_until_retry(deadline).map_err(|_| {
207                DispatcherError::new("timed out waiting for dispatcher clients to retire")
208            })?;
209        }
210        Ok(())
211    }
212
213    fn enqueue_stop_once(&self, deadline: Instant) -> Result<(), DispatcherError> {
214        let mut state = self.lock_state_until(deadline)?;
215        if self.health() == DispatcherHealth::Stopped || state.stop_enqueued {
216            return Ok(());
217        }
218        if state.worker.is_none() {
219            return Err(DispatcherError::new("dispatcher worker is unavailable"));
220        }
221        if self.sender.send(WorkerCommand::Stop).is_err() {
222            fatal_dispatcher_corruption("dispatcher worker stopped before lifecycle join");
223        }
224        state.stop_enqueued = true;
225        Ok(())
226    }
227
228    fn wait_for_worker_exit_and_join(&self, deadline: Instant) -> Result<(), DispatcherError> {
229        loop {
230            if self.health() == DispatcherHealth::Stopped {
231                return Ok(());
232            }
233            if self.health() == DispatcherHealth::Failed {
234                return Err(DispatcherError::new("dispatcher is Failed"));
235            }
236
237            let worker = {
238                let mut state = self.lock_state_until(deadline)?;
239                match state.worker.as_ref() {
240                    Some(worker) if !state.joining && worker.is_finished() => {
241                        state.joining = true;
242                        state.worker.take()
243                    }
244                    Some(_) | None if state.joining => None,
245                    Some(_) => None,
246                    None => {
247                        return Err(DispatcherError::new("dispatcher worker is unavailable"));
248                    }
249                }
250            };
251
252            if let Some(worker) = worker {
253                if worker.thread().id() == thread::current().id() {
254                    fatal_dispatcher_corruption("dispatcher attempted to join its own worker");
255                }
256                // `is_finished()` proved the thread has exited, so this join only
257                // collects its result and cannot wait for FIFO work.
258                if worker.join().is_err() {
259                    fatal_dispatcher_corruption("dispatcher worker panicked during shutdown");
260                }
261                // Publish completion only after `join` collected the already-finished
262                // worker. Concurrent closers now return without touching the
263                // lifecycle mutex, even if this caller is descheduled afterward.
264                self.health.store(STOPPED, Ordering::SeqCst);
265                return Ok(());
266            }
267
268            sleep_until_retry(deadline).map_err(|_| {
269                DispatcherError::new("timed out waiting for dispatcher worker to drain")
270            })?;
271        }
272    }
273
274    fn lock_state_until(
275        &self,
276        deadline: Instant,
277    ) -> Result<MutexGuard<'_, DispatcherState>, DispatcherError> {
278        loop {
279            match self.state.try_lock() {
280                Ok(state) => return Ok(state),
281                Err(TryLockError::Poisoned(_)) => {
282                    return Err(DispatcherError::new("dispatcher state lock poisoned"));
283                }
284                Err(TryLockError::WouldBlock) => sleep_until_retry(deadline).map_err(|_| {
285                    DispatcherError::new("timed out waiting for dispatcher close ownership")
286                })?,
287            }
288        }
289    }
290
291    fn acquire_client(dispatcher: &ResourceArc<Self>) -> Result<DispatcherClient, DispatcherError> {
292        if decode_health(dispatcher.health.load(Ordering::SeqCst)) != DispatcherHealth::Healthy {
293            return Err(DispatcherError::new(format!(
294                "dispatcher is {:?}",
295                dispatcher.health()
296            )));
297        }
298
299        dispatcher.active_clients.fetch_add(1, Ordering::SeqCst);
300        if decode_health(dispatcher.health.load(Ordering::SeqCst)) == DispatcherHealth::Healthy {
301            Ok(DispatcherClient {
302                dispatcher: dispatcher.clone(),
303            })
304        } else {
305            dispatcher.release_client();
306            Err(DispatcherError::new(format!(
307                "dispatcher is {:?}",
308                dispatcher.health()
309            )))
310        }
311    }
312
313    fn release_client(&self) {
314        let previous = self.active_clients.fetch_sub(1, Ordering::SeqCst);
315        if previous == 0 {
316            fatal_dispatcher_corruption("dispatcher client count underflow");
317        }
318    }
319
320    fn with_guard_admission<T>(
321        dispatcher: &ResourceArc<Self>,
322        operation: impl FnOnce() -> T,
323    ) -> Result<T, DispatcherError> {
324        let permit = Self::acquire_client(dispatcher)?;
325        let result = operation();
326        drop(permit);
327        Ok(result)
328    }
329
330    fn dispatch_abandoned(dispatcher: &ResourceArc<Self>, command: DispatchCommand) {
331        match Self::acquire_client(dispatcher) {
332            Ok(client) => client.dispatch(command),
333            Err(_)
334                if matches!(
335                    dispatcher.health(),
336                    DispatcherHealth::Stopping | DispatcherHealth::Stopped
337                ) =>
338            {
339                // Exact lifecycle drainage makes a late guard for an already
340                // retired holder a safe no-op after admission closes.
341            }
342            Err(_) => fatal_dispatcher_corruption(
343                "abandonment guard could not acquire its published dispatcher",
344            ),
345        }
346    }
347
348    fn sender_for_published(&self) -> Sender<WorkerCommand> {
349        self.sender.clone()
350    }
351
352    #[cfg(feature = "test-support")]
353    #[doc(hidden)]
354    pub fn inject_dispatch_delay_for_test(&self, delay: Duration) -> Result<(), DispatcherError> {
355        if self.health() != DispatcherHealth::Healthy {
356            return Err(DispatcherError::new(format!(
357                "dispatcher is {:?}",
358                self.health()
359            )));
360        }
361        self.sender
362            .send(WorkerCommand::DelayForTest(delay))
363            .map_err(|_| DispatcherError::new("dispatcher worker stopped unexpectedly"))
364    }
365
366    #[cfg(feature = "test-support")]
367    #[doc(hidden)]
368    pub fn inject_worker_panic_for_test(&self) {
369        let command = DispatchCommand::panic_for_test();
370        let sender = self.sender_for_published();
371        if sender.send(WorkerCommand::Dispatch(command)).is_err() {
372            fatal_dispatcher_corruption("dispatcher worker stopped unexpectedly");
373        }
374    }
375
376    #[cfg(feature = "test-support")]
377    #[doc(hidden)]
378    pub fn inject_enqueue_failure_for_test(&self) {
379        self.health.store(FAILED, Ordering::Release);
380        let _ = self.sender.send(WorkerCommand::FailForTest);
381    }
382}
383
384impl Drop for ReleaseDispatcher {
385    fn drop(&mut self) {
386        if self.health.load(Ordering::Acquire) != STOPPED {
387            fatal_dispatcher_corruption("dispatcher owner dropped without explicit close_and_join");
388        }
389    }
390}
391
392struct DispatcherClient {
393    dispatcher: ResourceArc<ReleaseDispatcher>,
394}
395
396impl DispatcherClient {
397    fn dispatch(self, command: DispatchCommand) {
398        let sender = self.dispatcher.sender_for_published();
399        if sender.send(WorkerCommand::Dispatch(command)).is_err() {
400            fatal_dispatcher_corruption("dispatcher worker stopped unexpectedly");
401        }
402    }
403}
404
405impl Drop for DispatcherClient {
406    fn drop(&mut self) {
407        self.dispatcher.release_client();
408    }
409}
410
411/// Fallback resource attached to one lease holder.
412pub struct AbandonmentGuard {
413    dispatcher: ResourceArc<ReleaseDispatcher>,
414    command: Mutex<Option<DispatchCommand>>,
415}
416
417#[rustler::resource_impl]
418impl Resource for AbandonmentGuard {}
419
420impl Drop for AbandonmentGuard {
421    fn drop(&mut self) {
422        let command = match self.command.get_mut() {
423            Ok(command) => command.take(),
424            Err(_) => fatal_dispatcher_corruption("abandonment guard lock poisoned"),
425        };
426
427        if let Some(command) = command {
428            ReleaseDispatcher::dispatch_abandoned(&self.dispatcher, command);
429        }
430    }
431}
432
433/// Creates the resource used by a thin producer-NIF guard constructor.
434///
435/// Guard creation is pre-publication and reports ordinary admission errors.
436/// Once returned to BEAM, enqueue loss while accepting is fatal lifecycle
437/// corruption. After lifecycle close, a stale guard is inert.
438/// Returns whether a term is this producer NIF's registered guard resource.
439/// Producer authority callbacks must expose this constant-time check.
440pub fn is_abandonment_guard_resource(term: Term<'_>) -> bool {
441    term.decode::<ResourceArc<AbandonmentGuard>>().is_ok()
442}
443
444pub fn new_abandonment_guard<'a>(
445    dispatcher: ResourceArc<ReleaseDispatcher>,
446    owner: LocalPid,
447    token: Term<'a>,
448    holder: Reference<'a>,
449) -> Result<ResourceArc<AbandonmentGuard>, DispatcherError> {
450    ReleaseDispatcher::with_guard_admission(&dispatcher, || {
451        ResourceArc::new(AbandonmentGuard {
452            dispatcher: dispatcher.clone(),
453            command: Mutex::new(Some(DispatchCommand::new(
454                MessageKind::Abandoned,
455                owner,
456                token,
457                Term::from(holder),
458            ))),
459        })
460    })
461}
462
463pub struct PreparedLease {
464    command: DispatchCommand,
465    guard: GuardKeepalive,
466    client: DispatcherClient,
467}
468
469pub struct ClaimedLease {
470    command: Option<DispatchCommand>,
471    guard: Option<GuardKeepalive>,
472    client: Option<DispatcherClient>,
473}
474
475pub struct PreparedVideoFrame {
476    frame: OwnedFrame,
477    lease: Option<PreparedLease>,
478}
479
480pub struct ClaimedVideoFrame {
481    pub frame: OwnedFrame,
482    pub lease: Option<ClaimedLease>,
483}
484
485struct GuardKeepalive {
486    _environment: OwnedEnv,
487    _guard: SavedTerm,
488}
489
490impl Lease<'_> {
491    fn prepare(&self, client: DispatcherClient) -> PreparedLease {
492        let command = DispatchCommand::new(
493            MessageKind::Release,
494            self.owner,
495            self.token,
496            Term::from(self.holder),
497        );
498
499        let guard_environment = OwnedEnv::new();
500        let guard = guard_environment.save(self.abandonment_guard);
501
502        PreparedLease {
503            command,
504            guard: GuardKeepalive {
505                _environment: guard_environment,
506                _guard: guard,
507            },
508            client,
509        }
510    }
511}
512
513impl Frame<'_> {
514    /// Validates and owns the frame storage while leaving any lease release
515    /// ownership with the Elixir caller. Binary bytes are copied; borrowed file
516    /// descriptors are duplicated with `CLOEXEC`.
517    ///
518    /// For borrowed storage, the entire abandonment authority envelope is saved
519    /// opaquely. Call [`PreparedVideoFrame::claim`] only after the native
520    /// subsystem has accepted responsibility for eventual retirement. Owned
521    /// binary storage has no lease to transfer.
522    pub fn prepare_cloexec(
523        &self,
524        dispatcher: &ResourceArc<ReleaseDispatcher>,
525    ) -> Result<PreparedVideoFrame, PrepareError> {
526        let lease = match (&self.storage, &self.lease) {
527            (Storage::Binary(_), None) => None,
528            (Storage::Binary(_), Some(_)) => return Err(PrepareError::UnexpectedLease),
529            (Storage::DmaBuf(_), None) => return Err(PrepareError::MissingLease),
530            (Storage::DmaBuf(_), Some(lease)) => {
531                let client = ReleaseDispatcher::acquire_client(dispatcher)?;
532                Some(lease.prepare(client))
533            }
534        };
535
536        let descriptor = FrameDescriptor {
537            coded_width: self.coded_width,
538            coded_height: self.coded_height,
539            visible_rect: self.visible_rect.clone(),
540            storage: self.storage.clone(),
541            acquire_sync: self.acquire_sync.clone(),
542        };
543
544        let frame = descriptor.duplicate_cloexec()?;
545        Ok(PreparedVideoFrame { frame, lease })
546    }
547}
548
549impl PreparedVideoFrame {
550    pub fn frame(&self) -> &OwnedFrame {
551        &self.frame
552    }
553
554    /// Transfers release responsibility and the opaque guard
555    /// envelope to native code.
556    pub fn claim(self) -> ClaimedVideoFrame {
557        ClaimedVideoFrame {
558            frame: self.frame,
559            lease: self.lease.map(|lease| ClaimedLease {
560                command: Some(lease.command),
561                guard: Some(lease.guard),
562                client: Some(lease.client),
563            }),
564        }
565    }
566}
567
568impl ClaimedVideoFrame {
569    pub fn into_parts(self) -> (OwnedFrame, Option<ClaimedLease>) {
570        (self.frame, self.lease)
571    }
572}
573
574impl ClaimedLease {
575    /// Queues producer release. The guard envelope remains live
576    /// until the worker accepts the release command.
577    pub fn retire(mut self) {
578        self.dispatch_release();
579    }
580
581    fn dispatch_release(&mut self) {
582        if let Some(command) = self.command.take() {
583            let client = self.client.take().unwrap_or_else(|| {
584                fatal_dispatcher_corruption("claimed lease lost its dispatcher client")
585            });
586            client.dispatch(command);
587            drop(self.guard.take());
588        }
589    }
590}
591
592impl Drop for ClaimedLease {
593    fn drop(&mut self) {
594        self.dispatch_release();
595    }
596}
597
598impl DispatchCommand {
599    fn new(kind: MessageKind, owner: LocalPid, token: Term<'_>, holder: Term<'_>) -> Self {
600        let environment = OwnedEnv::new();
601        let token = environment.save(token);
602        let holder = environment.save(holder);
603
604        Self {
605            kind,
606            owner: Some(owner),
607            environment,
608            token: Some(token),
609            holder: Some(holder),
610        }
611    }
612
613    #[cfg(feature = "test-support")]
614    fn panic_for_test() -> Self {
615        Self {
616            kind: MessageKind::Release,
617            owner: None,
618            environment: OwnedEnv::new(),
619            token: None,
620            holder: None,
621        }
622    }
623
624    fn send(mut self) -> Result<(), rustler::env::SendError> {
625        let owner = self
626            .owner
627            .take()
628            .unwrap_or_else(|| panic!("injected dispatcher worker panic"));
629        let tag = match self.kind {
630            MessageKind::Release => atoms::video_interop_release(),
631            MessageKind::Abandoned => atoms::video_interop_abandoned(),
632        };
633        let token = self.token.take().expect("dispatch token missing");
634        let holder = self.holder.take().expect("dispatch holder missing");
635
636        self.environment.send_and_clear(&owner, move |env| {
637            (tag, token.load(env), holder.load(env)).encode(env)
638        })
639    }
640}
641
642fn dispatch_worker(
643    receiver: Receiver<WorkerCommand>,
644    health: Arc<AtomicU8>,
645    undelivered_commands: Arc<AtomicUsize>,
646) {
647    let result = catch_unwind(AssertUnwindSafe(|| {
648        loop {
649            match receiver.recv() {
650                Ok(WorkerCommand::Dispatch(command)) => {
651                    if command.send().is_err() {
652                        // The local recipient exited. Its producer/owner-crash destructor is now
653                        // authoritative; the dispatcher worker and FIFO remain healthy.
654                        undelivered_commands.fetch_add(1, Ordering::Relaxed);
655                    }
656                }
657                Ok(WorkerCommand::Stop) => break,
658                #[cfg(feature = "test-support")]
659                Ok(WorkerCommand::DelayForTest(delay)) => thread::sleep(delay),
660                #[cfg(feature = "test-support")]
661                Ok(WorkerCommand::FailForTest) => break,
662                Err(_) => {
663                    if health.load(Ordering::Acquire) != STOPPING {
664                        fatal_dispatcher_corruption(
665                            "dispatcher worker stopped outside lifecycle shutdown",
666                        );
667                    }
668                    break;
669                }
670            }
671        }
672    }));
673
674    if result.is_err() {
675        health.store(FAILED, Ordering::Release);
676        fatal_dispatcher_corruption("dispatcher worker panicked");
677    }
678}
679
680fn sleep_until_retry(deadline: Instant) -> Result<(), ()> {
681    let remaining = deadline.checked_duration_since(Instant::now()).ok_or(())?;
682    if remaining.is_zero() {
683        return Err(());
684    }
685    thread::sleep(remaining.min(Duration::from_millis(1)));
686    Ok(())
687}
688
689fn decode_health(value: u8) -> DispatcherHealth {
690    match value {
691        HEALTHY => DispatcherHealth::Healthy,
692        STOPPING => DispatcherHealth::Stopping,
693        STOPPED => DispatcherHealth::Stopped,
694        _ => DispatcherHealth::Failed,
695    }
696}
697
698fn fatal_dispatcher_corruption(reason: &str) -> ! {
699    eprintln!("video_interop fatal dispatcher corruption: {reason}");
700    process::abort()
701}