Skip to main content

excel_api/
async_udf.rs

1//! Owned, bounded asynchronous UDF scheduling and completion.
2
3use core::{fmt, panic::AssertUnwindSafe};
4use std::{
5    collections::HashMap,
6    sync::{
7        Arc, Condvar, Mutex, OnceLock, Weak,
8        atomic::{AtomicBool, AtomicU8, AtomicU64, Ordering},
9        mpsc::{Receiver, SyncSender, TrySendError, sync_channel},
10    },
11    thread::JoinHandle,
12};
13
14use excel_api_sys::{LPXLOPER12, XLOPER12, XLOPER12BigData, XLOPER12BigDataHandle, XLOPER12Value};
15
16use crate::{
17    ExcelError, ExcelReturn, ExcelReturnCode, ExcelReturnValue, ThunkError,
18    excel_call::ExcelCallBackend,
19};
20
21const SCHEDULED: u8 = 0;
22const RUNNING: u8 = 1;
23const CANCEL_REQUESTED: u8 = 2;
24const COMPLETING: u8 = 3;
25const COMPLETED: u8 = 4;
26const CANCELED: u8 = 5;
27
28/// One owned closure submitted to an [`AsyncExecutor`].
29pub type AsyncJob = Box<dyn FnOnce() + Send + 'static>;
30
31/// An executor rejection that returns ownership of the job it did not run.
32pub struct AsyncExecuteError {
33    error: AsyncSubmitError,
34    job: AsyncJob,
35}
36
37impl AsyncExecuteError {
38    /// Creates a rejection that returns the closure which was never accepted.
39    ///
40    /// The executor must not have invoked `job`; the caller may use
41    /// [`Self::into_parts`] to recover it for another owner or disposal.
42    pub fn new(error: AsyncSubmitError, job: AsyncJob) -> Self {
43        Self { error, job }
44    }
45
46    /// Returns the reason this executor declined the job.
47    pub fn error(&self) -> AsyncSubmitError {
48        self.error
49    }
50
51    /// Splits this rejection into its reason and the still-unexecuted job.
52    pub fn into_parts(self) -> (AsyncSubmitError, AsyncJob) {
53        (self.error, self.job)
54    }
55}
56
57impl fmt::Debug for AsyncExecuteError {
58    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
59        formatter
60            .debug_struct("AsyncExecuteError")
61            .field("error", &self.error)
62            .field("job", &"<owned closure>")
63            .finish()
64    }
65}
66
67impl fmt::Display for AsyncExecuteError {
68    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
69        write!(
70            formatter,
71            "asynchronous executor rejected a job: {}",
72            self.error
73        )
74    }
75}
76
77impl std::error::Error for AsyncExecuteError {
78    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
79        Some(&self.error)
80    }
81}
82
83/// Runtime-neutral submission surface installed by an XLL application.
84///
85/// Each executor belongs to exactly one runtime generation. `execute` must
86/// either accept the closure exactly once or return it without running it.
87/// `shutdown` establishes an irreversible rejection boundary, waits until all
88/// accepted closures can no longer execute XLL code, and is idempotent. It must
89/// not detach work that can outlive XLL unload. The runtime never invokes
90/// `shutdown` from one of the executor's jobs; third-party implementations that
91/// permit that case must document it themselves. `execute` must not run the job
92/// synchronously or wait for the job to finish before returning: controller
93/// admission remains locked until acceptance commits.
94pub trait AsyncExecutor: Send + Sync + 'static {
95    /// Accepts `job` exactly once, or returns it without executing it.
96    ///
97    /// Implementations must establish the acceptance boundary before this
98    /// method returns and must not run the job synchronously.
99    fn execute(&self, job: AsyncJob) -> Result<(), AsyncExecuteError>;
100
101    /// Permanently rejects future jobs and waits for accepted jobs to stop.
102    ///
103    /// This is idempotent and is the executor-generation unload boundary: when
104    /// it returns, no accepted closure may still execute XLL code.
105    fn shutdown(&self);
106}
107
108enum ThreadPoolState {
109    New,
110    Running {
111        sender: SyncSender<AsyncJob>,
112        joins: Vec<JoinHandle<()>>,
113    },
114    ShuttingDown,
115    Closed,
116}
117
118/// Small optional standard-library executor with a bounded queue.
119///
120/// Shutdown is permanent: a closed executor never creates workers again.
121pub struct ThreadPoolExecutor {
122    workers: usize,
123    queue_bound: usize,
124    state: Mutex<ThreadPoolState>,
125    closed: Condvar,
126    #[cfg(test)]
127    fail_worker_at: Option<usize>,
128}
129
130impl ThreadPoolExecutor {
131    /// Creates a lazily started bounded executor.
132    ///
133    /// Returns `None` when either bound is zero. Once shut down, this executor
134    /// is permanently closed and cannot be restarted.
135    pub fn new(workers: usize, queue_bound: usize) -> Option<Self> {
136        (workers > 0 && queue_bound > 0).then_some(Self {
137            workers,
138            queue_bound,
139            state: Mutex::new(ThreadPoolState::New),
140            closed: Condvar::new(),
141            #[cfg(test)]
142            fail_worker_at: None,
143        })
144    }
145
146    #[cfg(test)]
147    fn failing_worker(workers: usize, queue_bound: usize, fail_worker_at: usize) -> Self {
148        Self {
149            workers,
150            queue_bound,
151            state: Mutex::new(ThreadPoolState::New),
152            closed: Condvar::new(),
153            fail_worker_at: Some(fail_worker_at),
154        }
155    }
156
157    fn lock_state(&self) -> std::sync::MutexGuard<'_, ThreadPoolState> {
158        self.state
159            .lock()
160            .unwrap_or_else(std::sync::PoisonError::into_inner)
161    }
162
163    fn start_locked(
164        &self,
165        state: &mut std::sync::MutexGuard<'_, ThreadPoolState>,
166    ) -> Result<(), Vec<JoinHandle<()>>> {
167        let (sender, receiver) = sync_channel(self.queue_bound);
168        let receiver = Arc::new(Mutex::new(receiver));
169        let mut joins = Vec::with_capacity(self.workers);
170        for index in 0..self.workers {
171            #[cfg(test)]
172            if self.fail_worker_at == Some(index) {
173                **state = ThreadPoolState::ShuttingDown;
174                drop(sender);
175                return Err(joins);
176            }
177            let receiver = receiver.clone();
178            let name = format!("excel-api-async-{index}");
179            match std::thread::Builder::new()
180                .name(name)
181                .spawn(move || worker_loop(&receiver))
182            {
183                Ok(join) => joins.push(join),
184                Err(_) => {
185                    **state = ThreadPoolState::ShuttingDown;
186                    drop(sender);
187                    return Err(joins);
188                }
189            }
190        }
191        **state = ThreadPoolState::Running { sender, joins };
192        Ok(())
193    }
194
195    fn finish_failed_start(
196        &self,
197        state: std::sync::MutexGuard<'_, ThreadPoolState>,
198        joins: Vec<JoinHandle<()>>,
199    ) {
200        drop(state);
201        for join in joins {
202            let _ = join.join();
203        }
204        let mut state = self.lock_state();
205        *state = ThreadPoolState::Closed;
206        self.closed.notify_all();
207    }
208
209    #[cfg(test)]
210    fn lifecycle(&self) -> &'static str {
211        match &*self.lock_state() {
212            ThreadPoolState::New => "New",
213            ThreadPoolState::Running { .. } => "Running",
214            ThreadPoolState::ShuttingDown => "ShuttingDown",
215            ThreadPoolState::Closed => "Closed",
216        }
217    }
218}
219
220fn worker_loop(receiver: &Mutex<Receiver<AsyncJob>>) {
221    loop {
222        let job = receiver
223            .lock()
224            .unwrap_or_else(std::sync::PoisonError::into_inner)
225            .recv();
226        match job {
227            Ok(job) => job(),
228            Err(_) => return,
229        }
230    }
231}
232
233impl AsyncExecutor for ThreadPoolExecutor {
234    fn execute(&self, job: AsyncJob) -> Result<(), AsyncExecuteError> {
235        let mut state = self.lock_state();
236        if matches!(*state, ThreadPoolState::New) {
237            if let Err(joins) = self.start_locked(&mut state) {
238                self.finish_failed_start(state, joins);
239                return Err(AsyncExecuteError::new(
240                    AsyncSubmitError::WorkerStartFailed,
241                    job,
242                ));
243            }
244        }
245        match &mut *state {
246            ThreadPoolState::Running { sender, .. } => match sender.try_send(job) {
247                Ok(()) => Ok(()),
248                Err(TrySendError::Full(job)) => Err(AsyncExecuteError::new(
249                    AsyncSubmitError::ExecutorQueueFull,
250                    job,
251                )),
252                Err(TrySendError::Disconnected(job)) => Err(AsyncExecuteError::new(
253                    AsyncSubmitError::ExecutorClosed,
254                    job,
255                )),
256            },
257            ThreadPoolState::ShuttingDown | ThreadPoolState::Closed => Err(AsyncExecuteError::new(
258                AsyncSubmitError::ExecutorClosed,
259                job,
260            )),
261            ThreadPoolState::New => unreachable!("startup resolved the New state"),
262        }
263    }
264
265    fn shutdown(&self) {
266        let joins = {
267            let mut state = self.lock_state();
268            loop {
269                match std::mem::replace(&mut *state, ThreadPoolState::ShuttingDown) {
270                    ThreadPoolState::New => {
271                        *state = ThreadPoolState::Closed;
272                        self.closed.notify_all();
273                        return;
274                    }
275                    ThreadPoolState::Running { sender, joins } => {
276                        drop(sender);
277                        break joins;
278                    }
279                    ThreadPoolState::ShuttingDown => {
280                        *state = ThreadPoolState::ShuttingDown;
281                        state = self
282                            .closed
283                            .wait(state)
284                            .unwrap_or_else(std::sync::PoisonError::into_inner);
285                    }
286                    ThreadPoolState::Closed => {
287                        *state = ThreadPoolState::Closed;
288                        return;
289                    }
290                }
291            }
292        };
293        for join in joins {
294            let _ = join.join();
295        }
296        let mut state = self.lock_state();
297        *state = ThreadPoolState::Closed;
298        self.closed.notify_all();
299    }
300}
301
302#[derive(Clone, Copy, Debug, Eq, PartialEq)]
303/// Describes why asynchronous submission could not be committed.
304pub enum AsyncSubmitError {
305    /// No executor was installed for the current runtime generation.
306    ExecutorUnavailable,
307    /// A third-party executor rejected the job before accepting it.
308    ExecutorRejected,
309    /// The executor's own bounded queue has no capacity.
310    ExecutorQueueFull,
311    /// The executor generation has crossed its permanent shutdown boundary.
312    ExecutorClosed,
313    /// The built-in executor could not start every required worker.
314    WorkerStartFailed,
315    /// The controller's configured in-flight request limit was reached.
316    CapacityExhausted,
317    /// Runtime shutdown won the submission race.
318    RuntimeClosing,
319    /// Excel supplied a malformed or null asynchronous completion handle.
320    InvalidHandle,
321}
322
323impl fmt::Display for AsyncSubmitError {
324    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
325        formatter.write_str(match self {
326            Self::ExecutorUnavailable => "no asynchronous executor is installed",
327            Self::ExecutorRejected => "the asynchronous executor rejected the job",
328            Self::ExecutorQueueFull => "the asynchronous executor queue is full",
329            Self::ExecutorClosed => "the asynchronous executor generation is closed",
330            Self::WorkerStartFailed => "an asynchronous executor worker could not be started",
331            Self::CapacityExhausted => "the asynchronous in-flight limit was reached",
332            Self::RuntimeClosing => "the asynchronous runtime is closing",
333            Self::InvalidHandle => "Excel supplied an invalid asynchronous handle",
334        })
335    }
336}
337
338impl std::error::Error for AsyncSubmitError {}
339
340#[derive(Debug)]
341/// Describes why an accepted asynchronous request could not publish a result.
342pub enum AsyncCompletionError {
343    /// Calculation cancellation retired the request before completion.
344    Canceled,
345    /// A second completion attempt targeted an already terminal request.
346    AlreadyCompleted,
347    /// The runtime generation is shutting down and will not publish results.
348    RuntimeClosing,
349    /// Planning or materializing the return value failed before `xlAsyncReturn`.
350    Return(ThunkError),
351    /// `xlAsyncReturn` returned a non-success Excel result.
352    Excel {
353        /// Exact Excel C API return code.
354        code: ExcelReturnCode,
355        /// Boolean result returned by Excel when it supplied one.
356        accepted: Option<bool>,
357    },
358}
359
360impl fmt::Display for AsyncCompletionError {
361    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
362        match self {
363            Self::Canceled => formatter.write_str("asynchronous request was canceled"),
364            Self::AlreadyCompleted => formatter.write_str("asynchronous request already completed"),
365            Self::RuntimeClosing => formatter.write_str("asynchronous runtime is closing"),
366            Self::Return(error) => write!(formatter, "asynchronous return failed: {error}"),
367            Self::Excel { code, accepted } => {
368                write!(formatter, "xlAsyncReturn failed with {code}")?;
369                if let Some(accepted) = accepted {
370                    write!(formatter, " (accepted={accepted})")?;
371                }
372                Ok(())
373            }
374        }
375    }
376}
377
378impl std::error::Error for AsyncCompletionError {
379    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
380        match self {
381            Self::Return(error) => Some(error),
382            _ => None,
383        }
384    }
385}
386
387/// Cooperative cancellation signal available to asynchronous function bodies.
388#[derive(Clone)]
389pub struct AsyncCancellationToken {
390    request: Weak<Request>,
391}
392
393impl AsyncCancellationToken {
394    /// Returns whether the owning request or runtime generation was canceled.
395    ///
396    /// The token is cooperative: a running task must inspect it and return on
397    /// its own. Ignoring it never permits publishing into a retired generation.
398    pub fn is_cancellation_requested(&self) -> bool {
399        self.request.upgrade().is_none_or(|request| {
400            matches!(
401                request.state.load(Ordering::Acquire),
402                CANCEL_REQUESTED | CANCELED
403            ) || request
404                .owner
405                .upgrade()
406                .is_none_or(|owner| !owner.is_active(request.epoch))
407        })
408    }
409}
410
411#[derive(Clone, Copy, Debug, Eq, PartialEq)]
412struct AsyncHandle {
413    value: usize,
414    size: i32,
415}
416
417// The pointer-sized value is an opaque Excel token: it is copied and passed
418// back but never dereferenced or freed by Rust.
419// SAFETY: moving the copied integer bits does not grant pointer access.
420unsafe impl Send for AsyncHandle {}
421// SAFETY: shared access exposes no dereference or mutation operation.
422unsafe impl Sync for AsyncHandle {}
423
424impl AsyncHandle {
425    unsafe fn copy_from(raw: LPXLOPER12) -> Result<Self, AsyncSubmitError> {
426        // SAFETY: the generated thunk contract guarantees a readable callback root.
427        let raw = unsafe { raw.as_ref() }.ok_or(AsyncSubmitError::InvalidHandle)?;
428        if raw.xltype & excel_api_sys::XLTYPE_MASK != excel_api_sys::xltypeBigData {
429            return Err(AsyncSubmitError::InvalidHandle);
430        }
431        // SAFETY: the validated tag selects the bigdata union member.
432        let bigdata = unsafe { raw.val.bigdata };
433        // SAFETY: Excel's async handle uses the hdata arm and remains opaque.
434        let value = unsafe { bigdata.h.hdata } as usize;
435        if value == 0 {
436            return Err(AsyncSubmitError::InvalidHandle);
437        }
438        Ok(Self {
439            value,
440            size: bigdata.cbData,
441        })
442    }
443
444    fn root(self) -> XLOPER12 {
445        XLOPER12 {
446            val: XLOPER12Value {
447                bigdata: XLOPER12BigData {
448                    h: XLOPER12BigDataHandle {
449                        hdata: self.value as *mut core::ffi::c_void,
450                    },
451                    cbData: self.size,
452                },
453            },
454            xltype: excel_api_sys::xltypeBigData,
455        }
456    }
457}
458
459struct Request {
460    id: u64,
461    epoch: u64,
462    handle: AsyncHandle,
463    state: AtomicU8,
464    retired: AtomicBool,
465    owner: Weak<AsyncController>,
466}
467
468impl Request {
469    fn cancel(&self) {
470        loop {
471            let state = self.state.load(Ordering::Acquire);
472            let next = match state {
473                SCHEDULED => CANCELED,
474                RUNNING => CANCEL_REQUESTED,
475                _ => return,
476            };
477            if self
478                .state
479                .compare_exchange(state, next, Ordering::AcqRel, Ordering::Acquire)
480                .is_ok()
481            {
482                return;
483            }
484        }
485    }
486
487    fn try_start(&self) -> bool {
488        let Some(owner) = self.owner.upgrade() else {
489            return false;
490        };
491        let state = owner.lock_state();
492        let current = state.requests.get(&self.id).map(Arc::as_ptr);
493        let registered = current == Some(self as *const Self);
494        let may_start = state.active
495            && owner.epoch == self.epoch
496            && registered
497            && !self.retired.load(Ordering::Acquire);
498        may_start
499            && self
500                .state
501                .compare_exchange(SCHEDULED, RUNNING, Ordering::AcqRel, Ordering::Acquire)
502                .is_ok()
503    }
504
505    fn complete(&self, value: ExcelReturnValue) -> Result<(), AsyncCompletionError> {
506        self.state
507            .compare_exchange(RUNNING, COMPLETING, Ordering::AcqRel, Ordering::Acquire)
508            .map_err(|state| match state {
509                CANCEL_REQUESTED | CANCELED => AsyncCompletionError::Canceled,
510                _ => AsyncCompletionError::AlreadyCompleted,
511            })?;
512        let Some(owner) = self.owner.upgrade() else {
513            self.state.store(CANCELED, Ordering::Release);
514            self.retired.store(true, Ordering::Release);
515            return Err(AsyncCompletionError::RuntimeClosing);
516        };
517        if !owner.is_active(self.epoch) {
518            self.state.store(CANCELED, Ordering::Release);
519            self.retire();
520            return Err(AsyncCompletionError::RuntimeClosing);
521        }
522
523        let result = value
524            .plan()
525            .map_err(ThunkError::ReturnPlanning)
526            .and_then(|plan| plan.materialize().map_err(ThunkError::Materialization));
527        let result = match result {
528            Ok(result) => owner.return_to_excel(self.handle, result),
529            Err(error) => Err(AsyncCompletionError::Return(error)),
530        };
531        self.state.store(COMPLETED, Ordering::Release);
532        self.retire();
533        result
534    }
535
536    fn retire(&self) {
537        if self.retired.swap(true, Ordering::AcqRel) {
538            return;
539        }
540        if let Some(owner) = self.owner.upgrade() {
541            owner.retire(self.id, self as *const Self);
542        }
543    }
544}
545
546struct ControllerState {
547    active: bool,
548    requests: HashMap<u64, Arc<Request>>,
549    in_flight: usize,
550}
551
552struct AsyncController {
553    executor: Arc<dyn AsyncExecutor>,
554    backend: Arc<dyn ExcelCallBackend>,
555    maximum: usize,
556    epoch: u64,
557    next_id: AtomicU64,
558    state: Mutex<ControllerState>,
559    #[cfg(test)]
560    before_submit: Mutex<Option<Arc<SubmissionPause>>>,
561}
562
563impl AsyncController {
564    fn new(
565        executor: Arc<dyn AsyncExecutor>,
566        backend: Arc<dyn ExcelCallBackend>,
567        maximum: usize,
568        epoch: u64,
569    ) -> Arc<Self> {
570        Arc::new(Self {
571            executor,
572            backend,
573            maximum: maximum.max(1),
574            epoch,
575            next_id: AtomicU64::new(1),
576            state: Mutex::new(ControllerState {
577                active: true,
578                requests: HashMap::new(),
579                in_flight: 0,
580            }),
581            #[cfg(test)]
582            before_submit: Mutex::new(None),
583        })
584    }
585
586    fn lock_state(&self) -> std::sync::MutexGuard<'_, ControllerState> {
587        self.state
588            .lock()
589            .unwrap_or_else(std::sync::PoisonError::into_inner)
590    }
591
592    fn is_active(&self, epoch: u64) -> bool {
593        let state = self.lock_state();
594        state.active && self.epoch == epoch
595    }
596
597    fn schedule(
598        self: &Arc<Self>,
599        handle: AsyncHandle,
600        task: Box<
601            dyn FnOnce(AsyncCancellationToken) -> Result<ExcelReturnValue, ThunkError>
602                + Send
603                + 'static,
604        >,
605    ) -> Result<(), AsyncSubmitError> {
606        let request = {
607            let mut state = self.lock_state();
608            if !state.active {
609                return Err(AsyncSubmitError::RuntimeClosing);
610            }
611            if state.in_flight >= self.maximum {
612                return Err(AsyncSubmitError::CapacityExhausted);
613            }
614            let id = self.next_id.fetch_add(1, Ordering::Relaxed);
615            let request = Arc::new(Request {
616                id,
617                epoch: self.epoch,
618                handle,
619                state: AtomicU8::new(SCHEDULED),
620                retired: AtomicBool::new(false),
621                owner: Arc::downgrade(self),
622            });
623            state.in_flight += 1;
624            state.requests.insert(id, request.clone());
625            request
626        };
627
628        #[cfg(test)]
629        if let Some(pause) = self
630            .before_submit
631            .lock()
632            .unwrap_or_else(std::sync::PoisonError::into_inner)
633            .clone()
634        {
635            pause.reached.wait();
636            pause.release.wait();
637        }
638
639        let token = AsyncCancellationToken {
640            request: Arc::downgrade(&request),
641        };
642        let job_request = request.clone();
643        let job = Box::new(move || {
644            if !job_request.try_start() {
645                job_request.retire();
646                return;
647            }
648            let outcome = std::panic::catch_unwind(AssertUnwindSafe(|| task(token)));
649            let value = match outcome {
650                Ok(Ok(value)) => value,
651                Ok(Err(error)) => {
652                    emit_async_failure();
653                    ExcelReturnValue::Error(crate::thunk::error_for(&error))
654                }
655                Err(_) => {
656                    emit_async_failure();
657                    ExcelReturnValue::Error(ExcelError::Value)
658                }
659            };
660            if let Err(AsyncCompletionError::Canceled) = job_request.complete(value) {
661                job_request.state.store(CANCELED, Ordering::Release);
662                job_request.retire();
663            }
664        }) as AsyncJob;
665        // This second gate is the schedule/shutdown linearization point. If
666        // shutdown won, the request is never offered to the executor. If this
667        // call accepts, shutdown cannot deactivate the controller until the
668        // executor has committed that acceptance. A worker attempting to start
669        // waits on this same state mutex, so user code cannot run under it.
670        let state = self.lock_state();
671        if !state.active
672            || state
673                .requests
674                .get(&request.id)
675                .is_none_or(|registered| !Arc::ptr_eq(registered, &request))
676        {
677            drop(state);
678            drop(job);
679            request.cancel();
680            request.retire();
681            return Err(AsyncSubmitError::RuntimeClosing);
682        }
683        let submitted = self.executor.execute(job);
684        drop(state);
685        match submitted {
686            Ok(()) => Ok(()),
687            Err(error) => {
688                let submit_error = error.error();
689                let (_error, rejected_job) = error.into_parts();
690                drop(rejected_job);
691                request.cancel();
692                request.retire();
693                Err(submit_error)
694            }
695        }
696    }
697
698    fn retire(&self, id: u64, expected: *const Request) {
699        let mut state = self.lock_state();
700        let matches = state
701            .requests
702            .get(&id)
703            .is_some_and(|request| Arc::as_ptr(request) == expected);
704        if matches {
705            state.requests.remove(&id);
706            #[cfg(test)]
707            debug_assert!(state.in_flight > 0, "async in-flight accounting underflow");
708            if state.in_flight > 0 {
709                state.in_flight -= 1;
710            }
711        }
712    }
713
714    fn cancel_all(&self) {
715        let requests: Vec<_> = self.lock_state().requests.values().cloned().collect();
716        for request in requests {
717            request.cancel();
718            if request.state.load(Ordering::Acquire) == CANCELED {
719                request.retire();
720            }
721        }
722    }
723
724    fn calculation_ended(&self) {
725        self.cancel_all();
726    }
727
728    fn shutdown(&self) {
729        let requests = {
730            let mut state = self.lock_state();
731            if !state.active {
732                None
733            } else {
734                state.active = false;
735                Some(state.requests.values().cloned().collect::<Vec<_>>())
736            }
737        };
738        let Some(requests) = requests else {
739            self.executor.shutdown();
740            return;
741        };
742        for request in &requests {
743            request.cancel();
744        }
745        // No controller/global lock is held while the executor joins workers.
746        self.executor.shutdown();
747        for request in requests {
748            request.state.store(CANCELED, Ordering::Release);
749            request.retire();
750        }
751    }
752
753    fn return_to_excel(
754        &self,
755        handle: AsyncHandle,
756        mut value: ExcelReturn,
757    ) -> Result<(), AsyncCompletionError> {
758        if !self.is_active(self.epoch) || !self.backend.is_linked() {
759            return Err(AsyncCompletionError::RuntimeClosing);
760        }
761        let mut handle = handle.root();
762        let mut response = XLOPER12 {
763            val: XLOPER12Value { xbool: 0 },
764            xltype: excel_api_sys::xltypeNil,
765        };
766        let mut arguments = [
767            &mut handle as LPXLOPER12,
768            value.as_xloper_mut_for_callback() as LPXLOPER12,
769        ];
770        // SAFETY: roots remain stable for this synchronous xlAsyncReturn call.
771        let raw = unsafe {
772            self.backend.excel12v_raw(
773                excel_api_sys::xlAsyncReturn,
774                &mut response,
775                2,
776                arguments.as_mut_ptr(),
777            )
778        };
779        let accepted = if response.xltype & excel_api_sys::XLTYPE_MASK == excel_api_sys::xltypeBool
780        {
781            // SAFETY: guarded by the Boolean tag.
782            Some(unsafe { response.val.xbool != 0 })
783        } else {
784            None
785        };
786        if raw == excel_api_sys::xlretSuccess && accepted == Some(true) {
787            Ok(())
788        } else {
789            Err(AsyncCompletionError::Excel {
790                code: ExcelReturnCode(raw),
791                accepted,
792            })
793        }
794    }
795
796    #[cfg(test)]
797    fn accounting(&self) -> (usize, usize) {
798        let state = self.lock_state();
799        (state.in_flight, state.requests.len())
800    }
801}
802
803fn emit_async_failure() {
804    crate::diagnostics::emit(crate::DiagnosticEvent::new(
805        crate::DiagnosticCode::ThunkFailure,
806        crate::DiagnosticSeverity::Error,
807        0,
808    ));
809}
810
811struct PendingExecutor {
812    executor: Arc<dyn AsyncExecutor>,
813    maximum_in_flight: usize,
814}
815
816#[derive(Default)]
817struct Generations {
818    pending: Option<PendingExecutor>,
819    active: Option<Arc<AsyncController>>,
820    next_epoch: u64,
821}
822
823fn generations() -> &'static Mutex<Generations> {
824    static GENERATIONS: OnceLock<Mutex<Generations>> = OnceLock::new();
825    GENERATIONS.get_or_init(|| Mutex::new(Generations::default()))
826}
827
828fn lock_generations() -> std::sync::MutexGuard<'static, Generations> {
829    generations()
830        .lock()
831        .unwrap_or_else(std::sync::PoisonError::into_inner)
832}
833
834pub(crate) fn install_production_executor(
835    executor: Arc<dyn AsyncExecutor>,
836    maximum_in_flight: usize,
837) -> Result<(), Arc<dyn AsyncExecutor>> {
838    let mut generations = lock_generations();
839    if generations.pending.is_some() || generations.active.is_some() {
840        return Err(executor);
841    }
842    generations.pending = Some(PendingExecutor {
843        executor,
844        maximum_in_flight: maximum_in_flight.max(1),
845    });
846    Ok(())
847}
848
849pub(crate) fn activate(backend: Arc<dyn ExcelCallBackend>) -> Result<(), AsyncSubmitError> {
850    let mut generations = lock_generations();
851    if generations.active.is_some() {
852        return Ok(());
853    }
854    let pending = generations
855        .pending
856        .take()
857        .ok_or(AsyncSubmitError::ExecutorUnavailable)?;
858    generations.next_epoch = generations.next_epoch.wrapping_add(1).max(1);
859    generations.active = Some(AsyncController::new(
860        pending.executor,
861        backend,
862        pending.maximum_in_flight,
863        generations.next_epoch,
864    ));
865    Ok(())
866}
867
868pub(crate) fn shutdown() {
869    let controller = lock_generations().active.take();
870    if let Some(controller) = controller {
871        controller.shutdown();
872    }
873}
874
875fn active_controller() -> Option<Arc<AsyncController>> {
876    lock_generations().active.clone()
877}
878
879#[cfg(test)]
880pub(crate) fn reset_generations_for_test() {
881    let (active, pending) = {
882        let mut generations = lock_generations();
883        let active = generations.active.take();
884        let pending = generations.pending.take();
885        (active, pending)
886    };
887    if let Some(active) = active {
888        active.shutdown();
889    }
890    if let Some(pending) = pending {
891        pending.executor.shutdown();
892    }
893}
894
895pub(crate) fn calculation_canceled() {
896    if let Some(controller) = active_controller() {
897        controller.cancel_all();
898    }
899}
900
901pub(crate) fn calculation_ended() {
902    if let Some(controller) = active_controller() {
903        controller.calculation_ended();
904    }
905}
906
907/// Excel calculation-cancellation event procedure registered by name.
908#[unsafe(export_name = "excel_api_calculation_canceled")]
909pub extern "system" fn calculation_canceled_event() {
910    let _ = std::panic::catch_unwind(calculation_canceled);
911}
912
913/// Excel calculation-ended event procedure registered by name.
914#[unsafe(export_name = "excel_api_calculation_ended")]
915pub extern "system" fn calculation_ended_event() {
916    let _ = std::panic::catch_unwind(calculation_ended);
917}
918
919/// Schedules an owned asynchronous result from a generated async thunk.
920///
921/// This entry point is an implementation detail of the procedural macros.
922/// Application code should declare an async worksheet function instead of
923/// calling it directly.
924///
925/// # Safety
926///
927/// `raw_handle` must be a readable `XLOPER12` root supplied by Excel for the
928/// current asynchronous-UDF callback. Its tag must select a valid non-null
929/// async handle, and the handle must not be retained, dereferenced, freed, or
930/// used after Excel retires it. The call must occur only through the generated
931/// thunk's verified callback path; it does not create a general worker-thread
932/// Excel callback capability.
933#[doc(hidden)]
934pub unsafe fn schedule(
935    raw_handle: LPXLOPER12,
936    task: Box<
937        dyn FnOnce(AsyncCancellationToken) -> Result<ExcelReturnValue, ThunkError> + Send + 'static,
938    >,
939) -> Result<(), AsyncSubmitError> {
940    let controller = active_controller().ok_or(AsyncSubmitError::ExecutorUnavailable)?;
941    // SAFETY: forwarded from the generated async thunk contract.
942    let handle = unsafe { AsyncHandle::copy_from(raw_handle) }?;
943    controller.schedule(handle, task)
944}
945
946#[cfg(test)]
947struct SubmissionPause {
948    reached: std::sync::Barrier,
949    release: std::sync::Barrier,
950}
951
952#[cfg(test)]
953mod tests {
954    use super::*;
955    use core::ffi::c_int;
956    use std::{
957        collections::VecDeque,
958        sync::{Barrier, mpsc},
959        time::Duration,
960    };
961
962    type RecordedCall = (i32, usize, usize, u32, f64);
963
964    struct QueueState {
965        jobs: VecDeque<AsyncJob>,
966        closed: bool,
967    }
968
969    #[derive(Default)]
970    struct QueueExecutor {
971        state: Mutex<Option<QueueState>>,
972        shutdowns: AtomicU64,
973    }
974
975    impl QueueExecutor {
976        fn initialized() -> Self {
977            Self {
978                state: Mutex::new(Some(QueueState {
979                    jobs: VecDeque::new(),
980                    closed: false,
981                })),
982                shutdowns: AtomicU64::new(0),
983            }
984        }
985
986        fn run_one(&self) {
987            let job = self
988                .state
989                .lock()
990                .unwrap()
991                .as_mut()
992                .unwrap()
993                .jobs
994                .pop_front()
995                .expect("queued job");
996            job();
997        }
998    }
999
1000    impl AsyncExecutor for QueueExecutor {
1001        fn execute(&self, job: AsyncJob) -> Result<(), AsyncExecuteError> {
1002            let mut state = self.state.lock().unwrap();
1003            let state = state.as_mut().unwrap();
1004            if state.closed {
1005                Err(AsyncExecuteError::new(
1006                    AsyncSubmitError::ExecutorClosed,
1007                    job,
1008                ))
1009            } else {
1010                state.jobs.push_back(job);
1011                Ok(())
1012            }
1013        }
1014
1015        fn shutdown(&self) {
1016            self.shutdowns.fetch_add(1, Ordering::AcqRel);
1017            let jobs = {
1018                let mut state = self.state.lock().unwrap();
1019                let state = state.as_mut().unwrap();
1020                state.closed = true;
1021                std::mem::take(&mut state.jobs)
1022            };
1023            for job in jobs {
1024                job();
1025            }
1026        }
1027    }
1028
1029    #[derive(Default)]
1030    struct MockBackend {
1031        linked: AtomicBool,
1032        code: std::sync::atomic::AtomicI32,
1033        accepted: AtomicBool,
1034        calls: Mutex<Vec<RecordedCall>>,
1035    }
1036
1037    impl MockBackend {
1038        fn linked() -> Self {
1039            Self {
1040                linked: AtomicBool::new(true),
1041                accepted: AtomicBool::new(true),
1042                ..Self::default()
1043            }
1044        }
1045    }
1046
1047    impl ExcelCallBackend for MockBackend {
1048        fn link(&self) -> Result<(), crate::ExcelCallError> {
1049            self.linked.store(true, Ordering::Release);
1050            Ok(())
1051        }
1052        fn unlink(&self) {
1053            self.linked.store(false, Ordering::Release);
1054        }
1055        fn is_linked(&self) -> bool {
1056            self.linked.load(Ordering::Acquire)
1057        }
1058        unsafe fn excel12v_raw(
1059            &self,
1060            function: i32,
1061            result: *mut XLOPER12,
1062            count: c_int,
1063            arguments: *mut LPXLOPER12,
1064        ) -> i32 {
1065            // SAFETY: the controller supplies the exact two initialized roots.
1066            let handle = unsafe { (**arguments).val.bigdata };
1067            // SAFETY: the second root is the numeric fixture result.
1068            let value = unsafe { (**arguments.add(1)).val.num };
1069            // SAFETY: the handle tag selects the opaque hdata arm.
1070            let handle_value = unsafe { handle.h.hdata } as usize;
1071            // SAFETY: the second argument root is initialized and live.
1072            let value_type = unsafe { (**arguments.add(1)).xltype };
1073            self.calls.lock().unwrap().push((
1074                function,
1075                count as usize,
1076                handle_value,
1077                value_type,
1078                value,
1079            ));
1080            // SAFETY: the test backend receives a required live result root.
1081            unsafe {
1082                (*result).val = XLOPER12Value {
1083                    xbool: i32::from(self.accepted.load(Ordering::Acquire)),
1084                };
1085                (*result).xltype = excel_api_sys::xltypeBool;
1086            }
1087            self.code.load(Ordering::Acquire)
1088        }
1089    }
1090
1091    fn handle(value: usize) -> AsyncHandle {
1092        AsyncHandle { value, size: 8 }
1093    }
1094
1095    fn number(value: f64) -> ExcelReturnValue {
1096        ExcelReturnValue::Number(value)
1097    }
1098
1099    #[test]
1100    fn public_async_errors_have_structured_error_contracts() {
1101        fn assert_error<T: std::error::Error>() {}
1102        assert_error::<AsyncExecuteError>();
1103        assert_error::<AsyncSubmitError>();
1104        assert_error::<AsyncCompletionError>();
1105
1106        let execute = AsyncExecuteError::new(AsyncSubmitError::ExecutorClosed, Box::new(|| {}));
1107        assert!(execute.to_string().contains("generation is closed"));
1108        assert!(std::error::Error::source(&execute).is_some());
1109
1110        let completion = AsyncCompletionError::Return(ThunkError::NullArgument);
1111        assert!(
1112            completion
1113                .to_string()
1114                .contains("asynchronous return failed")
1115        );
1116        assert!(std::error::Error::source(&completion).is_some());
1117    }
1118
1119    fn controller(
1120        executor: Arc<dyn AsyncExecutor>,
1121        backend: Arc<MockBackend>,
1122        maximum: usize,
1123        epoch: u64,
1124    ) -> Arc<AsyncController> {
1125        AsyncController::new(executor, backend, maximum, epoch)
1126    }
1127
1128    #[test]
1129    fn thread_pool_is_lazy_bounded_and_permanently_closed() {
1130        let pool = Arc::new(ThreadPoolExecutor::new(1, 1).unwrap());
1131        assert_eq!(pool.lifecycle(), "New");
1132        let (started_tx, started_rx) = mpsc::channel();
1133        let release = Arc::new(Barrier::new(2));
1134        let worker_release = release.clone();
1135        pool.execute(Box::new(move || {
1136            started_tx.send(()).unwrap();
1137            worker_release.wait();
1138        }))
1139        .unwrap();
1140        started_rx.recv_timeout(Duration::from_secs(2)).unwrap();
1141        pool.execute(Box::new(|| {})).unwrap();
1142        let rejected = pool.execute(Box::new(|| {})).unwrap_err();
1143        assert_eq!(rejected.error(), AsyncSubmitError::ExecutorQueueFull);
1144        release.wait();
1145        pool.shutdown();
1146        assert_eq!(pool.lifecycle(), "Closed");
1147        pool.shutdown();
1148        assert_eq!(
1149            pool.execute(Box::new(|| {})).unwrap_err().error(),
1150            AsyncSubmitError::ExecutorClosed
1151        );
1152        assert_eq!(pool.lifecycle(), "Closed");
1153    }
1154
1155    #[test]
1156    fn thread_pool_shutdown_with_empty_queue_is_permanent() {
1157        let pool = ThreadPoolExecutor::new(1, 1).unwrap();
1158        pool.shutdown();
1159        assert_eq!(pool.lifecycle(), "Closed");
1160        assert_eq!(
1161            pool.execute(Box::new(|| {})).unwrap_err().error(),
1162            AsyncSubmitError::ExecutorClosed
1163        );
1164    }
1165
1166    #[test]
1167    fn thread_pool_runs_multiple_workers_and_joins_queued_work() {
1168        let pool = Arc::new(ThreadPoolExecutor::new(2, 4).unwrap());
1169        let barrier = Arc::new(Barrier::new(3));
1170        let counter = Arc::new(std::sync::atomic::AtomicUsize::new(0));
1171        for _ in 0..2 {
1172            let barrier = barrier.clone();
1173            let counter = counter.clone();
1174            pool.execute(Box::new(move || {
1175                counter.fetch_add(1, Ordering::AcqRel);
1176                barrier.wait();
1177            }))
1178            .unwrap();
1179        }
1180        barrier.wait();
1181        pool.execute(Box::new({
1182            let counter = counter.clone();
1183            move || {
1184                counter.fetch_add(1, Ordering::AcqRel);
1185            }
1186        }))
1187        .unwrap();
1188        pool.shutdown();
1189        assert_eq!(counter.load(Ordering::Acquire), 3);
1190    }
1191
1192    #[test]
1193    fn thread_pool_partial_start_failure_closes_and_joins() {
1194        let pool = ThreadPoolExecutor::failing_worker(2, 2, 1);
1195        assert_eq!(
1196            pool.execute(Box::new(|| {})).unwrap_err().error(),
1197            AsyncSubmitError::WorkerStartFailed
1198        );
1199        assert_eq!(pool.lifecycle(), "Closed");
1200        assert_eq!(
1201            pool.execute(Box::new(|| {})).unwrap_err().error(),
1202            AsyncSubmitError::ExecutorClosed
1203        );
1204    }
1205
1206    #[test]
1207    fn execute_racing_shutdown_is_linearizable() {
1208        for _ in 0..32 {
1209            let pool = Arc::new(ThreadPoolExecutor::new(1, 2).unwrap());
1210            let gate = Arc::new(Barrier::new(2));
1211            let ran = Arc::new(AtomicBool::new(false));
1212            let submitter = {
1213                let pool = pool.clone();
1214                let gate = gate.clone();
1215                let ran = ran.clone();
1216                std::thread::spawn(move || {
1217                    gate.wait();
1218                    pool.execute(Box::new(move || ran.store(true, Ordering::Release)))
1219                })
1220            };
1221            gate.wait();
1222            pool.shutdown();
1223            let result = submitter.join().unwrap();
1224            assert!(result.is_err() || ran.load(Ordering::Acquire));
1225            assert_eq!(pool.lifecycle(), "Closed");
1226        }
1227    }
1228
1229    #[test]
1230    fn canceled_queued_work_skips_user_body_and_retires_once() {
1231        let executor = Arc::new(QueueExecutor::initialized());
1232        let backend = Arc::new(MockBackend::linked());
1233        let controller = controller(executor.clone(), backend.clone(), 2, 1);
1234        let called = Arc::new(AtomicBool::new(false));
1235        let body_called = called.clone();
1236        controller
1237            .schedule(
1238                handle(1),
1239                Box::new(move |_| {
1240                    body_called.store(true, Ordering::Release);
1241                    Ok(number(1.0))
1242                }),
1243            )
1244            .unwrap();
1245        controller.cancel_all();
1246        executor.run_one();
1247        assert!(!called.load(Ordering::Acquire));
1248        assert!(backend.calls.lock().unwrap().is_empty());
1249        assert_eq!(controller.accounting(), (0, 0));
1250    }
1251
1252    #[test]
1253    fn running_cancellation_sets_token_and_suppresses_ignored_result() {
1254        let executor = Arc::new(ThreadPoolExecutor::new(1, 2).unwrap());
1255        let backend = Arc::new(MockBackend::linked());
1256        let controller = controller(executor, backend.clone(), 2, 1);
1257        let entered = Arc::new(Barrier::new(2));
1258        let leave = Arc::new(Barrier::new(2));
1259        let observed = Arc::new(AtomicBool::new(false));
1260        controller
1261            .schedule(
1262                handle(1),
1263                Box::new({
1264                    let entered = entered.clone();
1265                    let leave = leave.clone();
1266                    let observed = observed.clone();
1267                    move |token| {
1268                        entered.wait();
1269                        leave.wait();
1270                        observed.store(token.is_cancellation_requested(), Ordering::Release);
1271                        Ok(number(9.0))
1272                    }
1273                }),
1274            )
1275            .unwrap();
1276        entered.wait();
1277        controller.cancel_all();
1278        leave.wait();
1279        controller.shutdown();
1280        assert!(observed.load(Ordering::Acquire));
1281        assert!(backend.calls.lock().unwrap().is_empty());
1282        assert_eq!(controller.accounting(), (0, 0));
1283    }
1284
1285    #[test]
1286    fn shutdown_between_reservation_and_submission_rejects_without_running() {
1287        let executor = Arc::new(ThreadPoolExecutor::new(1, 2).unwrap());
1288        let backend = Arc::new(MockBackend::linked());
1289        let controller = controller(executor, backend, 1, 1);
1290        let pause = Arc::new(SubmissionPause {
1291            reached: Barrier::new(2),
1292            release: Barrier::new(2),
1293        });
1294        *controller.before_submit.lock().unwrap() = Some(pause.clone());
1295        let called = Arc::new(AtomicBool::new(false));
1296        let schedule = {
1297            let controller = controller.clone();
1298            let called = called.clone();
1299            std::thread::spawn(move || {
1300                controller.schedule(
1301                    handle(1),
1302                    Box::new(move |_| {
1303                        called.store(true, Ordering::Release);
1304                        Ok(number(1.0))
1305                    }),
1306                )
1307            })
1308        };
1309        pause.reached.wait();
1310        controller.shutdown();
1311        pause.release.wait();
1312        assert_eq!(
1313            schedule.join().unwrap(),
1314            Err(AsyncSubmitError::RuntimeClosing)
1315        );
1316        assert!(!called.load(Ordering::Acquire));
1317        assert_eq!(controller.accounting(), (0, 0));
1318    }
1319
1320    #[test]
1321    fn schedule_before_reserve_and_after_accept_obey_shutdown_boundary() {
1322        let executor = Arc::new(ThreadPoolExecutor::new(1, 4).unwrap());
1323        let backend = Arc::new(MockBackend::linked());
1324        let controller = controller(executor, backend.clone(), 3, 1);
1325        let entered = Arc::new(Barrier::new(2));
1326        let release = Arc::new(Barrier::new(2));
1327        controller
1328            .schedule(
1329                handle(1),
1330                Box::new({
1331                    let entered = entered.clone();
1332                    let release = release.clone();
1333                    move |token| {
1334                        entered.wait();
1335                        release.wait();
1336                        assert!(token.is_cancellation_requested());
1337                        Ok(number(1.0))
1338                    }
1339                }),
1340            )
1341            .unwrap();
1342        entered.wait();
1343        let queued_called = Arc::new(AtomicBool::new(false));
1344        controller
1345            .schedule(
1346                handle(2),
1347                Box::new({
1348                    let queued_called = queued_called.clone();
1349                    move |_| {
1350                        queued_called.store(true, Ordering::Release);
1351                        Ok(number(2.0))
1352                    }
1353                }),
1354            )
1355            .unwrap();
1356        let shutdown = {
1357            let controller = controller.clone();
1358            std::thread::spawn(move || controller.shutdown())
1359        };
1360        while controller.is_active(1) {
1361            std::thread::yield_now();
1362        }
1363        assert_eq!(
1364            controller.schedule(handle(3), Box::new(|_| Ok(number(3.0)))),
1365            Err(AsyncSubmitError::RuntimeClosing)
1366        );
1367        release.wait();
1368        shutdown.join().unwrap();
1369        assert!(!queued_called.load(Ordering::Acquire));
1370        assert!(backend.calls.lock().unwrap().is_empty());
1371        assert_eq!(controller.accounting(), (0, 0));
1372    }
1373
1374    #[test]
1375    fn successful_completion_is_at_most_once_and_preserves_handle() {
1376        let executor = Arc::new(QueueExecutor::initialized());
1377        let backend = Arc::new(MockBackend::linked());
1378        let controller = controller(executor.clone(), backend.clone(), 2, 7);
1379        controller
1380            .schedule(handle(0x1234), Box::new(|_| Ok(number(4.5))))
1381            .unwrap();
1382        executor.run_one();
1383        assert_eq!(
1384            backend.calls.lock().unwrap().as_slice(),
1385            &[(
1386                excel_api_sys::xlAsyncReturn,
1387                2,
1388                0x1234,
1389                excel_api_sys::xltypeNum,
1390                4.5,
1391            )]
1392        );
1393        assert_eq!(controller.accounting(), (0, 0));
1394    }
1395
1396    #[test]
1397    fn completion_racing_cancellation_is_linearizable_and_retires_once() {
1398        for _ in 0..32 {
1399            let executor = Arc::new(QueueExecutor::initialized());
1400            let backend = Arc::new(MockBackend::linked());
1401            let controller = controller(executor, backend.clone(), 1, 1);
1402            let request = {
1403                let request = Arc::new(Request {
1404                    id: 1,
1405                    epoch: 1,
1406                    handle: handle(1),
1407                    state: AtomicU8::new(RUNNING),
1408                    retired: AtomicBool::new(false),
1409                    owner: Arc::downgrade(&controller),
1410                });
1411                let mut state = controller.lock_state();
1412                state.in_flight = 1;
1413                state.requests.insert(1, request.clone());
1414                request
1415            };
1416            let barrier = Arc::new(Barrier::new(3));
1417            let completing = {
1418                let request = request.clone();
1419                let barrier = barrier.clone();
1420                std::thread::spawn(move || {
1421                    barrier.wait();
1422                    let result = request.complete(number(1.0));
1423                    if matches!(result, Err(AsyncCompletionError::Canceled)) {
1424                        request.state.store(CANCELED, Ordering::Release);
1425                        request.retire();
1426                    }
1427                    result
1428                })
1429            };
1430            let canceling = {
1431                let request = request.clone();
1432                let barrier = barrier.clone();
1433                std::thread::spawn(move || {
1434                    barrier.wait();
1435                    request.cancel();
1436                })
1437            };
1438            barrier.wait();
1439            let completion = completing.join().unwrap();
1440            canceling.join().unwrap();
1441            assert!(
1442                completion.is_ok() || matches!(completion, Err(AsyncCompletionError::Canceled))
1443            );
1444            assert!(backend.calls.lock().unwrap().len() <= 1);
1445            assert_eq!(controller.accounting(), (0, 0));
1446        }
1447    }
1448
1449    #[test]
1450    fn excel_rejection_and_user_panic_each_retire_exactly_once() {
1451        let executor = Arc::new(QueueExecutor::initialized());
1452        let backend = Arc::new(MockBackend::linked());
1453        backend.accepted.store(false, Ordering::Release);
1454        let controller = controller(executor.clone(), backend.clone(), 2, 1);
1455        controller
1456            .schedule(handle(1), Box::new(|_| Ok(number(1.0))))
1457            .unwrap();
1458        controller
1459            .schedule(
1460                handle(2),
1461                Box::new(|_| -> Result<ExcelReturnValue, ThunkError> { panic!("fixture") }),
1462            )
1463            .unwrap();
1464        executor.run_one();
1465        executor.run_one();
1466        assert_eq!(backend.calls.lock().unwrap().len(), 2);
1467        assert_eq!(controller.accounting(), (0, 0));
1468    }
1469
1470    #[test]
1471    fn excel_return_code_and_boolean_rejection_are_preserved() {
1472        let executor = Arc::new(QueueExecutor::initialized());
1473        let backend = Arc::new(MockBackend::linked());
1474        backend.accepted.store(false, Ordering::Release);
1475        backend.code.store(
1476            excel_api_sys::xlretInvAsynchronousContext,
1477            Ordering::Release,
1478        );
1479        let controller = controller(executor, backend, 1, 1);
1480        let request = Arc::new(Request {
1481            id: 1,
1482            epoch: 1,
1483            handle: handle(1),
1484            state: AtomicU8::new(RUNNING),
1485            retired: AtomicBool::new(false),
1486            owner: Arc::downgrade(&controller),
1487        });
1488        {
1489            let mut state = controller.lock_state();
1490            state.in_flight = 1;
1491            state.requests.insert(1, request.clone());
1492        }
1493        assert!(matches!(
1494            request.complete(number(1.0)),
1495            Err(AsyncCompletionError::Excel {
1496                code: ExcelReturnCode(excel_api_sys::xlretInvAsynchronousContext),
1497                accepted: Some(false),
1498            })
1499        ));
1500        assert_eq!(controller.accounting(), (0, 0));
1501    }
1502
1503    #[test]
1504    fn invalid_async_handles_are_rejected_before_submission() {
1505        assert_eq!(
1506            // SAFETY: null intentionally exercises defensive validation.
1507            unsafe { AsyncHandle::copy_from(core::ptr::null_mut()) },
1508            Err(AsyncSubmitError::InvalidHandle)
1509        );
1510        let mut wrong = XLOPER12 {
1511            val: XLOPER12Value { num: 1.0 },
1512            xltype: excel_api_sys::xltypeNum,
1513        };
1514        assert_eq!(
1515            // SAFETY: `wrong` is a readable live root with a deliberately wrong tag.
1516            unsafe { AsyncHandle::copy_from(&mut wrong) },
1517            Err(AsyncSubmitError::InvalidHandle)
1518        );
1519    }
1520
1521    #[test]
1522    fn stale_generation_cannot_complete_after_reopen_or_unlink() {
1523        let old_executor = Arc::new(QueueExecutor::initialized());
1524        let backend = Arc::new(MockBackend::linked());
1525        let old = controller(old_executor.clone(), backend.clone(), 1, 1);
1526        old.schedule(handle(1), Box::new(|_| Ok(number(1.0))))
1527            .unwrap();
1528        old.shutdown();
1529        let new_executor = Arc::new(QueueExecutor::initialized());
1530        let new = controller(new_executor.clone(), backend.clone(), 1, 2);
1531        new.schedule(handle(2), Box::new(|_| Ok(number(2.0))))
1532            .unwrap();
1533        backend.unlink();
1534        new_executor.run_one();
1535        assert!(backend.calls.lock().unwrap().is_empty());
1536        new.shutdown();
1537    }
1538
1539    #[test]
1540    fn calculation_canceled_then_ended_is_idempotent() {
1541        let executor = Arc::new(QueueExecutor::initialized());
1542        let backend = Arc::new(MockBackend::linked());
1543        let controller = controller(executor.clone(), backend, 1, 1);
1544        controller
1545            .schedule(handle(1), Box::new(|_| Ok(number(1.0))))
1546            .unwrap();
1547        controller.cancel_all();
1548        controller.calculation_ended();
1549        executor.run_one();
1550        assert_eq!(controller.accounting(), (0, 0));
1551    }
1552
1553    #[test]
1554    fn executor_rejection_preserves_specific_error_and_accounting() {
1555        let executor = Arc::new(QueueExecutor::initialized());
1556        executor.shutdown();
1557        let backend = Arc::new(MockBackend::linked());
1558        let controller = controller(executor, backend, 1, 1);
1559        assert_eq!(
1560            controller.schedule(handle(1), Box::new(|_| Ok(number(1.0)))),
1561            Err(AsyncSubmitError::ExecutorClosed)
1562        );
1563        assert_eq!(controller.accounting(), (0, 0));
1564    }
1565}