1use 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
28pub type AsyncJob = Box<dyn FnOnce() + Send + 'static>;
30
31pub struct AsyncExecuteError {
33 error: AsyncSubmitError,
34 job: AsyncJob,
35}
36
37impl AsyncExecuteError {
38 pub fn new(error: AsyncSubmitError, job: AsyncJob) -> Self {
43 Self { error, job }
44 }
45
46 pub fn error(&self) -> AsyncSubmitError {
48 self.error
49 }
50
51 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
83pub trait AsyncExecutor: Send + Sync + 'static {
95 fn execute(&self, job: AsyncJob) -> Result<(), AsyncExecuteError>;
100
101 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
118pub 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 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)]
303pub enum AsyncSubmitError {
305 ExecutorUnavailable,
307 ExecutorRejected,
309 ExecutorQueueFull,
311 ExecutorClosed,
313 WorkerStartFailed,
315 CapacityExhausted,
317 RuntimeClosing,
319 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)]
341pub enum AsyncCompletionError {
343 Canceled,
345 AlreadyCompleted,
347 RuntimeClosing,
349 Return(ThunkError),
351 Excel {
353 code: ExcelReturnCode,
355 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#[derive(Clone)]
389pub struct AsyncCancellationToken {
390 request: Weak<Request>,
391}
392
393impl AsyncCancellationToken {
394 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
417unsafe impl Send for AsyncHandle {}
421unsafe impl Sync for AsyncHandle {}
423
424impl AsyncHandle {
425 unsafe fn copy_from(raw: LPXLOPER12) -> Result<Self, AsyncSubmitError> {
426 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 let bigdata = unsafe { raw.val.bigdata };
433 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 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 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 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 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#[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#[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#[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 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 let handle = unsafe { (**arguments).val.bigdata };
1067 let value = unsafe { (**arguments.add(1)).val.num };
1069 let handle_value = unsafe { handle.h.hdata } as usize;
1071 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 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 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 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}