1use core::{fmt, marker::PhantomData, panic::AssertUnwindSafe};
13use std::{
14 cell::Cell,
15 collections::{HashMap, VecDeque},
16 sync::{
17 Arc, Condvar, Mutex, OnceLock, Weak,
18 atomic::{AtomicBool, AtomicU8, AtomicU64, Ordering},
19 },
20 time::{Duration, Instant},
21};
22
23use crate::{
24 DiagnosticCode, DiagnosticEvent, DiagnosticSeverity, ExcelCallError, ExcelValue,
25 LifecycleContext, MacroContext, ThreadSafeContext, WorksheetContext,
26};
27
28const QUEUED: u8 = 0;
29const SELECTED: u8 = 1;
30const RUNNING: u8 = 2;
31const COMPLETED: u8 = 3;
32const FAILED: u8 = 4;
33const CANCELED: u8 = 5;
34const EXPIRED: u8 = 6;
35const SHUTDOWN: u8 = 7;
36
37const EVENT_ENQUEUE_ACCEPTED: i32 = 1;
38const EVENT_ENQUEUE_REJECTED: i32 = 2;
39const EVENT_SELECTED: i32 = 3;
40const EVENT_EXECUTED: i32 = 4;
41const EVENT_CANCELED: i32 = 5;
42const EVENT_EXPIRED: i32 = 6;
43const EVENT_COMPLETED: i32 = 7;
44const EVENT_FAILED: i32 = 8;
45const EVENT_SHUTDOWN: i32 = 9;
46const EVENT_INCOMPATIBLE_SKIPPED: i32 = 10;
47const EVENT_NESTED_SUPPRESSED: i32 = 11;
48const EVENT_INTERNAL_INVARIANT: i32 = 12;
49const MAXIMUM_CONDVAR_WAIT_SLICE: Duration = Duration::from_secs(24 * 60 * 60);
50
51#[derive(Clone, Copy, Debug, Eq, PartialEq)]
53pub struct DispatchConfig {
54 pub maximum_pending: usize,
56 pub maximum_batch_per_drain: usize,
58 pub default_timeout: Option<Duration>,
60 pub maximum_drain_duration: Option<Duration>,
62}
63
64impl Default for DispatchConfig {
65 fn default() -> Self {
66 Self {
67 maximum_pending: 64,
68 maximum_batch_per_drain: 16,
69 default_timeout: Some(Duration::from_secs(300)),
70 maximum_drain_duration: Some(Duration::from_millis(50)),
71 }
72 }
73}
74
75impl DispatchConfig {
76 fn normalized(self) -> Option<Self> {
77 (self.maximum_pending > 0 && self.maximum_batch_per_drain > 0).then_some(self)
78 }
79}
80
81#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
83pub enum DispatchRequirement {
84 ContextNeutral,
86 ThreadSafeWorksheet,
88 Worksheet,
90 Macro,
92 Lifecycle,
94}
95
96#[derive(Clone, Debug, PartialEq)]
98pub enum DispatchOperation {
99 EchoOwned(ExcelValue),
101 PollCancellationPreservingBreak,
103 #[cfg(test)]
104 TestEnqueueNested(ExcelValue),
106 #[cfg(test)]
107 TestNestedMacroDrain,
109 #[cfg(test)]
110 TestBlock,
112 #[cfg(test)]
113 TestPanic,
115}
116
117impl DispatchOperation {
118 pub const fn requirement(&self) -> DispatchRequirement {
120 match self {
121 Self::EchoOwned(_) => DispatchRequirement::ContextNeutral,
122 Self::PollCancellationPreservingBreak => DispatchRequirement::Macro,
123 #[cfg(test)]
124 Self::TestEnqueueNested(_) | Self::TestBlock | Self::TestPanic => {
125 DispatchRequirement::ContextNeutral
126 }
127 #[cfg(test)]
128 Self::TestNestedMacroDrain => DispatchRequirement::Macro,
129 }
130 }
131
132 pub const fn calls_excel(&self) -> bool {
134 match self {
135 Self::PollCancellationPreservingBreak => true,
136 #[cfg(test)]
137 Self::TestNestedMacroDrain => true,
138 _ => false,
139 }
140 }
141}
142
143#[derive(Clone, Debug, PartialEq)]
145pub enum DispatchResult {
146 OwnedValue(ExcelValue),
148 CancellationRequested(bool),
150}
151
152#[derive(Clone, Copy, Debug, Eq, PartialEq)]
153pub enum DispatchEnqueueError {
155 NoActiveGeneration,
157 QueueFull,
159 RuntimeClosing,
161 StaleGeneration,
163}
164
165impl fmt::Display for DispatchEnqueueError {
166 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
167 formatter.write_str(match self {
168 Self::NoActiveGeneration => "no cooperative dispatcher generation is active",
169 Self::QueueFull => "the cooperative dispatcher queue is full",
170 Self::RuntimeClosing => "the cooperative dispatcher generation is closing",
171 Self::StaleGeneration => "the cooperative dispatcher generation is stale",
172 })
173 }
174}
175
176impl std::error::Error for DispatchEnqueueError {}
177
178#[derive(Clone, Debug, Eq, PartialEq)]
180pub enum DispatchExecutionError {
181 IncompatibleContext {
183 required: DispatchRequirement,
185 actual: DispatchCallbackKind,
187 },
188 Excel(ExcelCallError),
190 Panicked,
192 InternalInvariant,
194}
195
196impl fmt::Display for DispatchExecutionError {
197 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
198 match self {
199 Self::IncompatibleContext { required, actual } => {
200 write!(
201 formatter,
202 "{actual:?} cannot execute {required:?} dispatch work"
203 )
204 }
205 Self::Excel(error) => write!(formatter, "dispatcher Excel call failed: {error}"),
206 Self::Panicked => formatter.write_str("dispatcher operation panicked"),
207 Self::InternalInvariant => {
208 formatter.write_str("dispatcher internal execution invariant failed")
209 }
210 }
211 }
212}
213
214impl std::error::Error for DispatchExecutionError {}
215
216#[derive(Clone, Debug, Eq, PartialEq)]
218pub enum DispatchCompletionError {
219 Canceled,
221 Expired,
223 DispatcherShutdown,
225 Operation(DispatchExecutionError),
227 WaitFromCallback,
229 WaitTimeout,
231}
232
233impl fmt::Display for DispatchCompletionError {
234 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
235 match self {
236 Self::Canceled => formatter.write_str("dispatch request was canceled"),
237 Self::Expired => formatter.write_str("dispatch request expired before execution"),
238 Self::DispatcherShutdown => {
239 formatter.write_str("dispatcher shut down before completion")
240 }
241 Self::Operation(error) => write!(formatter, "{error}"),
242 Self::WaitFromCallback => {
243 formatter.write_str("waiting is forbidden from an Excel callback")
244 }
245 Self::WaitTimeout => formatter.write_str("timed out waiting for dispatch completion"),
246 }
247 }
248}
249
250impl std::error::Error for DispatchCompletionError {}
251
252#[derive(Clone, Copy, Debug, Eq, PartialEq)]
254pub enum DispatchCancelOutcome {
255 Canceled,
257 TooLate,
259 AlreadyTerminal,
261}
262
263#[derive(Clone, Copy, Debug, Eq, PartialEq)]
265pub enum DispatchCallbackKind {
266 ThreadSafe,
268 Worksheet,
270 Macro,
272 Lifecycle,
274}
275
276impl DispatchCallbackKind {
277 pub const fn permits(self, requirement: DispatchRequirement) -> bool {
282 matches!(
283 (self, requirement),
284 (_, DispatchRequirement::ContextNeutral)
285 | (Self::ThreadSafe, DispatchRequirement::ThreadSafeWorksheet)
286 | (Self::Worksheet, DispatchRequirement::Worksheet)
287 | (Self::Macro, DispatchRequirement::Macro)
288 | (Self::Lifecycle, DispatchRequirement::Lifecycle)
289 )
290 }
291}
292
293#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
295pub struct DispatchDrainReport {
296 pub selected: usize,
298 pub processed: usize,
300 pub failed: usize,
302 pub expired: usize,
304 pub incompatible_skipped: usize,
306 pub nested_suppressed: bool,
308 pub duration_limit_reached: bool,
310}
311
312#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
314pub struct DispatchDiagnostics {
315 pub generation: u64,
317 pub pending: usize,
319 pub running: usize,
321 pub accepted: u64,
323 pub rejected: u64,
325 pub selected: u64,
327 pub executed: u64,
329 pub canceled: u64,
331 pub expired: u64,
333 pub completed: u64,
335 pub failed: u64,
337 pub shutdown_retired: u64,
339 pub incompatible_skipped: u64,
341 pub nested_suppressed: u64,
343}
344
345struct Completion {
346 result: Option<Result<DispatchResult, DispatchCompletionError>>,
347}
348
349struct Request {
350 id: u64,
351 generation: u64,
352 requirement: DispatchRequirement,
353 operation: Mutex<Option<DispatchOperation>>,
354 state: AtomicU8,
355 retired: AtomicBool,
356 completion: Mutex<Completion>,
357 ready: Condvar,
358 deadline: Option<Instant>,
359 owner: Weak<DispatchController>,
360 #[cfg(test)]
361 wait_returns: AtomicU64,
362}
363
364impl Request {
365 fn lock_completion(&self) -> std::sync::MutexGuard<'_, Completion> {
366 self.completion
367 .lock()
368 .unwrap_or_else(std::sync::PoisonError::into_inner)
369 }
370
371 fn publish(&self, state: u8, result: Result<DispatchResult, DispatchCompletionError>) -> bool {
372 let mut completion = self.lock_completion();
373 if completion.result.is_some() {
374 return false;
375 }
376 self.state.store(state, Ordering::Release);
377 completion.result = Some(result);
378 self.ready.notify_all();
379 true
380 }
381
382 fn retire(&self) {
383 if self.retired.swap(true, Ordering::AcqRel) {
384 return;
385 }
386 if let Some(owner) = self.owner.upgrade() {
387 owner.retire(self.id, self as *const Self);
388 }
389 }
390
391 fn expire_if_due(&self) {
392 if self
393 .deadline
394 .is_some_and(|deadline| Instant::now() >= deadline)
395 {
396 if let Some(owner) = self.owner.upgrade() {
397 owner.expire(self);
398 }
399 }
400 }
401}
402
403pub struct DispatchTicket {
408 request: Arc<Request>,
409}
410
411impl fmt::Debug for DispatchTicket {
412 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
413 formatter
414 .debug_struct("DispatchTicket")
415 .field("id", &self.id())
416 .field("generation", &self.generation())
417 .finish_non_exhaustive()
418 }
419}
420
421impl DispatchTicket {
422 pub fn id(&self) -> u64 {
424 self.request.id
425 }
426
427 pub fn generation(&self) -> u64 {
431 self.request.generation
432 }
433
434 pub fn try_result(&self) -> Option<Result<DispatchResult, DispatchCompletionError>> {
438 self.request.expire_if_due();
439 self.request.lock_completion().result.clone()
440 }
441
442 pub fn wait_timeout(
449 &self,
450 timeout: Duration,
451 ) -> Result<DispatchResult, DispatchCompletionError> {
452 if callback_depth() > 0 {
453 return Err(DispatchCompletionError::WaitFromCallback);
454 }
455 self.request.expire_if_due();
458 let wait_started = Instant::now();
459 let caller_deadline = wait_started.checked_add(timeout);
460 loop {
461 let completion = self.request.lock_completion();
462 if let Some(result) = completion.result.clone() {
463 return result;
464 }
465
466 let now = Instant::now();
467 let queued_deadline = (self.request.state.load(Ordering::Acquire) == QUEUED)
468 .then_some(self.request.deadline)
469 .flatten();
470 let caller_due = caller_deadline.is_some_and(|deadline| now >= deadline);
471 let request_due = queued_deadline.is_some_and(|deadline| now >= deadline);
472
473 if caller_due
477 && queued_deadline.is_none_or(|request_deadline| {
478 caller_deadline.is_some_and(|caller| caller < request_deadline)
479 })
480 {
481 return Err(DispatchCompletionError::WaitTimeout);
482 }
483 if request_due {
484 drop(completion);
485 self.request.expire_if_due();
486 continue;
487 }
488 let caller_remaining = caller_deadline.map_or_else(
489 || timeout.saturating_sub(wait_started.elapsed()),
490 |deadline| deadline.saturating_duration_since(now),
491 );
492 if caller_remaining.is_zero() {
493 return Err(DispatchCompletionError::WaitTimeout);
494 }
495
496 let request_remaining =
499 queued_deadline.map(|deadline| deadline.saturating_duration_since(now));
500 let wait_for = request_remaining
501 .map_or(caller_remaining, |remaining| {
502 remaining.min(caller_remaining)
503 })
504 .min(MAXIMUM_CONDVAR_WAIT_SLICE);
505 if wait_for.is_zero() {
506 drop(completion);
507 self.request.expire_if_due();
508 continue;
509 }
510
511 let (completion, _) = self
512 .request
513 .ready
514 .wait_timeout(completion, wait_for)
515 .unwrap_or_else(std::sync::PoisonError::into_inner);
516 #[cfg(test)]
517 self.request.wait_returns.fetch_add(1, Ordering::Relaxed);
518 drop(completion);
519 }
520 }
521
522 pub fn cancel(&self) -> DispatchCancelOutcome {
524 self.request
525 .owner
526 .upgrade()
527 .map_or(DispatchCancelOutcome::AlreadyTerminal, |owner| {
528 owner.cancel(&self.request)
529 })
530 }
531}
532
533#[derive(Clone)]
536pub struct DispatchGeneration {
537 controller: Arc<DispatchController>,
538}
539
540impl fmt::Debug for DispatchGeneration {
541 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
542 formatter
543 .debug_struct("DispatchGeneration")
544 .field("id", &self.id())
545 .finish_non_exhaustive()
546 }
547}
548
549impl DispatchGeneration {
550 pub fn id(&self) -> u64 {
552 self.controller.generation
553 }
554
555 pub fn enqueue(
560 &self,
561 operation: DispatchOperation,
562 ) -> Result<DispatchTicket, DispatchEnqueueError> {
563 if active_generation_id() != Some(self.id()) {
564 emit_request(EVENT_ENQUEUE_REJECTED, self.id());
565 self.controller
566 .diagnostics
567 .rejected
568 .fetch_add(1, Ordering::Relaxed);
569 return Err(DispatchEnqueueError::StaleGeneration);
570 }
571 self.controller.enqueue(operation)
572 }
573
574 pub fn diagnostics(&self) -> DispatchDiagnostics {
576 self.controller.diagnostics()
577 }
578}
579
580#[derive(Default)]
581struct Counters {
582 accepted: AtomicU64,
583 rejected: AtomicU64,
584 selected: AtomicU64,
585 executed: AtomicU64,
586 canceled: AtomicU64,
587 expired: AtomicU64,
588 completed: AtomicU64,
589 failed: AtomicU64,
590 shutdown_retired: AtomicU64,
591 incompatible_skipped: AtomicU64,
592 nested_suppressed: AtomicU64,
593}
594
595struct ControllerState {
596 active: bool,
597 pending: VecDeque<Arc<Request>>,
598 registry: HashMap<u64, Arc<Request>>,
599 running: usize,
600}
601
602struct DispatchController {
603 generation: u64,
604 config: DispatchConfig,
605 next_id: AtomicU64,
606 state: Mutex<ControllerState>,
607 idle: Condvar,
608 diagnostics: Counters,
609 #[cfg(test)]
610 before_start: Mutex<Option<Arc<TestPause>>>,
611 #[cfg(test)]
612 panic_after_start: AtomicBool,
613 #[cfg(test)]
614 clear_operation_after_start: AtomicBool,
615}
616
617impl DispatchController {
618 fn new(generation: u64, config: DispatchConfig) -> Arc<Self> {
619 Arc::new(Self {
620 generation,
621 config,
622 next_id: AtomicU64::new(1),
623 state: Mutex::new(ControllerState {
624 active: true,
625 pending: VecDeque::new(),
626 registry: HashMap::new(),
627 running: 0,
628 }),
629 idle: Condvar::new(),
630 diagnostics: Counters::default(),
631 #[cfg(test)]
632 before_start: Mutex::new(None),
633 #[cfg(test)]
634 panic_after_start: AtomicBool::new(false),
635 #[cfg(test)]
636 clear_operation_after_start: AtomicBool::new(false),
637 })
638 }
639
640 fn lock_state(&self) -> std::sync::MutexGuard<'_, ControllerState> {
641 self.state
642 .lock()
643 .unwrap_or_else(std::sync::PoisonError::into_inner)
644 }
645
646 fn enqueue(
647 self: &Arc<Self>,
648 operation: DispatchOperation,
649 ) -> Result<DispatchTicket, DispatchEnqueueError> {
650 let mut state = self.lock_state();
651 if !state.active {
652 self.diagnostics.rejected.fetch_add(1, Ordering::Relaxed);
653 emit_request(EVENT_ENQUEUE_REJECTED, self.generation);
654 return Err(DispatchEnqueueError::RuntimeClosing);
655 }
656 self.expire_locked(&mut state);
657 if state.registry.len() >= self.config.maximum_pending {
658 self.diagnostics.rejected.fetch_add(1, Ordering::Relaxed);
659 emit_request(EVENT_ENQUEUE_REJECTED, self.generation);
660 return Err(DispatchEnqueueError::QueueFull);
661 }
662 let id = self.next_id.fetch_add(1, Ordering::Relaxed);
663 let request = Arc::new(Request {
664 id,
665 generation: self.generation,
666 requirement: operation.requirement(),
667 operation: Mutex::new(Some(operation)),
668 state: AtomicU8::new(QUEUED),
669 retired: AtomicBool::new(false),
670 completion: Mutex::new(Completion { result: None }),
671 ready: Condvar::new(),
672 deadline: self
673 .config
674 .default_timeout
675 .and_then(|timeout| Instant::now().checked_add(timeout)),
676 owner: Arc::downgrade(self),
677 #[cfg(test)]
678 wait_returns: AtomicU64::new(0),
679 });
680 state.pending.push_back(request.clone());
681 state.registry.insert(id, request.clone());
682 drop(state);
683 self.diagnostics.accepted.fetch_add(1, Ordering::Relaxed);
684 emit_request(EVENT_ENQUEUE_ACCEPTED, correlation(self.generation, id));
685 Ok(DispatchTicket { request })
686 }
687
688 fn expire_locked(&self, state: &mut ControllerState) -> usize {
689 let now = Instant::now();
690 let mut expired = Vec::new();
691 state.pending.retain(|request| {
692 let due = request.deadline.is_some_and(|deadline| now >= deadline);
693 if due
694 && request
695 .state
696 .compare_exchange(QUEUED, EXPIRED, Ordering::AcqRel, Ordering::Acquire)
697 .is_ok()
698 {
699 expired.push(request.clone());
700 false
701 } else {
702 true
703 }
704 });
705 let expired_count = expired.len();
706 for request in expired {
707 if request.publish(EXPIRED, Err(DispatchCompletionError::Expired)) {
708 self.diagnostics.expired.fetch_add(1, Ordering::Relaxed);
709 emit_request(EVENT_EXPIRED, correlation(self.generation, request.id));
710 }
711 self.retire_locked(state, request.id, Arc::as_ptr(&request));
712 request.retired.store(true, Ordering::Release);
713 }
714 expired_count
715 }
716
717 fn expire(&self, request: &Request) {
718 let mut state = self.lock_state();
719 if request
720 .state
721 .compare_exchange(QUEUED, EXPIRED, Ordering::AcqRel, Ordering::Acquire)
722 .is_err()
723 {
724 return;
725 }
726 state
727 .pending
728 .retain(|pending| !core::ptr::eq(Arc::as_ptr(pending), request));
729 if request.publish(EXPIRED, Err(DispatchCompletionError::Expired)) {
730 self.diagnostics.expired.fetch_add(1, Ordering::Relaxed);
731 emit_request(EVENT_EXPIRED, correlation(self.generation, request.id));
732 }
733 self.retire_locked(&mut state, request.id, request as *const Request);
734 request.retired.store(true, Ordering::Release);
735 }
736
737 fn cancel(&self, request: &Request) -> DispatchCancelOutcome {
738 let mut state = self.lock_state();
739 let current = request.state.load(Ordering::Acquire);
740 if matches!(current, COMPLETED | FAILED | CANCELED | EXPIRED | SHUTDOWN) {
741 return DispatchCancelOutcome::AlreadyTerminal;
742 }
743 if current == RUNNING {
744 return DispatchCancelOutcome::TooLate;
745 }
746 if request
747 .state
748 .compare_exchange(current, CANCELED, Ordering::AcqRel, Ordering::Acquire)
749 .is_err()
750 {
751 drop(state);
752 return self.cancel(request);
753 }
754 state
755 .pending
756 .retain(|pending| !core::ptr::eq(Arc::as_ptr(pending), request));
757 if request.publish(CANCELED, Err(DispatchCompletionError::Canceled)) {
758 self.diagnostics.canceled.fetch_add(1, Ordering::Relaxed);
759 emit_request(EVENT_CANCELED, correlation(self.generation, request.id));
760 }
761 self.retire_locked(&mut state, request.id, request as *const Request);
762 request.retired.store(true, Ordering::Release);
763 DispatchCancelOutcome::Canceled
764 }
765
766 fn select(&self, kind: DispatchCallbackKind) -> (Vec<Arc<Request>>, usize, usize) {
767 let mut state = self.lock_state();
768 if !state.active {
769 return (Vec::new(), 0, 0);
770 }
771 let mut expired = self.expire_locked(&mut state);
772 let mut selected = Vec::with_capacity(self.config.maximum_batch_per_drain);
773 let mut retained = VecDeque::with_capacity(state.pending.len());
774 let mut incompatible = 0;
775 while let Some(request) = state.pending.pop_front() {
776 if request.state.load(Ordering::Acquire) == EXPIRED {
777 expired += 1;
778 continue;
779 }
780 if selected.len() < self.config.maximum_batch_per_drain
781 && kind.permits(request.requirement)
782 && request
783 .state
784 .compare_exchange(QUEUED, SELECTED, Ordering::AcqRel, Ordering::Acquire)
785 .is_ok()
786 {
787 self.diagnostics.selected.fetch_add(1, Ordering::Relaxed);
788 emit_request(EVENT_SELECTED, correlation(self.generation, request.id));
789 selected.push(request);
790 } else {
791 if !kind.permits(request.requirement) {
792 incompatible += 1;
793 }
794 retained.push_back(request);
795 }
796 }
797 state.pending = retained;
798 if incompatible > 0 {
799 self.diagnostics
800 .incompatible_skipped
801 .fetch_add(incompatible as u64, Ordering::Relaxed);
802 emit_request(EVENT_INCOMPATIBLE_SKIPPED, self.generation);
803 }
804 (selected, incompatible, expired)
805 }
806
807 fn try_start(self: &Arc<Self>, request: Arc<Request>) -> Option<RunningRequestGuard> {
808 let mut state = self.lock_state();
809 let registered = state
810 .registry
811 .get(&request.id)
812 .is_some_and(|entry| core::ptr::eq(Arc::as_ptr(entry), Arc::as_ptr(&request)));
813 if !state.active || !registered || request.generation != self.generation {
814 return None;
815 }
816 if request
817 .state
818 .compare_exchange(SELECTED, RUNNING, Ordering::AcqRel, Ordering::Acquire)
819 .is_ok()
820 {
821 state.running += 1;
822 Some(RunningRequestGuard {
823 controller: self.clone(),
824 request,
825 finished: false,
826 })
827 } else {
828 None
829 }
830 }
831
832 fn finish_running(
833 &self,
834 request: &Request,
835 result: Result<DispatchResult, DispatchExecutionError>,
836 ) {
837 if request.retired.swap(true, Ordering::AcqRel) {
838 return;
839 }
840 let (state_code, completion) = match result {
841 Ok(result) => (COMPLETED, Ok(result)),
842 Err(error) => (FAILED, Err(DispatchCompletionError::Operation(error))),
843 };
844 let published = request.publish(state_code, completion);
845 if published {
846 let (counter, event) = if state_code == COMPLETED {
847 (&self.diagnostics.completed, EVENT_COMPLETED)
848 } else {
849 (&self.diagnostics.failed, EVENT_FAILED)
850 };
851 counter.fetch_add(1, Ordering::Relaxed);
852 emit_request(event, correlation(self.generation, request.id));
853 }
854 let mut state = self.lock_state();
855 if state.running > 0 {
856 state.running -= 1;
857 } else {
858 emit_request(
859 EVENT_INTERNAL_INVARIANT,
860 correlation(self.generation, request.id),
861 );
862 }
863 self.retire_locked(&mut state, request.id, request as *const Request);
864 if state.running == 0 {
865 self.idle.notify_all();
866 }
867 }
868
869 fn requeue_selected(&self, requests: &[Arc<Request>]) {
870 let mut state = self.lock_state();
871 if !state.active {
872 drop(state);
873 for request in requests {
874 self.shutdown_selected(request);
875 }
876 return;
877 }
878 for request in requests.iter().rev() {
879 if request
880 .state
881 .compare_exchange(SELECTED, QUEUED, Ordering::AcqRel, Ordering::Acquire)
882 .is_ok()
883 {
884 state.pending.push_front(request.clone());
885 }
886 }
887 }
888
889 fn shutdown_selected(&self, request: &Request) {
890 if request
891 .state
892 .compare_exchange(SELECTED, SHUTDOWN, Ordering::AcqRel, Ordering::Acquire)
893 .is_ok()
894 {
895 if request.publish(SHUTDOWN, Err(DispatchCompletionError::DispatcherShutdown)) {
896 self.diagnostics
897 .shutdown_retired
898 .fetch_add(1, Ordering::Relaxed);
899 emit_request(EVENT_SHUTDOWN, correlation(self.generation, request.id));
900 }
901 request.retire();
902 }
903 }
904
905 fn retire(&self, id: u64, expected: *const Request) {
906 let mut state = self.lock_state();
907 self.retire_locked(&mut state, id, expected);
908 }
909
910 fn retire_locked(&self, state: &mut ControllerState, id: u64, expected: *const Request) {
911 if state
912 .registry
913 .get(&id)
914 .is_some_and(|request| Arc::as_ptr(request) == expected)
915 {
916 state.registry.remove(&id);
917 }
918 }
919
920 fn shutdown(&self) {
921 let requests = {
922 let mut state = self.lock_state();
923 if !state.active {
924 while state.running > 0 {
925 state = self
926 .idle
927 .wait(state)
928 .unwrap_or_else(std::sync::PoisonError::into_inner);
929 }
930 return;
931 }
932 self.expire_locked(&mut state);
933 state.active = false;
934 state.pending.clear();
935 state.registry.values().cloned().collect::<Vec<_>>()
936 };
937 for request in &requests {
938 let state = request.state.load(Ordering::Acquire);
939 if matches!(state, QUEUED | SELECTED)
940 && request
941 .state
942 .compare_exchange(state, SHUTDOWN, Ordering::AcqRel, Ordering::Acquire)
943 .is_ok()
944 {
945 if request.publish(SHUTDOWN, Err(DispatchCompletionError::DispatcherShutdown)) {
946 self.diagnostics
947 .shutdown_retired
948 .fetch_add(1, Ordering::Relaxed);
949 emit_request(EVENT_SHUTDOWN, correlation(self.generation, request.id));
950 }
951 request.retire();
952 }
953 }
954 let mut state = self.lock_state();
955 while state.running > 0 {
956 state = self
957 .idle
958 .wait(state)
959 .unwrap_or_else(std::sync::PoisonError::into_inner);
960 }
961 for request in requests {
962 if !request.retired.load(Ordering::Acquire)
963 && request.publish(SHUTDOWN, Err(DispatchCompletionError::DispatcherShutdown))
964 {
965 self.diagnostics
966 .shutdown_retired
967 .fetch_add(1, Ordering::Relaxed);
968 }
969 self.retire_locked(&mut state, request.id, Arc::as_ptr(&request));
970 request.retired.store(true, Ordering::Release);
971 }
972 state.pending.clear();
973 #[cfg(test)]
974 debug_assert!(
975 state.registry.is_empty(),
976 "dispatcher request leaked during shutdown"
977 );
978 }
979
980 fn diagnostics(&self) -> DispatchDiagnostics {
981 let state = self.lock_state();
982 DispatchDiagnostics {
983 generation: self.generation,
984 pending: state.pending.len(),
985 running: state.running,
986 accepted: self.diagnostics.accepted.load(Ordering::Relaxed),
987 rejected: self.diagnostics.rejected.load(Ordering::Relaxed),
988 selected: self.diagnostics.selected.load(Ordering::Relaxed),
989 executed: self.diagnostics.executed.load(Ordering::Relaxed),
990 canceled: self.diagnostics.canceled.load(Ordering::Relaxed),
991 expired: self.diagnostics.expired.load(Ordering::Relaxed),
992 completed: self.diagnostics.completed.load(Ordering::Relaxed),
993 failed: self.diagnostics.failed.load(Ordering::Relaxed),
994 shutdown_retired: self.diagnostics.shutdown_retired.load(Ordering::Relaxed),
995 incompatible_skipped: self
996 .diagnostics
997 .incompatible_skipped
998 .load(Ordering::Relaxed),
999 nested_suppressed: self.diagnostics.nested_suppressed.load(Ordering::Relaxed),
1000 }
1001 }
1002}
1003
1004struct RunningRequestGuard {
1007 controller: Arc<DispatchController>,
1008 request: Arc<Request>,
1009 finished: bool,
1010}
1011
1012impl RunningRequestGuard {
1013 fn take_operation(&self) -> Option<DispatchOperation> {
1014 self.request
1015 .operation
1016 .lock()
1017 .unwrap_or_else(std::sync::PoisonError::into_inner)
1018 .take()
1019 }
1020
1021 fn finish(mut self, result: Result<DispatchResult, DispatchExecutionError>) {
1022 self.controller.finish_running(&self.request, result);
1023 self.finished = true;
1024 }
1025}
1026
1027impl Drop for RunningRequestGuard {
1028 fn drop(&mut self) {
1029 if self.finished {
1030 return;
1031 }
1032 let _ = self
1033 .request
1034 .operation
1035 .lock()
1036 .unwrap_or_else(std::sync::PoisonError::into_inner)
1037 .take();
1038 self.controller
1039 .finish_running(&self.request, Err(DispatchExecutionError::Panicked));
1040 self.finished = true;
1041 }
1042}
1043
1044struct PendingConfig(DispatchConfig);
1045
1046#[derive(Default)]
1047struct Generations {
1048 pending: Option<PendingConfig>,
1049 active: Option<Arc<DispatchController>>,
1050 next_generation: u64,
1051}
1052
1053fn generations() -> &'static Mutex<Generations> {
1054 static GENERATIONS: OnceLock<Mutex<Generations>> = OnceLock::new();
1055 GENERATIONS.get_or_init(|| Mutex::new(Generations::default()))
1056}
1057
1058fn lock_generations() -> std::sync::MutexGuard<'static, Generations> {
1059 generations()
1060 .lock()
1061 .unwrap_or_else(std::sync::PoisonError::into_inner)
1062}
1063
1064pub(crate) fn install_production_config(config: DispatchConfig) -> Result<(), DispatchConfig> {
1065 let Some(config) = config.normalized() else {
1066 return Err(config);
1067 };
1068 let mut generations = lock_generations();
1069 if generations.pending.is_some() || generations.active.is_some() {
1070 return Err(config);
1071 }
1072 generations.pending = Some(PendingConfig(config));
1073 Ok(())
1074}
1075
1076pub(crate) fn activate() -> bool {
1077 let mut generations = lock_generations();
1078 if generations.active.is_some() {
1079 return true;
1080 }
1081 let Some(PendingConfig(config)) = generations.pending.take() else {
1082 return false;
1083 };
1084 generations.next_generation = generations.next_generation.wrapping_add(1).max(1);
1085 generations.active = Some(DispatchController::new(generations.next_generation, config));
1086 true
1087}
1088
1089pub(crate) fn shutdown() {
1090 let controller = lock_generations().active.take();
1091 if let Some(controller) = controller {
1092 controller.shutdown();
1093 }
1094}
1095
1096pub fn current_generation() -> Option<DispatchGeneration> {
1101 lock_generations()
1102 .active
1103 .clone()
1104 .map(|controller| DispatchGeneration { controller })
1105}
1106
1107fn active_generation_id() -> Option<u64> {
1108 lock_generations()
1109 .active
1110 .as_ref()
1111 .map(|controller| controller.generation)
1112}
1113
1114pub fn enqueue(operation: DispatchOperation) -> Result<DispatchTicket, DispatchEnqueueError> {
1118 current_generation()
1119 .ok_or(DispatchEnqueueError::NoActiveGeneration)?
1120 .enqueue(operation)
1121}
1122
1123pub fn diagnostics() -> Option<DispatchDiagnostics> {
1125 current_generation().map(|generation| generation.diagnostics())
1126}
1127
1128thread_local! {
1129 static CALLBACK_DEPTH: Cell<usize> = const { Cell::new(0) };
1130 static DRAIN_DEPTH: Cell<usize> = const { Cell::new(0) };
1131}
1132
1133fn callback_depth() -> usize {
1134 CALLBACK_DEPTH.get()
1135}
1136
1137struct DrainGuard {
1138 entered: bool,
1139 _callback: CallbackGuard,
1140 _not_send: PhantomData<*mut ()>,
1141}
1142
1143impl DrainGuard {
1144 fn enter() -> Self {
1145 let entered = DRAIN_DEPTH.get() == 0;
1146 if entered {
1147 DRAIN_DEPTH.set(1);
1148 }
1149 Self {
1150 entered,
1151 _callback: enter_callback(),
1152 _not_send: PhantomData,
1153 }
1154 }
1155}
1156
1157impl Drop for DrainGuard {
1158 fn drop(&mut self) {
1159 if self.entered {
1160 DRAIN_DEPTH.set(0);
1161 }
1162 }
1163}
1164
1165pub(crate) struct CallbackGuard {
1166 _not_send: PhantomData<*mut ()>,
1167}
1168
1169pub(crate) fn enter_callback() -> CallbackGuard {
1170 CALLBACK_DEPTH.set(CALLBACK_DEPTH.get().saturating_add(1));
1171 CallbackGuard {
1172 _not_send: PhantomData,
1173 }
1174}
1175
1176impl Drop for CallbackGuard {
1177 fn drop(&mut self) {
1178 CALLBACK_DEPTH.set(CALLBACK_DEPTH.get().saturating_sub(1));
1179 }
1180}
1181
1182enum DrainContext<'call, 'context> {
1183 ThreadSafe(&'context ThreadSafeContext<'call>),
1184 Worksheet(&'context WorksheetContext<'call>),
1185 Macro(&'context MacroContext<'call>),
1186 Lifecycle(&'context LifecycleContext<'call>),
1187}
1188
1189impl DrainContext<'_, '_> {
1190 const fn kind(&self) -> DispatchCallbackKind {
1191 match self {
1192 Self::ThreadSafe(context) => {
1193 let _ = context;
1194 DispatchCallbackKind::ThreadSafe
1195 }
1196 Self::Worksheet(context) => {
1197 let _ = context;
1198 DispatchCallbackKind::Worksheet
1199 }
1200 Self::Macro(_) => DispatchCallbackKind::Macro,
1201 Self::Lifecycle(context) => {
1202 let _ = context;
1203 DispatchCallbackKind::Lifecycle
1204 }
1205 }
1206 }
1207}
1208
1209fn drain(context: DrainContext<'_, '_>) -> DispatchDrainReport {
1210 let Some(generation) = current_generation() else {
1211 return DispatchDrainReport::default();
1212 };
1213 let guard = DrainGuard::enter();
1214 if !guard.entered {
1215 generation
1216 .controller
1217 .diagnostics
1218 .nested_suppressed
1219 .fetch_add(1, Ordering::Relaxed);
1220 emit_request(EVENT_NESTED_SUPPRESSED, generation.id());
1221 return DispatchDrainReport {
1222 nested_suppressed: true,
1223 ..DispatchDrainReport::default()
1224 };
1225 }
1226 let kind = context.kind();
1227 let (selected, incompatible, expired) = generation.controller.select(kind);
1228 let mut report = DispatchDrainReport {
1229 selected: selected.len(),
1230 incompatible_skipped: incompatible,
1231 expired,
1232 ..DispatchDrainReport::default()
1233 };
1234 let started = Instant::now();
1235 for (index, request) in selected.iter().enumerate() {
1236 if generation
1237 .controller
1238 .config
1239 .maximum_drain_duration
1240 .is_some_and(|limit| started.elapsed() >= limit)
1241 {
1242 generation.controller.requeue_selected(&selected[index..]);
1243 report.duration_limit_reached = true;
1244 break;
1245 }
1246 #[cfg(test)]
1247 if let Some(pause) = generation
1248 .controller
1249 .before_start
1250 .lock()
1251 .unwrap_or_else(std::sync::PoisonError::into_inner)
1252 .clone()
1253 {
1254 pause.reached.wait();
1255 pause.release.wait();
1256 }
1257 let Some(running) = generation.controller.try_start(request.clone()) else {
1258 generation.controller.shutdown_selected(request);
1259 continue;
1260 };
1261 #[cfg(test)]
1262 if generation
1263 .controller
1264 .panic_after_start
1265 .swap(false, Ordering::AcqRel)
1266 {
1267 panic!("injected panic after dispatcher Running commitment");
1268 }
1269 #[cfg(test)]
1270 if generation
1271 .controller
1272 .clear_operation_after_start
1273 .swap(false, Ordering::AcqRel)
1274 {
1275 let _ = running.take_operation();
1276 }
1277 let Some(operation) = running.take_operation() else {
1278 emit_request(
1279 EVENT_INTERNAL_INVARIANT,
1280 correlation(request.generation, request.id),
1281 );
1282 running.finish(Err(DispatchExecutionError::InternalInvariant));
1283 report.failed += 1;
1284 report.processed += 1;
1285 continue;
1286 };
1287 generation
1288 .controller
1289 .diagnostics
1290 .executed
1291 .fetch_add(1, Ordering::Relaxed);
1292 emit_request(EVENT_EXECUTED, correlation(request.generation, request.id));
1293 let result = std::panic::catch_unwind(AssertUnwindSafe(|| execute(operation, &context)))
1294 .unwrap_or(Err(DispatchExecutionError::Panicked));
1295 if result.is_err() {
1296 report.failed += 1;
1297 }
1298 running.finish(result);
1299 report.processed += 1;
1300 }
1301 report
1302}
1303
1304fn execute(
1305 operation: DispatchOperation,
1306 context: &DrainContext<'_, '_>,
1307) -> Result<DispatchResult, DispatchExecutionError> {
1308 if !context.kind().permits(operation.requirement()) {
1309 return Err(DispatchExecutionError::IncompatibleContext {
1310 required: operation.requirement(),
1311 actual: context.kind(),
1312 });
1313 }
1314 match operation {
1315 DispatchOperation::EchoOwned(value) => Ok(DispatchResult::OwnedValue(value)),
1316 DispatchOperation::PollCancellationPreservingBreak => match context {
1317 DrainContext::Macro(context) => context
1318 .is_cancellation_requested()
1319 .map(DispatchResult::CancellationRequested)
1320 .map_err(DispatchExecutionError::Excel),
1321 _ => Err(DispatchExecutionError::IncompatibleContext {
1322 required: DispatchRequirement::Macro,
1323 actual: context.kind(),
1324 }),
1325 },
1326 #[cfg(test)]
1327 DispatchOperation::TestEnqueueNested(value) => {
1328 enqueue(DispatchOperation::EchoOwned(value.clone()))
1329 .map_err(|_| DispatchExecutionError::Panicked)?;
1330 Ok(DispatchResult::OwnedValue(value))
1331 }
1332 #[cfg(test)]
1333 DispatchOperation::TestNestedMacroDrain => match context {
1334 DrainContext::Macro(context) => {
1335 let report = drain(DrainContext::Macro(context));
1336 Ok(DispatchResult::CancellationRequested(
1337 report.nested_suppressed,
1338 ))
1339 }
1340 _ => unreachable!("selection enforces macro compatibility"),
1341 },
1342 #[cfg(test)]
1343 DispatchOperation::TestBlock => {
1344 if let Some(pause) = test_execution_pause()
1345 .lock()
1346 .unwrap_or_else(std::sync::PoisonError::into_inner)
1347 .clone()
1348 {
1349 pause.reached.wait();
1350 pause.release.wait();
1351 }
1352 Ok(DispatchResult::OwnedValue(ExcelValue::Integer(1)))
1353 }
1354 #[cfg(test)]
1355 DispatchOperation::TestPanic => panic!("dispatcher test panic"),
1356 }
1357}
1358
1359pub(crate) fn drain_thread_safe(context: &ThreadSafeContext<'_>) -> DispatchDrainReport {
1360 drain(DrainContext::ThreadSafe(context))
1361}
1362
1363pub(crate) fn drain_worksheet(context: &WorksheetContext<'_>) -> DispatchDrainReport {
1364 drain(DrainContext::Worksheet(context))
1365}
1366
1367pub(crate) fn drain_macro(context: &MacroContext<'_>) -> DispatchDrainReport {
1368 drain(DrainContext::Macro(context))
1369}
1370
1371pub(crate) fn drain_lifecycle(context: &LifecycleContext<'_>) -> DispatchDrainReport {
1372 drain(DrainContext::Lifecycle(context))
1373}
1374
1375fn correlation(generation: u64, request: u64) -> u64 {
1376 generation.rotate_left(32) ^ request
1377}
1378
1379fn emit_request(event: i32, correlation_id: u64) {
1380 crate::diagnostics::emit(
1381 DiagnosticEvent::new(DiagnosticCode::Dispatcher, DiagnosticSeverity::Info, event)
1382 .with_correlation(correlation_id),
1383 );
1384}
1385
1386#[cfg(test)]
1387pub(crate) static TEST_SERIAL: Mutex<()> = Mutex::new(());
1388
1389#[cfg(test)]
1390struct TestPause {
1391 reached: std::sync::Barrier,
1392 release: std::sync::Barrier,
1393}
1394
1395#[cfg(test)]
1396fn test_execution_pause() -> &'static Mutex<Option<Arc<TestPause>>> {
1397 static PAUSE: OnceLock<Mutex<Option<Arc<TestPause>>>> = OnceLock::new();
1398 PAUSE.get_or_init(|| Mutex::new(None))
1399}
1400
1401#[cfg(test)]
1402#[allow(
1403 dead_code,
1404 reason = "used by dispatcher/runtime test modules as they are added"
1405)]
1406pub(crate) fn reset_generations_for_test() {
1407 let active = {
1408 let mut generations = lock_generations();
1409 generations.pending = None;
1410 generations.active.take()
1411 };
1412 if let Some(active) = active {
1413 active.shutdown();
1414 }
1415 CALLBACK_DEPTH.set(0);
1416 DRAIN_DEPTH.set(0);
1417 *test_execution_pause()
1418 .lock()
1419 .unwrap_or_else(std::sync::PoisonError::into_inner) = None;
1420}
1421
1422#[cfg(test)]
1423mod tests {
1424 use super::*;
1425 use core::ffi::c_int;
1426 use std::sync::{Barrier, mpsc};
1427
1428 use excel_api_sys::{LPXLOPER12, XLOPER12, XLOPER12Value};
1429
1430 use crate::excel_call::{CallCapability, ExcelCallBackend};
1431
1432 #[derive(Default)]
1433 struct AbortBackend {
1434 linked: AtomicBool,
1435 calls: Mutex<Vec<(i32, usize)>>,
1436 code: std::sync::atomic::AtomicI32,
1437 result: AtomicBool,
1438 }
1439
1440 impl AbortBackend {
1441 fn linked() -> Self {
1442 Self {
1443 linked: AtomicBool::new(true),
1444 result: AtomicBool::new(true),
1445 ..Self::default()
1446 }
1447 }
1448 }
1449
1450 impl ExcelCallBackend for AbortBackend {
1451 fn link(&self) -> Result<(), ExcelCallError> {
1452 self.linked.store(true, Ordering::Release);
1453 Ok(())
1454 }
1455
1456 fn unlink(&self) {
1457 self.linked.store(false, Ordering::Release);
1458 }
1459
1460 fn is_linked(&self) -> bool {
1461 self.linked.load(Ordering::Acquire)
1462 }
1463
1464 unsafe fn excel12v_raw(
1465 &self,
1466 function: i32,
1467 result: *mut XLOPER12,
1468 count: c_int,
1469 _: *mut LPXLOPER12,
1470 ) -> i32 {
1471 self.calls.lock().unwrap().push((function, count as usize));
1472 unsafe {
1474 (*result).val = XLOPER12Value {
1475 xbool: i32::from(self.result.load(Ordering::Acquire)),
1476 };
1477 (*result).xltype = excel_api_sys::xltypeBool;
1478 }
1479 self.code.load(Ordering::Acquire)
1480 }
1481 }
1482
1483 struct GenerationGuard;
1484
1485 impl Drop for GenerationGuard {
1486 fn drop(&mut self) {
1487 reset_generations_for_test();
1488 }
1489 }
1490
1491 fn start(config: DispatchConfig) -> (GenerationGuard, DispatchGeneration) {
1492 reset_generations_for_test();
1493 assert_eq!(install_production_config(config), Ok(()));
1494 assert!(activate());
1495 (GenerationGuard, current_generation().unwrap())
1496 }
1497
1498 fn value(number: i32) -> DispatchOperation {
1499 DispatchOperation::EchoOwned(ExcelValue::Integer(number))
1500 }
1501
1502 fn assert_owned(ticket: &DispatchTicket, expected: i32) {
1503 assert_eq!(
1504 ticket.try_result(),
1505 Some(Ok(DispatchResult::OwnedValue(ExcelValue::Integer(
1506 expected
1507 ))))
1508 );
1509 }
1510
1511 fn clone_ticket(ticket: &DispatchTicket) -> DispatchTicket {
1512 DispatchTicket {
1513 request: ticket.request.clone(),
1514 }
1515 }
1516
1517 #[test]
1518 fn compatibility_table_is_explicit_and_not_a_main_thread_ordering() {
1519 let _serial = TEST_SERIAL.lock().unwrap();
1520 for kind in [
1521 DispatchCallbackKind::ThreadSafe,
1522 DispatchCallbackKind::Worksheet,
1523 DispatchCallbackKind::Macro,
1524 DispatchCallbackKind::Lifecycle,
1525 ] {
1526 assert!(kind.permits(DispatchRequirement::ContextNeutral));
1527 }
1528 assert!(DispatchCallbackKind::ThreadSafe.permits(DispatchRequirement::ThreadSafeWorksheet));
1529 assert!(!DispatchCallbackKind::ThreadSafe.permits(DispatchRequirement::Worksheet));
1530 assert!(!DispatchCallbackKind::ThreadSafe.permits(DispatchRequirement::Macro));
1531 assert!(!DispatchCallbackKind::ThreadSafe.permits(DispatchRequirement::Lifecycle));
1532 assert!(DispatchCallbackKind::Worksheet.permits(DispatchRequirement::Worksheet));
1533 assert!(!DispatchCallbackKind::Worksheet.permits(DispatchRequirement::Macro));
1534 assert!(DispatchCallbackKind::Macro.permits(DispatchRequirement::Macro));
1535 assert!(!DispatchCallbackKind::Macro.permits(DispatchRequirement::Worksheet));
1536 assert!(DispatchCallbackKind::Lifecycle.permits(DispatchRequirement::Lifecycle));
1537 assert!(!DispatchCallbackKind::Lifecycle.permits(DispatchRequirement::Macro));
1538 }
1539
1540 #[test]
1541 fn empty_queue_fifo_and_bounded_batch_are_exact() {
1542 let _serial = TEST_SERIAL.lock().unwrap();
1543 let (_guard, _) = start(DispatchConfig {
1544 maximum_batch_per_drain: 2,
1545 ..DispatchConfig::default()
1546 });
1547 let backend = AbortBackend::linked();
1548 let capability = CallCapability::new(&backend);
1549 let context = ThreadSafeContext::new(&capability);
1550 assert_eq!(context.drain_dispatcher(), DispatchDrainReport::default());
1551 let first = enqueue(value(1)).unwrap();
1552 let second = enqueue(value(2)).unwrap();
1553 let third = enqueue(value(3)).unwrap();
1554 let report = context.drain_dispatcher();
1555 assert_eq!((report.selected, report.processed), (2, 2));
1556 assert_owned(&first, 1);
1557 assert_owned(&second, 2);
1558 assert_eq!(third.try_result(), None);
1559 assert_eq!(context.drain_dispatcher().processed, 1);
1560 assert_owned(&third, 3);
1561 assert!(backend.calls.lock().unwrap().is_empty());
1562 }
1563
1564 #[test]
1565 fn queue_full_and_detached_ticket_policy_remain_bounded() {
1566 let _serial = TEST_SERIAL.lock().unwrap();
1567 let (_guard, generation) = start(DispatchConfig {
1568 maximum_pending: 1,
1569 ..DispatchConfig::default()
1570 });
1571 let detached = enqueue(value(1)).unwrap();
1572 drop(detached);
1573 assert_eq!(
1574 enqueue(value(2)).unwrap_err(),
1575 DispatchEnqueueError::QueueFull
1576 );
1577 assert_eq!(generation.diagnostics().pending, 1);
1578 let backend = AbortBackend::linked();
1579 let capability = CallCapability::new(&backend);
1580 ThreadSafeContext::new(&capability).drain_dispatcher();
1581 let diagnostics = generation.diagnostics();
1582 assert_eq!((diagnostics.pending, diagnostics.completed), (0, 1));
1583 }
1584
1585 #[test]
1586 fn compatible_request_behind_macro_head_executes_without_excel_call() {
1587 let _serial = TEST_SERIAL.lock().unwrap();
1588 let (_guard, generation) = start(DispatchConfig::default());
1589 let macro_ticket = enqueue(DispatchOperation::PollCancellationPreservingBreak).unwrap();
1590 let pure_ticket = enqueue(value(9)).unwrap();
1591 let backend = AbortBackend::linked();
1592 let capability = CallCapability::new(&backend);
1593 let thread_safe = ThreadSafeContext::new(&capability);
1594 let report = thread_safe.drain_dispatcher();
1595 assert_eq!((report.processed, report.incompatible_skipped), (1, 1));
1596 assert_owned(&pure_ticket, 9);
1597 assert_eq!(macro_ticket.try_result(), None);
1598 assert!(backend.calls.lock().unwrap().is_empty());
1599 let macro_context = MacroContext::new(&capability);
1600 assert_eq!(macro_context.drain_dispatcher().processed, 1);
1601 assert_eq!(
1602 macro_ticket.try_result(),
1603 Some(Ok(DispatchResult::CancellationRequested(true)))
1604 );
1605 assert_eq!(
1606 *backend.calls.lock().unwrap(),
1607 vec![(excel_api_sys::xlAbort, 0)]
1608 );
1609 assert_eq!(generation.diagnostics().incompatible_skipped, 1);
1610 }
1611
1612 #[test]
1613 fn worksheet_and_lifecycle_contexts_execute_only_approved_work() {
1614 let _serial = TEST_SERIAL.lock().unwrap();
1615 let (_guard, _) = start(DispatchConfig::default());
1616 let macro_ticket = enqueue(DispatchOperation::PollCancellationPreservingBreak).unwrap();
1617 let worksheet_ticket = enqueue(value(1)).unwrap();
1618 let backend = AbortBackend::linked();
1619 let capability = CallCapability::new(&backend);
1620 let worksheet = WorksheetContext::new(&capability);
1621 assert_eq!(worksheet.drain_dispatcher().processed, 1);
1622 assert_owned(&worksheet_ticket, 1);
1623 assert_eq!(macro_ticket.try_result(), None);
1624 let lifecycle_ticket = enqueue(value(2)).unwrap();
1625 let lifecycle = LifecycleContext::new(&capability);
1626 assert_eq!(lifecycle.drain_dispatcher().processed, 1);
1627 assert_owned(&lifecycle_ticket, 2);
1628 assert_eq!(macro_ticket.try_result(), None);
1629 assert!(backend.calls.lock().unwrap().is_empty());
1630 }
1631
1632 #[test]
1633 fn expiration_and_wait_timeout_are_distinct() {
1634 let _serial = TEST_SERIAL.lock().unwrap();
1635 let (_guard, _) = start(DispatchConfig {
1636 default_timeout: Some(Duration::ZERO),
1637 ..DispatchConfig::default()
1638 });
1639 let expired = enqueue(value(1)).unwrap();
1640 assert_eq!(
1641 expired.try_result(),
1642 Some(Err(DispatchCompletionError::Expired))
1643 );
1644 reset_generations_for_test();
1645 assert_eq!(install_production_config(DispatchConfig::default()), Ok(()));
1646 assert!(activate());
1647 let queued = enqueue(value(2)).unwrap();
1648 assert_eq!(
1649 queued.wait_timeout(Duration::ZERO),
1650 Err(DispatchCompletionError::WaitTimeout)
1651 );
1652 assert_eq!(queued.try_result(), None);
1653
1654 reset_generations_for_test();
1655 assert_eq!(
1656 install_production_config(DispatchConfig {
1657 default_timeout: Some(Duration::ZERO),
1658 ..DispatchConfig::default()
1659 }),
1660 Ok(())
1661 );
1662 assert!(activate());
1663 let expired_during_shutdown = enqueue(value(3)).unwrap();
1664 shutdown();
1665 assert_eq!(
1666 expired_during_shutdown.try_result(),
1667 Some(Err(DispatchCompletionError::Expired))
1668 );
1669 }
1670
1671 #[test]
1672 fn wait_observes_request_deadline_before_longer_caller_timeout() {
1673 let _serial = TEST_SERIAL.lock().unwrap();
1674 let (_guard, generation) = start(DispatchConfig {
1675 default_timeout: Some(Duration::from_millis(40)),
1676 ..DispatchConfig::default()
1677 });
1678 let ticket = enqueue(value(1)).unwrap();
1679 let started = Instant::now();
1680 assert_eq!(
1681 ticket.wait_timeout(Duration::from_secs(2)),
1682 Err(DispatchCompletionError::Expired)
1683 );
1684 assert!(started.elapsed() >= Duration::from_millis(20));
1685 assert!(started.elapsed() < Duration::from_secs(1));
1686 assert_eq!(generation.diagnostics().pending, 0);
1687 }
1688
1689 #[test]
1690 fn caller_timeout_does_not_expire_a_longer_lived_request() {
1691 let _serial = TEST_SERIAL.lock().unwrap();
1692 let (_guard, generation) = start(DispatchConfig {
1693 default_timeout: Some(Duration::from_secs(2)),
1694 ..DispatchConfig::default()
1695 });
1696 let ticket = enqueue(value(1)).unwrap();
1697 assert_eq!(
1698 ticket.wait_timeout(Duration::from_millis(20)),
1699 Err(DispatchCompletionError::WaitTimeout)
1700 );
1701 assert_eq!(ticket.try_result(), None);
1702 assert_eq!(generation.diagnostics().pending, 1);
1703 }
1704
1705 #[test]
1706 fn wait_returns_completion_cancellation_and_shutdown_results() {
1707 let _serial = TEST_SERIAL.lock().unwrap();
1708 let (_guard, _) = start(DispatchConfig::default());
1709 let backend = AbortBackend::linked();
1710 let capability = CallCapability::new(&backend);
1711
1712 let completed = enqueue(value(7)).unwrap();
1713 let completed_wait = clone_ticket(&completed);
1714 let (ready_tx, ready_rx) = mpsc::channel();
1715 let waiter = std::thread::spawn(move || {
1716 ready_tx.send(()).unwrap();
1717 completed_wait.wait_timeout(Duration::from_secs(2))
1718 });
1719 ready_rx.recv().unwrap();
1720 MacroContext::new(&capability).drain_dispatcher();
1721 assert_eq!(
1722 waiter.join().unwrap(),
1723 Ok(DispatchResult::OwnedValue(ExcelValue::Integer(7)))
1724 );
1725
1726 let canceled = enqueue(value(8)).unwrap();
1727 let canceled_wait = clone_ticket(&canceled);
1728 let waiter = std::thread::spawn(move || canceled_wait.wait_timeout(Duration::from_secs(2)));
1729 assert_eq!(canceled.cancel(), DispatchCancelOutcome::Canceled);
1730 assert_eq!(
1731 waiter.join().unwrap(),
1732 Err(DispatchCompletionError::Canceled)
1733 );
1734
1735 let stopped = enqueue(value(9)).unwrap();
1736 let stopped_wait = clone_ticket(&stopped);
1737 let waiter = std::thread::spawn(move || stopped_wait.wait_timeout(Duration::from_secs(2)));
1738 shutdown();
1739 assert_eq!(
1740 waiter.join().unwrap(),
1741 Err(DispatchCompletionError::DispatcherShutdown)
1742 );
1743 }
1744
1745 #[test]
1746 fn spurious_notifications_do_not_complete_a_wait() {
1747 let _serial = TEST_SERIAL.lock().unwrap();
1748 let (_guard, _) = start(DispatchConfig::default());
1749 let ticket = enqueue(value(1)).unwrap();
1750 let waiter_ticket = clone_ticket(&ticket);
1751 let request = ticket.request.clone();
1752 let waiter = std::thread::spawn(move || waiter_ticket.wait_timeout(Duration::from_secs(2)));
1753 while request.wait_returns.load(Ordering::Acquire) == 0 {
1754 request.ready.notify_all();
1755 std::thread::yield_now();
1756 }
1757 assert_eq!(ticket.try_result(), None);
1758 assert_eq!(ticket.cancel(), DispatchCancelOutcome::Canceled);
1759 assert_eq!(
1760 waiter.join().unwrap(),
1761 Err(DispatchCompletionError::Canceled)
1762 );
1763 }
1764
1765 #[test]
1766 fn waiting_after_expiry_is_immediate_and_selected_or_running_work_does_not_expire() {
1767 let _serial = TEST_SERIAL.lock().unwrap();
1768 let (_guard, _generation) = start(DispatchConfig {
1769 default_timeout: Some(Duration::ZERO),
1770 ..DispatchConfig::default()
1771 });
1772 let expired = enqueue(value(1)).unwrap();
1773 assert_eq!(
1774 expired.wait_timeout(Duration::from_secs(1)),
1775 Err(DispatchCompletionError::Expired)
1776 );
1777
1778 reset_generations_for_test();
1779 assert_eq!(
1780 install_production_config(DispatchConfig {
1781 default_timeout: Some(Duration::from_millis(5)),
1782 ..DispatchConfig::default()
1783 }),
1784 Ok(())
1785 );
1786 assert!(activate());
1787 let generation = current_generation().unwrap();
1788 let selected_ticket = enqueue(value(2)).unwrap();
1789 let (_selected, _, _) = generation.controller.select(DispatchCallbackKind::Macro);
1790 assert_eq!(
1791 selected_ticket.wait_timeout(Duration::from_millis(20)),
1792 Err(DispatchCompletionError::WaitTimeout)
1793 );
1794 assert_eq!(selected_ticket.try_result(), None);
1795 assert_eq!(selected_ticket.cancel(), DispatchCancelOutcome::Canceled);
1796
1797 let running_ticket = enqueue(value(3)).unwrap();
1798 let (selected, _, _) = generation.controller.select(DispatchCallbackKind::Macro);
1799 let running = generation
1800 .controller
1801 .try_start(selected[0].clone())
1802 .unwrap();
1803 assert_eq!(
1804 running_ticket.wait_timeout(Duration::from_millis(20)),
1805 Err(DispatchCompletionError::WaitTimeout)
1806 );
1807 assert_eq!(running_ticket.try_result(), None);
1808 running.finish(Ok(DispatchResult::OwnedValue(ExcelValue::Integer(3))));
1809 assert_owned(&running_ticket, 3);
1810 assert_eq!(generation.diagnostics().running, 0);
1811 }
1812
1813 #[test]
1814 fn cancel_before_and_after_selection_retires_exactly_once() {
1815 let _serial = TEST_SERIAL.lock().unwrap();
1816 let (_guard, generation) = start(DispatchConfig::default());
1817 let queued = enqueue(value(1)).unwrap();
1818 assert_eq!(queued.cancel(), DispatchCancelOutcome::Canceled);
1819 assert_eq!(queued.cancel(), DispatchCancelOutcome::AlreadyTerminal);
1820 assert_eq!(
1821 queued.try_result(),
1822 Some(Err(DispatchCompletionError::Canceled))
1823 );
1824 let selected_ticket = enqueue(value(2)).unwrap();
1825 let (selected, _, _) = generation.controller.select(DispatchCallbackKind::Macro);
1826 assert_eq!(selected.len(), 1);
1827 assert_eq!(selected_ticket.cancel(), DispatchCancelOutcome::Canceled);
1828 generation.controller.shutdown_selected(&selected[0]);
1829 assert_eq!(
1830 selected_ticket.try_result(),
1831 Some(Err(DispatchCompletionError::Canceled))
1832 );
1833 assert_eq!(generation.diagnostics().pending, 0);
1834 }
1835
1836 #[test]
1837 fn cancellation_loses_after_execution_commitment() {
1838 let _serial = TEST_SERIAL.lock().unwrap();
1839 let (_guard, generation) = start(DispatchConfig::default());
1840 let ticket = enqueue(value(4)).unwrap();
1841 let (selected, _, _) = generation.controller.select(DispatchCallbackKind::Macro);
1842 let running = generation
1843 .controller
1844 .try_start(selected[0].clone())
1845 .unwrap();
1846 assert_eq!(ticket.cancel(), DispatchCancelOutcome::TooLate);
1847 running.finish(Ok(DispatchResult::OwnedValue(ExcelValue::Integer(4))));
1848 assert_owned(&ticket, 4);
1849 assert_eq!(generation.diagnostics().running, 0);
1850 }
1851
1852 #[test]
1853 fn waits_are_rejected_under_callback_depth_guard() {
1854 let _serial = TEST_SERIAL.lock().unwrap();
1855 let (_guard, _) = start(DispatchConfig::default());
1856 let ticket = enqueue(value(1)).unwrap();
1857 let callback = DrainGuard::enter();
1858 assert_eq!(
1859 ticket.wait_timeout(Duration::from_secs(1)),
1860 Err(DispatchCompletionError::WaitFromCallback)
1861 );
1862 drop(callback);
1863 assert_eq!(callback_depth(), 0);
1864 }
1865
1866 #[test]
1867 fn nested_enqueue_waits_for_later_drain_and_nested_drain_is_suppressed() {
1868 let _serial = TEST_SERIAL.lock().unwrap();
1869 let (_guard, generation) = start(DispatchConfig::default());
1870 let outer = enqueue(DispatchOperation::TestEnqueueNested(ExcelValue::Integer(8))).unwrap();
1871 let nested = enqueue(DispatchOperation::TestNestedMacroDrain).unwrap();
1872 let backend = AbortBackend::linked();
1873 let capability = CallCapability::new(&backend);
1874 let macro_context = MacroContext::new(&capability);
1875 let report = macro_context.drain_dispatcher();
1876 assert_eq!(report.processed, 2);
1877 assert_owned(&outer, 8);
1878 assert_eq!(
1879 nested.try_result(),
1880 Some(Ok(DispatchResult::CancellationRequested(true)))
1881 );
1882 assert_eq!(generation.diagnostics().pending, 1);
1883 assert_eq!(generation.diagnostics().nested_suppressed, 1);
1884 assert_eq!(macro_context.drain_dispatcher().processed, 1);
1885 assert_eq!(generation.diagnostics().pending, 0);
1886 }
1887
1888 #[test]
1889 fn panic_clears_guard_and_later_drain_succeeds() {
1890 let _serial = TEST_SERIAL.lock().unwrap();
1891 let (_guard, _) = start(DispatchConfig::default());
1892 let panic_ticket = enqueue(DispatchOperation::TestPanic).unwrap();
1893 let backend = AbortBackend::linked();
1894 let capability = CallCapability::new(&backend);
1895 let macro_context = MacroContext::new(&capability);
1896 let report = macro_context.drain_dispatcher();
1897 assert_eq!((report.processed, report.failed), (1, 1));
1898 assert!(matches!(
1899 panic_ticket.try_result(),
1900 Some(Err(DispatchCompletionError::Operation(
1901 DispatchExecutionError::Panicked
1902 )))
1903 ));
1904 assert_eq!(callback_depth(), 0);
1905 let later = enqueue(value(3)).unwrap();
1906 assert_eq!(macro_context.drain_dispatcher().processed, 1);
1907 assert_owned(&later, 3);
1908 }
1909
1910 #[test]
1911 fn running_guard_retires_repeated_pre_execution_panics_without_underflow() {
1912 let _serial = TEST_SERIAL.lock().unwrap();
1913 let (_guard, generation) = start(DispatchConfig::default());
1914 let backend = AbortBackend::linked();
1915 let capability = CallCapability::new(&backend);
1916 let macro_context = MacroContext::new(&capability);
1917
1918 for expected_failures in 1..=3 {
1919 let ticket = enqueue(value(expected_failures)).unwrap();
1920 generation
1921 .controller
1922 .panic_after_start
1923 .store(true, Ordering::Release);
1924 assert!(
1925 std::panic::catch_unwind(AssertUnwindSafe(|| { macro_context.drain_dispatcher() }))
1926 .is_err()
1927 );
1928 assert_eq!(
1929 ticket.try_result(),
1930 Some(Err(DispatchCompletionError::Operation(
1931 DispatchExecutionError::Panicked
1932 )))
1933 );
1934 let diagnostics = generation.diagnostics();
1935 assert_eq!(diagnostics.running, 0);
1936 assert_eq!(diagnostics.pending, 0);
1937 assert_eq!(diagnostics.failed, expected_failures as u64);
1938 assert_eq!(callback_depth(), 0);
1939 assert!(ticket.request.operation.lock().unwrap().is_none());
1940 assert!(generation.controller.lock_state().registry.is_empty());
1941 }
1942
1943 let later = enqueue(value(4)).unwrap();
1944 assert_eq!(macro_context.drain_dispatcher().processed, 1);
1945 assert_owned(&later, 4);
1946
1947 let (done_tx, done_rx) = mpsc::channel();
1948 let closer = std::thread::spawn(move || {
1949 shutdown();
1950 done_tx.send(()).unwrap();
1951 });
1952 done_rx.recv_timeout(Duration::from_secs(2)).unwrap();
1953 closer.join().unwrap();
1954 assert_eq!(install_production_config(DispatchConfig::default()), Ok(()));
1955 assert!(activate());
1956 let reopened = enqueue(value(5)).unwrap();
1957 MacroContext::new(&capability).drain_dispatcher();
1958 assert_owned(&reopened, 5);
1959 }
1960
1961 #[test]
1962 fn missing_running_operation_is_a_controlled_failure_and_shutdown_remains_live() {
1963 let _serial = TEST_SERIAL.lock().unwrap();
1964 let (_guard, generation) = start(DispatchConfig::default());
1965 let ticket = enqueue(value(1)).unwrap();
1966 generation
1967 .controller
1968 .clear_operation_after_start
1969 .store(true, Ordering::Release);
1970 let backend = AbortBackend::linked();
1971 let capability = CallCapability::new(&backend);
1972 let report = MacroContext::new(&capability).drain_dispatcher();
1973 assert_eq!((report.processed, report.failed), (1, 1));
1974 assert_eq!(
1975 ticket.try_result(),
1976 Some(Err(DispatchCompletionError::Operation(
1977 DispatchExecutionError::InternalInvariant
1978 )))
1979 );
1980 let diagnostics = generation.diagnostics();
1981 assert_eq!((diagnostics.pending, diagnostics.running), (0, 0));
1982 assert!(generation.controller.lock_state().registry.is_empty());
1983
1984 let (done_tx, done_rx) = mpsc::channel();
1985 let closer = std::thread::spawn(move || {
1986 shutdown();
1987 done_tx.send(()).unwrap();
1988 });
1989 done_rx.recv_timeout(Duration::from_secs(2)).unwrap();
1990 closer.join().unwrap();
1991 }
1992
1993 #[test]
1994 fn zero_duration_requeues_selected_work_without_execution() {
1995 let _serial = TEST_SERIAL.lock().unwrap();
1996 let (_guard, generation) = start(DispatchConfig {
1997 maximum_drain_duration: Some(Duration::ZERO),
1998 ..DispatchConfig::default()
1999 });
2000 let ticket = enqueue(value(1)).unwrap();
2001 let backend = AbortBackend::linked();
2002 let capability = CallCapability::new(&backend);
2003 let report = MacroContext::new(&capability).drain_dispatcher();
2004 assert!(report.duration_limit_reached);
2005 assert_eq!(report.processed, 0);
2006 assert_eq!(ticket.try_result(), None);
2007 assert_eq!(generation.diagnostics().pending, 1);
2008 }
2009
2010 #[test]
2011 fn selected_request_cannot_start_after_shutdown_boundary() {
2012 let _serial = TEST_SERIAL.lock().unwrap();
2013 let (_guard, generation) = start(DispatchConfig::default());
2014 let ticket = enqueue(value(1)).unwrap();
2015 let pause = Arc::new(TestPause {
2016 reached: Barrier::new(2),
2017 release: Barrier::new(2),
2018 });
2019 *generation.controller.before_start.lock().unwrap() = Some(pause.clone());
2020 let backend = Arc::new(AbortBackend::linked());
2021 let drain = {
2022 let backend = backend.clone();
2023 std::thread::spawn(move || {
2024 let capability = CallCapability::new(backend.as_ref());
2025 MacroContext::new(&capability).drain_dispatcher()
2026 })
2027 };
2028 pause.reached.wait();
2029 shutdown();
2030 pause.release.wait();
2031 assert_eq!(drain.join().unwrap().processed, 0);
2032 assert_eq!(
2033 ticket.try_result(),
2034 Some(Err(DispatchCompletionError::DispatcherShutdown))
2035 );
2036 }
2037
2038 #[test]
2039 fn shutdown_waits_for_running_operation_then_reopen_rejects_stale_generation() {
2040 let _serial = TEST_SERIAL.lock().unwrap();
2041 let (_guard, old) = start(DispatchConfig::default());
2042 let ticket = old.enqueue(DispatchOperation::TestBlock).unwrap();
2043 let pause = Arc::new(TestPause {
2044 reached: Barrier::new(2),
2045 release: Barrier::new(2),
2046 });
2047 *test_execution_pause().lock().unwrap() = Some(pause.clone());
2048 let backend = Arc::new(AbortBackend::linked());
2049 let drain = {
2050 let backend = backend.clone();
2051 std::thread::spawn(move || {
2052 let capability = CallCapability::new(backend.as_ref());
2053 MacroContext::new(&capability).drain_dispatcher()
2054 })
2055 };
2056 pause.reached.wait();
2057 let (done_tx, done_rx) = mpsc::channel();
2058 let closer = std::thread::spawn(move || {
2059 shutdown();
2060 done_tx.send(()).unwrap();
2061 });
2062 assert!(done_rx.try_recv().is_err());
2063 pause.release.wait();
2064 assert_eq!(drain.join().unwrap().processed, 1);
2065 done_rx.recv_timeout(Duration::from_secs(2)).unwrap();
2066 closer.join().unwrap();
2067 assert_owned(&ticket, 1);
2068 assert_eq!(install_production_config(DispatchConfig::default()), Ok(()));
2069 assert!(activate());
2070 assert_eq!(
2071 old.enqueue(value(2)).unwrap_err(),
2072 DispatchEnqueueError::StaleGeneration
2073 );
2074 let new_ticket = enqueue(value(3)).unwrap();
2075 let capability = CallCapability::new(backend.as_ref());
2076 MacroContext::new(&capability).drain_dispatcher();
2077 assert_owned(&new_ticket, 3);
2078 }
2079
2080 #[test]
2081 fn queued_shutdown_signals_ticket_and_repeated_poll_is_stable() {
2082 let _serial = TEST_SERIAL.lock().unwrap();
2083 let (_guard, _) = start(DispatchConfig::default());
2084 let ticket = enqueue(value(1)).unwrap();
2085 shutdown();
2086 let expected = Some(Err(DispatchCompletionError::DispatcherShutdown));
2087 assert_eq!(ticket.try_result(), expected);
2088 assert_eq!(ticket.try_result(), expected);
2089 assert_eq!(
2090 enqueue(value(2)).unwrap_err(),
2091 DispatchEnqueueError::NoActiveGeneration
2092 );
2093 }
2094
2095 #[test]
2096 fn xl_abort_failure_preserves_exact_code_and_no_auxiliary_owner() {
2097 let _serial = TEST_SERIAL.lock().unwrap();
2098 let (_guard, _) = start(DispatchConfig::default());
2099 let ticket = enqueue(DispatchOperation::PollCancellationPreservingBreak).unwrap();
2100 let backend = AbortBackend::linked();
2101 backend.code.store(
2102 excel_api_sys::xlretAbort | excel_api_sys::xlretUncalced,
2103 Ordering::Release,
2104 );
2105 let capability = CallCapability::new(&backend);
2106 MacroContext::new(&capability).drain_dispatcher();
2107 assert_eq!(
2108 ticket.try_result(),
2109 Some(Err(DispatchCompletionError::Operation(
2110 DispatchExecutionError::Excel(ExcelCallError::ExcelFailure {
2111 function: "xlAbort",
2112 code: crate::ExcelReturnCode(
2113 excel_api_sys::xlretAbort | excel_api_sys::xlretUncalced
2114 ),
2115 })
2116 )))
2117 );
2118 assert_eq!(
2119 *backend.calls.lock().unwrap(),
2120 vec![(excel_api_sys::xlAbort, 0)]
2121 );
2122 }
2123}