Skip to main content

excel_api/
dispatcher.rs

1//! Bounded cooperative dispatch under genuine Excel callback capabilities.
2//!
3//! Enqueueing a request does not wake Excel. Work executes only when an XLL
4//! callback explicitly drains through one of the typed context entry points.
5//!
6//! There is intentionally no context-free drain API:
7//!
8//! ```compile_fail
9//! excel_api::dispatcher::drain();
10//! ```
11
12use 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/// Bounds for one cooperative dispatcher generation.
52#[derive(Clone, Copy, Debug, Eq, PartialEq)]
53pub struct DispatchConfig {
54    /// Maximum queued and selected requests retained by this generation.
55    pub maximum_pending: usize,
56    /// Maximum compatible requests one callback drain may select.
57    pub maximum_batch_per_drain: usize,
58    /// Optional deadline assigned to requests without an explicit deadline.
59    pub default_timeout: Option<Duration>,
60    /// Optional wall-clock budget for one callback drain.
61    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/// Closed capability requirement recorded by every operation.
82#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
83pub enum DispatchRequirement {
84    /// Pure owned operation requiring no Excel call or capability.
85    ContextNeutral,
86    /// Operation legal only in an MTR-safe worksheet callback.
87    ThreadSafeWorksheet,
88    /// Operation legal only in an ordinary worksheet callback.
89    Worksheet,
90    /// Operation legal only in a registered macro command callback.
91    Macro,
92    /// Operation legal only during open/close lifecycle callbacks.
93    Lifecycle,
94}
95
96/// Closed owned operation catalogue. No arbitrary context-taking closure is accepted.
97#[derive(Clone, Debug, PartialEq)]
98pub enum DispatchOperation {
99    /// Returns the same fully owned semantic value without calling Excel.
100    EchoOwned(ExcelValue),
101    /// Calls verified `xlAbort` with its preserving zero-argument form.
102    PollCancellationPreservingBreak,
103    #[cfg(test)]
104    /// Test-only nested enqueue operation.
105    TestEnqueueNested(ExcelValue),
106    #[cfg(test)]
107    /// Test-only nested macro drain operation.
108    TestNestedMacroDrain,
109    #[cfg(test)]
110    /// Test-only deterministic execution blocker.
111    TestBlock,
112    #[cfg(test)]
113    /// Test-only panic containment operation.
114    TestPanic,
115}
116
117impl DispatchOperation {
118    /// Returns the exact closed capability requirement for this operation.
119    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    /// Returns whether executing this operation invokes the typed Excel catalogue.
133    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/// Owned completion values for the initial operation catalogue.
144#[derive(Clone, Debug, PartialEq)]
145pub enum DispatchResult {
146    /// Fully owned semantic value from a context-neutral operation.
147    OwnedValue(ExcelValue),
148    /// User break state returned by preserving `xlAbort` polling.
149    CancellationRequested(bool),
150}
151
152#[derive(Clone, Copy, Debug, Eq, PartialEq)]
153/// Rejection before a dispatcher request becomes owned by a generation.
154pub enum DispatchEnqueueError {
155    /// No runtime generation is installed.
156    NoActiveGeneration,
157    /// The bounded request registry has no capacity.
158    QueueFull,
159    /// Shutdown crossed the enqueue linearization point.
160    RuntimeClosing,
161    /// A retained generation handle no longer names the active generation.
162    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/// Failure after a request has been selected for a compatible callback drain.
179#[derive(Clone, Debug, Eq, PartialEq)]
180pub enum DispatchExecutionError {
181    /// A selected operation did not match the draining callback's capability.
182    IncompatibleContext {
183        /// Operation's closed capability requirement.
184        required: DispatchRequirement,
185        /// Actual Excel-issued callback kind.
186        actual: DispatchCallbackKind,
187    },
188    /// A legal typed Excel call failed while executing the operation.
189    Excel(ExcelCallError),
190    /// User operation code panicked; the dispatcher contained it and retired the request.
191    Panicked,
192    /// Internal request state was inconsistent; no panic escaped the callback.
193    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/// Terminal result reported by a dispatcher ticket when no value is available.
217#[derive(Clone, Debug, Eq, PartialEq)]
218pub enum DispatchCompletionError {
219    /// Cancellation won while the request was still cancelable.
220    Canceled,
221    /// The request expired while still queued.
222    Expired,
223    /// Runtime shutdown retired the request before a result was published.
224    DispatcherShutdown,
225    /// Execution failed after selection.
226    Operation(DispatchExecutionError),
227    /// Blocking waits are forbidden inside an Excel callback.
228    WaitFromCallback,
229    /// The caller's own wait deadline elapsed; the request remains owned.
230    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/// Result of a cooperative request-cancellation attempt.
253#[derive(Clone, Copy, Debug, Eq, PartialEq)]
254pub enum DispatchCancelOutcome {
255    /// Cancellation won before execution commitment.
256    Canceled,
257    /// Selection or execution had already committed.
258    TooLate,
259    /// A terminal request has no remaining cancellation action.
260    AlreadyTerminal,
261}
262
263/// Actual kind of Excel-issued callback that is attempting a drain.
264#[derive(Clone, Copy, Debug, Eq, PartialEq)]
265pub enum DispatchCallbackKind {
266    /// MTR-safe worksheet callback.
267    ThreadSafe,
268    /// Ordinary worksheet-function callback.
269    Worksheet,
270    /// Registered macro command callback.
271    Macro,
272    /// Open/close lifecycle callback.
273    Lifecycle,
274}
275
276impl DispatchCallbackKind {
277    /// Returns whether this callback kind exactly permits `requirement`.
278    ///
279    /// There is intentionally no inferred capability ordering: only the listed
280    /// pairs and context-neutral operations are allowed.
281    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/// Bounded outcome counters for one callback drain attempt.
294#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
295pub struct DispatchDrainReport {
296    /// Requests selected into this drain's bounded batch.
297    pub selected: usize,
298    /// Selected operations that reached an execution attempt.
299    pub processed: usize,
300    /// Selected operations that published failure.
301    pub failed: usize,
302    /// Queued requests retired because their deadline elapsed.
303    pub expired: usize,
304    /// Incompatible requests skipped while seeking compatible work behind them.
305    pub incompatible_skipped: usize,
306    /// Whether a nested drain was rejected by the callback-depth guard.
307    pub nested_suppressed: bool,
308    /// Whether the configured drain duration stopped batch selection.
309    pub duration_limit_reached: bool,
310}
311
312/// Bounded cumulative counters for a dispatcher generation.
313#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
314pub struct DispatchDiagnostics {
315    /// Generation this snapshot describes.
316    pub generation: u64,
317    /// Requests currently queued or selected.
318    pub pending: usize,
319    /// Operations currently executing synchronously in a callback.
320    pub running: usize,
321    /// Total accepted requests.
322    pub accepted: u64,
323    /// Total admission rejections.
324    pub rejected: u64,
325    /// Total selected requests.
326    pub selected: u64,
327    /// Total attempted executions.
328    pub executed: u64,
329    /// Total canceled requests.
330    pub canceled: u64,
331    /// Total queued-expired requests.
332    pub expired: u64,
333    /// Total successful completions.
334    pub completed: u64,
335    /// Total failed executions.
336    pub failed: u64,
337    /// Total requests retired by shutdown.
338    pub shutdown_retired: u64,
339    /// Total incompatible requests skipped during selection.
340    pub incompatible_skipped: u64,
341    /// Total nested drain attempts suppressed by the guard.
342    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
403/// An owned request handle containing no Excel pointer or callback capability.
404///
405/// Dropping a ticket detaches it: queued work remains owned by its generation
406/// and is eventually executed, canceled, expired, or retired by shutdown.
407pub 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    /// Returns this request's identifier within [`Self::generation`].
423    pub fn id(&self) -> u64 {
424        self.request.id
425    }
426
427    /// Returns the dispatcher generation that owns this request.
428    ///
429    /// IDs can be reused by a later generation, so interpret them together.
430    pub fn generation(&self) -> u64 {
431        self.request.generation
432    }
433
434    /// Returns a copied terminal result if available without blocking.
435    ///
436    /// Polling also cooperatively expires this request if it is still queued.
437    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    /// Waits until completion, the caller deadline, or a queued request deadline.
443    ///
444    /// The earlier of `timeout` and the request deadline wins while the request
445    /// is queued. A caller timeout does not cancel the request. Waiting from an
446    /// Excel callback is rejected to avoid blocking Excel; ticket drop detaches
447    /// rather than cancels the generation-owned request.
448    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        // An already-due queued request wins before this wait establishes its
456        // caller deadline.
457        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 an oversleep crosses both deadlines, preserve which deadline
474            // was earlier rather than allowing the later request expiry to
475            // overwrite a caller timeout that had already won.
476            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            // Expiry can win only while Queued. Once selection commits, the
497            // original queue deadline no longer limits an active wait.
498            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    /// Attempts cancellation while the request has not committed to execution.
523    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/// Stable handle to one dispatcher generation. A stale handle never redirects
534/// work into a later generation.
535#[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    /// Returns this generation's monotonically assigned identifier.
551    pub fn id(&self) -> u64 {
552        self.controller.generation
553    }
554
555    /// Enqueues one closed owned operation in this exact generation.
556    ///
557    /// This never wakes Excel. A stale handle cannot redirect work into a later
558    /// generation, and a queue-full error leaves `operation` with the caller.
559    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    /// Returns a bounded diagnostics snapshot for this generation.
575    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
1004/// Owns exact-once accounting from the Selected-to-Running commitment until
1005/// terminal publication and retirement.
1006struct 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
1096/// Returns a stable handle to the currently active dispatcher generation.
1097///
1098/// The handle becomes stale on runtime close or reopen and cannot enqueue into
1099/// a replacement generation.
1100pub 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
1114/// Enqueues one closed operation in the active generation without waking Excel.
1115///
1116/// Use a genuine compatible callback, such as `RUST.DISPATCH.PUMP`, to drain it.
1117pub fn enqueue(operation: DispatchOperation) -> Result<DispatchTicket, DispatchEnqueueError> {
1118    current_generation()
1119        .ok_or(DispatchEnqueueError::NoActiveGeneration)?
1120        .enqueue(operation)
1121}
1122
1123/// Returns diagnostics for the active generation, if one exists.
1124pub 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            // SAFETY: the xlAbort wrapper supplies one live immediate result root.
1473            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}