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
86pub 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 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 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 if worker.join().is_err() {
259 fatal_dispatcher_corruption("dispatcher worker panicked during shutdown");
260 }
261 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 }
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
411pub 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
433pub 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 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 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 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 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}