1use core::mem::size_of;
10
11use excel_api_sys::{
12 XCHAR, XLOPER12, XLOPER12Array, XLOPER12Value, XLTYPE_MASK, xlbitDLLFree, xlbitXLFree,
13 xltypeBool, xltypeErr, xltypeInt, xltypeMissing, xltypeMulti, xltypeNil, xltypeNum, xltypeStr,
14};
15
16use crate::{
17 ExcelError, PlannedArrayElement, PlannedText, PlannedValue, ReturnMaterializationError,
18 ReturnOwnershipStrategy, ReturnPlan, ReturnStorageTotals, ReturnText,
19};
20
21pub struct ExcelReturn {
54 allocation: Box<ReturnAllocation>,
55}
56
57impl ExcelReturn {
58 pub fn from_plan(plan: ReturnPlan) -> Result<Self, ReturnMaterializationError> {
63 Materializer::new().materialize(plan)
64 }
65
66 pub fn as_xloper(&self) -> &XLOPER12 {
68 &self.allocation.root
69 }
70
71 pub(crate) fn as_xloper_mut_for_callback(&mut self) -> &mut XLOPER12 {
73 &mut self.allocation.root
74 }
75
76 pub fn into_raw_for_excel(self) -> *mut XLOPER12 {
84 let mut allocation = self.allocation;
85 let original_type = allocation.root.xltype;
86 let base_type = original_type & XLTYPE_MASK;
87
88 debug_assert_eq!(original_type & xlbitDLLFree, 0);
91 debug_assert_eq!(original_type & xlbitXLFree, 0);
92 debug_assert_eq!(original_type, base_type);
93 debug_assert!(is_supported_root_type(base_type));
94
95 allocation.root.xltype = original_type | xlbitDLLFree;
96
97 #[cfg(test)]
98 HANDED_OFF_ROOTS.fetch_add(1, core::sync::atomic::Ordering::SeqCst);
99
100 let allocation_pointer = allocation.as_mut() as *mut ReturnAllocation;
101 let root_pointer = &mut allocation.root as *mut XLOPER12;
102 debug_assert_eq!(root_pointer.cast::<ReturnAllocation>(), allocation_pointer);
103
104 let _allocation_pointer = Box::into_raw(allocation);
105 root_pointer
106 }
107}
108
109const fn is_supported_root_type(xltype: u32) -> bool {
110 xltype == xltypeNum
111 || xltype == xltypeInt
112 || xltype == xltypeBool
113 || xltype == xltypeErr
114 || xltype == xltypeMissing
115 || xltype == xltypeNil
116 || xltype == xltypeStr
117 || xltype == xltypeMulti
118}
119
120pub unsafe extern "system" fn xl_auto_free12(pointer: *mut XLOPER12) {
137 if pointer.is_null() {
138 return;
139 }
140
141 #[cfg(test)]
142 contain_callback_panic(|| {
143 if PANIC_BEFORE_RECLAIM.swap(false, core::sync::atomic::Ordering::SeqCst) {
144 panic!("injected callback-boundary panic");
145 }
146 });
147
148 contain_callback_panic(|| {
149 unsafe { reclaim_excel_return(pointer) }
152 });
153}
154
155fn contain_callback_panic(action: impl FnOnce()) {
156 let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(action));
157}
158
159unsafe fn reclaim_excel_return(pointer: *mut XLOPER12) {
169 let allocation = pointer.cast::<ReturnAllocation>();
170 drop(unsafe { Box::from_raw(allocation) });
174
175 #[cfg(test)]
176 {
177 let previous = HANDED_OFF_ROOTS.fetch_sub(1, core::sync::atomic::Ordering::SeqCst);
178 assert!(previous > 0, "callback reclaimed a non-handed-off root");
179 CALLBACK_FREES.fetch_add(1, core::sync::atomic::Ordering::SeqCst);
180 }
181}
182
183impl ReturnPlan {
184 pub fn materialize(self) -> Result<ExcelReturn, ReturnMaterializationError> {
189 ExcelReturn::from_plan(self)
190 }
191}
192
193#[repr(C)]
196struct ReturnAllocation {
197 root: XLOPER12,
198 array_elements: Option<ReturnArrayBuffer>,
199 string_buffers: Box<[ReturnUtf16Buffer]>,
200 #[cfg(test)]
201 _tracker: RootTracker,
202}
203
204struct ReturnUtf16Buffer {
205 storage: Box<[XCHAR]>,
206}
207
208impl ReturnUtf16Buffer {
209 fn from_planned(text: PlannedText) -> Result<Self, ReturnMaterializationError> {
210 let PlannedText {
211 source,
212 payload_code_units,
213 storage_code_units,
214 } = text;
215
216 let mut storage = Vec::new();
217 storage.try_reserve_exact(storage_code_units).map_err(|_| {
218 ReturnMaterializationError::AllocationFailure {
219 storage: "counted UTF-16 string",
220 }
221 })?;
222 storage.push(0);
223
224 let utf8_source = matches!(&source, ReturnText::Utf8(_));
225 match source {
226 ReturnText::Utf8(value) => storage.extend(value.encode_utf16()),
227 ReturnText::Utf16(value) => storage.extend_from_slice(value.as_utf16()),
228 }
229
230 let actual_payload = storage.len() - 1;
231 if utf8_source && actual_payload != payload_code_units {
232 return Err(ReturnMaterializationError::Utf8EncodedLengthMismatch {
233 planned: payload_code_units,
234 actual: actual_payload,
235 });
236 }
237 if actual_payload != payload_code_units || storage.len() != storage_code_units {
238 return Err(ReturnMaterializationError::StringBufferLengthMismatch {
239 planned: storage_code_units,
240 actual: storage.len(),
241 });
242 }
243 let prefix = XCHAR::try_from(actual_payload).map_err(|_| {
244 ReturnMaterializationError::StringBufferLengthMismatch {
245 planned: storage_code_units,
246 actual: storage.len(),
247 }
248 })?;
249 storage[0] = prefix;
250
251 #[cfg(test)]
252 LIVE_STRING_BUFFERS.fetch_add(1, core::sync::atomic::Ordering::SeqCst);
253 Ok(Self {
254 storage: storage.into_boxed_slice(),
255 })
256 }
257
258 fn abi_ptr(&self) -> *mut XCHAR {
259 self.storage.as_ptr().cast_mut()
262 }
263
264 fn payload_units(&self) -> usize {
265 self.storage.len() - 1
266 }
267
268 fn storage_units(&self) -> usize {
269 self.storage.len()
270 }
271}
272
273#[cfg(test)]
274impl Drop for ReturnUtf16Buffer {
275 fn drop(&mut self) {
276 let previous = LIVE_STRING_BUFFERS.fetch_sub(1, core::sync::atomic::Ordering::SeqCst);
277 assert!(previous > 0, "return string buffer dropped more than once");
278 }
279}
280
281struct ReturnArrayBuffer {
282 storage: Box<[XLOPER12]>,
283}
284
285impl ReturnArrayBuffer {
286 fn allocate(elements: usize) -> Result<Self, ReturnMaterializationError> {
287 let mut storage = Vec::new();
288 storage.try_reserve_exact(elements).map_err(|_| {
289 ReturnMaterializationError::AllocationFailure {
290 storage: "XLOPER12 array elements",
291 }
292 })?;
293 storage.resize(elements, raw_empty());
294
295 #[cfg(test)]
296 LIVE_ARRAY_BUFFERS.fetch_add(1, core::sync::atomic::Ordering::SeqCst);
297 Ok(Self {
298 storage: storage.into_boxed_slice(),
299 })
300 }
301
302 fn abi_ptr(&self) -> *mut XLOPER12 {
303 self.storage.as_ptr().cast_mut()
306 }
307}
308
309#[cfg(test)]
310impl Drop for ReturnArrayBuffer {
311 fn drop(&mut self) {
312 let previous = LIVE_ARRAY_BUFFERS.fetch_sub(1, core::sync::atomic::Ordering::SeqCst);
313 assert!(previous > 0, "return array buffer dropped more than once");
314 }
315}
316
317#[derive(Clone, Debug)]
318enum RootBlueprint {
319 Number(f64),
320 Integer(i32),
321 Boolean(bool),
322 Error(ExcelError),
323 Missing,
324 Empty,
325 Text {
326 buffer: usize,
327 },
328 Array {
329 rows: usize,
330 columns: usize,
331 elements: Box<[ElementBlueprint]>,
332 },
333}
334
335#[derive(Clone, Debug)]
336enum ElementBlueprint {
337 Number(f64),
338 Integer(i32),
339 Boolean(bool),
340 Error(ExcelError),
341 Missing,
342 Empty,
343 Text { buffer: usize },
344}
345
346#[derive(Clone, Copy, Debug, Eq, PartialEq)]
347enum FailurePoint {
348 BeforeFirstString,
349 AfterStringAllocations(usize),
350 BeforeArrayAllocation,
351 AfterArrayAllocation,
352 DuringElementInitialization(usize),
353 BeforeRootCreation,
354}
355
356impl FailurePoint {
357 #[cfg(test)]
358 const fn label(self) -> &'static str {
359 match self {
360 Self::BeforeFirstString => "before first string allocation",
361 Self::AfterStringAllocations(_) => "after string allocation",
362 Self::BeforeArrayAllocation => "before array allocation",
363 Self::AfterArrayAllocation => "after array allocation",
364 Self::DuringElementInitialization(_) => "during array element initialization",
365 Self::BeforeRootCreation => "before final root creation",
366 }
367 }
368}
369
370struct Materializer {
371 #[cfg(test)]
372 failure: Option<FailurePoint>,
373 strings_allocated: usize,
374}
375
376impl Materializer {
377 fn new() -> Self {
378 Self {
379 #[cfg(test)]
380 failure: None,
381 strings_allocated: 0,
382 }
383 }
384
385 #[cfg(test)]
386 fn with_failure(failure: FailurePoint) -> Self {
387 Self {
388 failure: Some(failure),
389 strings_allocated: 0,
390 }
391 }
392
393 fn materialize(mut self, plan: ReturnPlan) -> Result<ExcelReturn, ReturnMaterializationError> {
394 let ReturnPlan {
395 root,
396 totals,
397 strategy,
398 } = plan;
399 if strategy != ReturnOwnershipStrategy::DllOwnedXloper12 {
400 return Err(ReturnMaterializationError::UnsupportedPlannedValue {
401 variant: "ownership strategy",
402 });
403 }
404
405 let text_count = count_texts(&root);
406 let mut strings = Vec::new();
407 strings.try_reserve_exact(text_count).map_err(|_| {
408 ReturnMaterializationError::AllocationFailure {
409 storage: "string-buffer owner table",
410 }
411 })?;
412 let blueprint = self.prepare_root(root, &mut strings)?;
413 let string_buffers = strings.into_boxed_slice();
414
415 let mut array_elements = self.materialize_array(&blueprint, &string_buffers)?;
416 verify_totals(&totals, &string_buffers, array_elements.as_ref())?;
417 self.fail_if(FailurePoint::BeforeRootCreation)?;
418
419 let root = raw_root(&blueprint, &string_buffers, array_elements.as_ref())?;
420 let allocation = ReturnAllocation {
421 root,
422 array_elements: array_elements.take(),
423 string_buffers,
424 #[cfg(test)]
425 _tracker: RootTracker::new(),
426 };
427 Ok(ExcelReturn {
428 allocation: Box::new(allocation),
429 })
430 }
431
432 fn prepare_root(
433 &mut self,
434 root: PlannedValue,
435 strings: &mut Vec<ReturnUtf16Buffer>,
436 ) -> Result<RootBlueprint, ReturnMaterializationError> {
437 Ok(match root {
438 PlannedValue::Number(value) => RootBlueprint::Number(value),
439 PlannedValue::Integer(value) => RootBlueprint::Integer(value),
440 PlannedValue::Boolean(value) => RootBlueprint::Boolean(value),
441 PlannedValue::Error(value) => RootBlueprint::Error(value),
442 PlannedValue::Missing => RootBlueprint::Missing,
443 PlannedValue::Empty => RootBlueprint::Empty,
444 PlannedValue::Text(text) => RootBlueprint::Text {
445 buffer: self.push_string(text, strings)?,
446 },
447 PlannedValue::Array(array) => {
448 let expected = array.rows.checked_mul(array.columns).ok_or(
449 ReturnMaterializationError::ArrayShapeMismatch {
450 rows: array.rows,
451 columns: array.columns,
452 elements: array.elements.len(),
453 },
454 )?;
455 if expected != array.elements.len() {
456 return Err(ReturnMaterializationError::ArrayShapeMismatch {
457 rows: array.rows,
458 columns: array.columns,
459 elements: array.elements.len(),
460 });
461 }
462 let mut elements = Vec::new();
463 elements.try_reserve_exact(expected).map_err(|_| {
464 ReturnMaterializationError::AllocationFailure {
465 storage: "array element blueprints",
466 }
467 })?;
468 for element in array.elements.into_vec() {
469 elements.push(self.prepare_element(element, strings)?);
470 }
471 RootBlueprint::Array {
472 rows: array.rows,
473 columns: array.columns,
474 elements: elements.into_boxed_slice(),
475 }
476 }
477 })
478 }
479
480 fn prepare_element(
481 &mut self,
482 element: PlannedArrayElement,
483 strings: &mut Vec<ReturnUtf16Buffer>,
484 ) -> Result<ElementBlueprint, ReturnMaterializationError> {
485 Ok(match element {
486 PlannedArrayElement::Number(value) => ElementBlueprint::Number(value),
487 PlannedArrayElement::Integer(value) => ElementBlueprint::Integer(value),
488 PlannedArrayElement::Boolean(value) => ElementBlueprint::Boolean(value),
489 PlannedArrayElement::Error(value) => ElementBlueprint::Error(value),
490 PlannedArrayElement::Missing => ElementBlueprint::Missing,
491 PlannedArrayElement::Empty => ElementBlueprint::Empty,
492 PlannedArrayElement::Text(text) => ElementBlueprint::Text {
493 buffer: self.push_string(text, strings)?,
494 },
495 })
496 }
497
498 fn push_string(
499 &mut self,
500 text: PlannedText,
501 strings: &mut Vec<ReturnUtf16Buffer>,
502 ) -> Result<usize, ReturnMaterializationError> {
503 if self.strings_allocated == 0 {
504 self.fail_if(FailurePoint::BeforeFirstString)?;
505 }
506 let buffer = ReturnUtf16Buffer::from_planned(text)?;
507 strings.push(buffer);
508 self.strings_allocated += 1;
509 self.fail_if(FailurePoint::AfterStringAllocations(self.strings_allocated))?;
510 Ok(strings.len() - 1)
511 }
512
513 fn materialize_array(
514 &self,
515 blueprint: &RootBlueprint,
516 strings: &[ReturnUtf16Buffer],
517 ) -> Result<Option<ReturnArrayBuffer>, ReturnMaterializationError> {
518 let RootBlueprint::Array { elements, .. } = blueprint else {
519 return Ok(None);
520 };
521 self.fail_if(FailurePoint::BeforeArrayAllocation)?;
522 let mut storage = ReturnArrayBuffer::allocate(elements.len())?;
523 self.fail_if(FailurePoint::AfterArrayAllocation)?;
524 for (index, (destination, element)) in
525 storage.storage.iter_mut().zip(elements.iter()).enumerate()
526 {
527 self.fail_if(FailurePoint::DuringElementInitialization(index))?;
528 *destination = raw_element(element, strings)?;
529 }
530 Ok(Some(storage))
531 }
532
533 fn fail_if(&self, point: FailurePoint) -> Result<(), ReturnMaterializationError> {
534 #[cfg(test)]
535 if self.failure == Some(point) {
536 return Err(ReturnMaterializationError::InjectedTestFailure {
537 stage: point.label(),
538 });
539 }
540 let _ = point;
541 Ok(())
542 }
543}
544
545fn count_texts(root: &PlannedValue) -> usize {
546 match root {
547 PlannedValue::Text(_) => 1,
548 PlannedValue::Array(array) => array
549 .elements
550 .iter()
551 .filter(|element| matches!(element, PlannedArrayElement::Text(_)))
552 .count(),
553 _ => 0,
554 }
555}
556
557fn verify_totals(
558 planned: &ReturnStorageTotals,
559 strings: &[ReturnUtf16Buffer],
560 array: Option<&ReturnArrayBuffer>,
561) -> Result<(), ReturnMaterializationError> {
562 let root_bytes = size_of::<XLOPER12>();
563 let array_element_bytes = array.map_or(0, |value| value.storage.len() * root_bytes);
564 let string_payload_code_units = strings.iter().map(ReturnUtf16Buffer::payload_units).sum();
565 let string_storage_code_units = strings.iter().map(ReturnUtf16Buffer::storage_units).sum();
566 let string_storage_bytes = string_storage_code_units * size_of::<XCHAR>();
567 let total_bytes = root_bytes + array_element_bytes + string_storage_bytes;
568 let allocation_count = 1 + usize::from(array.is_some()) + strings.len();
569
570 for (field, expected, actual) in [
571 ("root_bytes", planned.root_bytes, root_bytes),
572 (
573 "array_element_bytes",
574 planned.array_element_bytes,
575 array_element_bytes,
576 ),
577 (
578 "string_payload_code_units",
579 planned.string_payload_code_units,
580 string_payload_code_units,
581 ),
582 (
583 "string_storage_code_units",
584 planned.string_storage_code_units,
585 string_storage_code_units,
586 ),
587 (
588 "string_storage_bytes",
589 planned.string_storage_bytes,
590 string_storage_bytes,
591 ),
592 ("total_bytes", planned.total_bytes, total_bytes),
593 (
594 "allocation_count",
595 planned.allocation_count,
596 allocation_count,
597 ),
598 ] {
599 if expected != actual {
600 return Err(ReturnMaterializationError::PlanStorageInvariantMismatch {
601 field,
602 planned: expected,
603 actual,
604 });
605 }
606 }
607 Ok(())
608}
609
610fn raw_root(
611 blueprint: &RootBlueprint,
612 strings: &[ReturnUtf16Buffer],
613 array: Option<&ReturnArrayBuffer>,
614) -> Result<XLOPER12, ReturnMaterializationError> {
615 Ok(match blueprint {
616 RootBlueprint::Number(value) => raw_number(*value),
617 RootBlueprint::Integer(value) => raw_integer(*value),
618 RootBlueprint::Boolean(value) => raw_boolean(*value),
619 RootBlueprint::Error(value) => raw_error(*value),
620 RootBlueprint::Missing => raw_missing(),
621 RootBlueprint::Empty => raw_empty(),
622 RootBlueprint::Text { buffer } => {
623 let buffer = strings.get(*buffer).ok_or(
624 ReturnMaterializationError::UnsupportedPlannedValue {
625 variant: "missing root string buffer",
626 },
627 )?;
628 raw_text(buffer.abi_ptr())
629 }
630 RootBlueprint::Array {
631 rows,
632 columns,
633 elements,
634 } => {
635 let storage = array.ok_or(ReturnMaterializationError::UnsupportedPlannedValue {
636 variant: "missing array element buffer",
637 })?;
638 if storage.storage.len() != elements.len() {
639 return Err(ReturnMaterializationError::ArrayShapeMismatch {
640 rows: *rows,
641 columns: *columns,
642 elements: storage.storage.len(),
643 });
644 }
645 let planned_rows = *rows;
646 let planned_columns = *columns;
647 let rows = i32::try_from(planned_rows).map_err(|_| {
648 ReturnMaterializationError::ArrayShapeMismatch {
649 rows: planned_rows,
650 columns: planned_columns,
651 elements: elements.len(),
652 }
653 })?;
654 let columns = i32::try_from(planned_columns).map_err(|_| {
655 ReturnMaterializationError::ArrayShapeMismatch {
656 rows: planned_rows,
657 columns: planned_columns,
658 elements: elements.len(),
659 }
660 })?;
661 raw_array(storage.abi_ptr(), rows, columns)
662 }
663 })
664}
665
666fn raw_element(
667 element: &ElementBlueprint,
668 strings: &[ReturnUtf16Buffer],
669) -> Result<XLOPER12, ReturnMaterializationError> {
670 Ok(match element {
671 ElementBlueprint::Number(value) => raw_number(*value),
672 ElementBlueprint::Integer(value) => raw_integer(*value),
673 ElementBlueprint::Boolean(value) => raw_boolean(*value),
674 ElementBlueprint::Error(value) => raw_error(*value),
675 ElementBlueprint::Missing => raw_missing(),
676 ElementBlueprint::Empty => raw_empty(),
677 ElementBlueprint::Text { buffer } => {
678 let buffer = strings.get(*buffer).ok_or(
679 ReturnMaterializationError::UnsupportedPlannedValue {
680 variant: "missing array string buffer",
681 },
682 )?;
683 raw_text(buffer.abi_ptr())
684 }
685 })
686}
687
688fn zeroed_value() -> XLOPER12Value {
689 unsafe { core::mem::zeroed() }
694}
695
696fn raw_number(value: f64) -> XLOPER12 {
697 let mut raw = zeroed_value();
698 raw.num = value;
699 XLOPER12 {
700 val: raw,
701 xltype: xltypeNum,
702 }
703}
704
705fn raw_integer(value: i32) -> XLOPER12 {
706 let mut raw = zeroed_value();
707 raw.w = value;
708 XLOPER12 {
709 val: raw,
710 xltype: xltypeInt,
711 }
712}
713
714fn raw_boolean(value: bool) -> XLOPER12 {
715 let mut raw = zeroed_value();
716 raw.xbool = i32::from(value);
717 XLOPER12 {
718 val: raw,
719 xltype: xltypeBool,
720 }
721}
722
723fn raw_error(value: ExcelError) -> XLOPER12 {
724 let mut raw = zeroed_value();
725 raw.err = match value {
726 ExcelError::Null => excel_api_sys::xlerrNull,
727 ExcelError::Div0 => excel_api_sys::xlerrDiv0,
728 ExcelError::Value => excel_api_sys::xlerrValue,
729 ExcelError::Ref => excel_api_sys::xlerrRef,
730 ExcelError::Name => excel_api_sys::xlerrName,
731 ExcelError::Num => excel_api_sys::xlerrNum,
732 ExcelError::Na => excel_api_sys::xlerrNA,
733 ExcelError::GettingData => excel_api_sys::xlerrGettingData,
734 };
735 XLOPER12 {
736 val: raw,
737 xltype: xltypeErr,
738 }
739}
740
741fn raw_missing() -> XLOPER12 {
742 XLOPER12 {
743 val: zeroed_value(),
744 xltype: xltypeMissing,
745 }
746}
747
748fn raw_empty() -> XLOPER12 {
749 XLOPER12 {
750 val: zeroed_value(),
751 xltype: xltypeNil,
752 }
753}
754
755fn raw_text(pointer: *mut XCHAR) -> XLOPER12 {
756 let mut raw = zeroed_value();
757 raw.str = pointer;
758 XLOPER12 {
759 val: raw,
760 xltype: xltypeStr,
761 }
762}
763
764fn raw_array(pointer: *mut XLOPER12, rows: i32, columns: i32) -> XLOPER12 {
765 let mut raw = zeroed_value();
766 raw.array = XLOPER12Array {
767 lparray: pointer,
768 rows,
769 columns,
770 };
771 XLOPER12 {
772 val: raw,
773 xltype: xltypeMulti,
774 }
775}
776
777#[cfg(test)]
778use core::sync::atomic::AtomicUsize;
779
780#[cfg(test)]
781static LIVE_ROOTS: AtomicUsize = AtomicUsize::new(0);
782#[cfg(test)]
783static LIVE_STRING_BUFFERS: AtomicUsize = AtomicUsize::new(0);
784#[cfg(test)]
785static LIVE_ARRAY_BUFFERS: AtomicUsize = AtomicUsize::new(0);
786#[cfg(test)]
787static HANDED_OFF_ROOTS: AtomicUsize = AtomicUsize::new(0);
788#[cfg(test)]
789static CALLBACK_FREES: AtomicUsize = AtomicUsize::new(0);
790#[cfg(test)]
791static PANIC_BEFORE_RECLAIM: core::sync::atomic::AtomicBool =
792 core::sync::atomic::AtomicBool::new(false);
793
794#[cfg(test)]
795struct RootTracker;
796
797#[cfg(test)]
798impl RootTracker {
799 fn new() -> Self {
800 LIVE_ROOTS.fetch_add(1, core::sync::atomic::Ordering::SeqCst);
801 Self
802 }
803}
804
805#[cfg(test)]
806impl Drop for RootTracker {
807 fn drop(&mut self) {
808 let previous = LIVE_ROOTS.fetch_sub(1, core::sync::atomic::Ordering::SeqCst);
809 assert!(previous > 0, "return root dropped more than once");
810 }
811}
812
813#[cfg(test)]
814mod tests {
815 use core::{mem::offset_of, slice};
816 use std::sync::{Mutex, MutexGuard};
817
818 use excel_api_sys::{xlbitDLLFree, xlbitXLFree};
819
820 use super::*;
821 use crate::{ExcelReturnArray, ExcelReturnValue, ExcelString, ReturnText};
822
823 static TEST_LOCK: Mutex<()> = Mutex::new(());
824
825 fn lock() -> MutexGuard<'static, ()> {
826 TEST_LOCK.lock().unwrap_or_else(|error| error.into_inner())
827 }
828
829 fn live_counts() -> (usize, usize, usize) {
830 use core::sync::atomic::Ordering;
831
832 (
833 LIVE_ROOTS.load(Ordering::SeqCst),
834 LIVE_STRING_BUFFERS.load(Ordering::SeqCst),
835 LIVE_ARRAY_BUFFERS.load(Ordering::SeqCst),
836 )
837 }
838
839 fn handoff_counts() -> (usize, usize) {
840 use core::sync::atomic::Ordering;
841
842 (
843 HANDED_OFF_ROOTS.load(Ordering::SeqCst),
844 CALLBACK_FREES.load(Ordering::SeqCst),
845 )
846 }
847
848 fn assert_no_live_or_handed_off_allocations() {
849 assert_eq!(live_counts(), (0, 0, 0));
850 assert_eq!(handoff_counts().0, 0);
851 }
852
853 fn assert_no_ownership_bits(value: &XLOPER12) {
854 assert_eq!(value.xltype & (xlbitDLLFree | xlbitXLFree), 0);
855 }
856
857 fn number(value: &XLOPER12) -> f64 {
858 assert_eq!(value.xltype, xltypeNum);
859 unsafe { value.val.num }
862 }
863
864 fn integer(value: &XLOPER12) -> i32 {
865 assert_eq!(value.xltype, xltypeInt);
866 unsafe { value.val.w }
869 }
870
871 fn boolean(value: &XLOPER12) -> i32 {
872 assert_eq!(value.xltype, xltypeBool);
873 unsafe { value.val.xbool }
876 }
877
878 fn error_code(value: &XLOPER12) -> i32 {
879 assert_eq!(value.xltype, xltypeErr);
880 unsafe { value.val.err }
883 }
884
885 fn counted_storage<'owner>(_owner: &'owner ExcelReturn, value: &XLOPER12) -> &'owner [XCHAR] {
886 assert_eq!(value.xltype, xltypeStr);
887 unsafe {
892 let pointer = value.val.str;
893 let payload = usize::from(pointer.read());
894 slice::from_raw_parts(pointer, payload + 1)
895 }
896 }
897
898 fn array_elements(owner: &ExcelReturn) -> &[XLOPER12] {
899 let root = owner.as_xloper();
900 assert_eq!(root.xltype, xltypeMulti);
901 unsafe {
905 let array = root.val.array;
906 let count =
907 usize::try_from(array.rows).unwrap() * usize::try_from(array.columns).unwrap();
908 slice::from_raw_parts(array.lparray, count)
909 }
910 }
911
912 fn array_pointer(value: &XLOPER12) -> *mut XLOPER12 {
913 assert_eq!(value.xltype, xltypeMulti);
914 unsafe { value.val.array.lparray }
917 }
918
919 fn string_pointer(value: &XLOPER12) -> *mut XCHAR {
920 assert_eq!(value.xltype, xltypeStr);
921 unsafe { value.val.str }
924 }
925
926 fn string_pointer_with_flags(value: &XLOPER12) -> *mut XCHAR {
927 assert_eq!(value.xltype & XLTYPE_MASK, xltypeStr);
928 unsafe { value.val.str }
931 }
932
933 fn array_pointer_with_flags(value: &XLOPER12) -> *mut XLOPER12 {
934 assert_eq!(value.xltype & XLTYPE_MASK, xltypeMulti);
935 unsafe { value.val.array.lparray }
938 }
939
940 unsafe fn raw_counted_storage(value: &XLOPER12) -> &[XCHAR] {
941 assert_eq!(value.xltype & XLTYPE_MASK, xltypeStr);
942 unsafe {
946 let pointer = value.val.str;
947 let payload = usize::from(pointer.read());
948 slice::from_raw_parts(pointer, payload + 1)
949 }
950 }
951
952 unsafe fn raw_array_elements(value: &XLOPER12) -> &[XLOPER12] {
953 assert_eq!(value.xltype & XLTYPE_MASK, xltypeMulti);
954 unsafe {
958 let array = value.val.array;
959 let count =
960 usize::try_from(array.rows).unwrap() * usize::try_from(array.columns).unwrap();
961 slice::from_raw_parts(array.lparray, count)
962 }
963 }
964
965 fn handoff_and_reclaim(returned: ExcelReturn) {
966 let base_type = returned.as_xloper().xltype;
967 let root_address = returned.as_xloper() as *const XLOPER12 as *mut XLOPER12;
968 let callback_frees_before = handoff_counts().1;
969
970 let pointer = returned.into_raw_for_excel();
971 assert_eq!(pointer, root_address);
972 let root = unsafe { &*pointer };
975 assert_eq!(root.xltype & XLTYPE_MASK, base_type);
976 assert_ne!(root.xltype & xlbitDLLFree, 0);
977 assert_eq!(root.xltype & xlbitXLFree, 0);
978 assert_eq!(handoff_counts(), (1, callback_frees_before));
979
980 unsafe { xl_auto_free12(pointer) };
983 assert_no_live_or_handed_off_allocations();
984 assert_eq!(handoff_counts().1, callback_frees_before + 1);
985 }
986
987 fn move_return(value: ExcelReturn) -> ExcelReturn {
988 value
989 }
990
991 fn materialize(value: ExcelReturnValue) -> ExcelReturn {
992 value.plan().unwrap().materialize().unwrap()
993 }
994
995 fn mixed_array_plan() -> ReturnPlan {
996 ExcelReturnValue::Array(
997 ExcelReturnArray::new(
998 2,
999 4,
1000 vec![
1001 ExcelReturnValue::Number(1.5),
1002 ExcelReturnValue::Integer(-2),
1003 ExcelReturnValue::Boolean(true),
1004 ExcelReturnValue::Error(ExcelError::Ref),
1005 ExcelReturnValue::Missing,
1006 ExcelReturnValue::Empty,
1007 ExcelReturnValue::Text(ReturnText::from("A\0B")),
1008 ExcelReturnValue::Text(ReturnText::Utf16(ExcelString::from_utf16_units([
1009 0xD800,
1010 ]))),
1011 ],
1012 )
1013 .unwrap(),
1014 )
1015 .plan()
1016 .unwrap()
1017 }
1018
1019 #[test]
1020 fn root_is_offset_zero_and_scalars_use_exact_sdk_members() {
1021 let _guard = lock();
1022 assert_eq!(offset_of!(ReturnAllocation, root), 0);
1023
1024 let returned = materialize(ExcelReturnValue::Number(2.5));
1025 assert_eq!(
1026 returned.as_xloper() as *const XLOPER12,
1027 returned.allocation.as_ref() as *const ReturnAllocation as *const XLOPER12
1028 );
1029 assert_eq!(number(returned.as_xloper()), 2.5);
1030 assert_no_ownership_bits(returned.as_xloper());
1031 drop(returned);
1032
1033 let returned = materialize(ExcelReturnValue::Integer(-42));
1034 assert_eq!(integer(returned.as_xloper()), -42);
1035 assert_no_ownership_bits(returned.as_xloper());
1036 drop(returned);
1037
1038 for (input, expected) in [(false, 0), (true, 1)] {
1039 let returned = materialize(ExcelReturnValue::Boolean(input));
1040 assert_eq!(boolean(returned.as_xloper()), expected);
1041 assert_no_ownership_bits(returned.as_xloper());
1042 }
1043
1044 let missing = materialize(ExcelReturnValue::Missing);
1045 assert_eq!(missing.as_xloper().xltype, xltypeMissing);
1046 assert_no_ownership_bits(missing.as_xloper());
1047 let empty = materialize(ExcelReturnValue::Empty);
1048 assert_eq!(empty.as_xloper().xltype, xltypeNil);
1049 assert_no_ownership_bits(empty.as_xloper());
1050 drop((missing, empty));
1051 assert_eq!(live_counts(), (0, 0, 0));
1052 }
1053
1054 #[test]
1055 fn every_excel_error_uses_the_exact_sdk_code() {
1056 let _guard = lock();
1057 for (error, expected) in [
1058 (ExcelError::Null, excel_api_sys::xlerrNull),
1059 (ExcelError::Div0, excel_api_sys::xlerrDiv0),
1060 (ExcelError::Value, excel_api_sys::xlerrValue),
1061 (ExcelError::Ref, excel_api_sys::xlerrRef),
1062 (ExcelError::Name, excel_api_sys::xlerrName),
1063 (ExcelError::Num, excel_api_sys::xlerrNum),
1064 (ExcelError::Na, excel_api_sys::xlerrNA),
1065 (ExcelError::GettingData, excel_api_sys::xlerrGettingData),
1066 ] {
1067 let returned = materialize(ExcelReturnValue::Error(error));
1068 assert_eq!(error_code(returned.as_xloper()), expected);
1069 assert_no_ownership_bits(returned.as_xloper());
1070 }
1071 assert_eq!(live_counts(), (0, 0, 0));
1072 }
1073
1074 #[test]
1075 fn counted_strings_preserve_every_utf16_form_without_terminator() {
1076 let _guard = lock();
1077 let cases: Vec<ReturnText> = vec![
1078 ReturnText::from(""),
1079 ReturnText::from("ASCII"),
1080 ReturnText::from("é水"),
1081 ReturnText::from("😃"),
1082 ReturnText::Utf16(ExcelString::from_utf16_units([0xD83D, 0xDE03])),
1083 ReturnText::Utf16(ExcelString::from_utf16_units([0xD800])),
1084 ReturnText::Utf16(ExcelString::from_utf16_units([0xDC00])),
1085 ReturnText::Utf16(ExcelString::from_utf16_units([b'A' as u16, 0, b'B' as u16])),
1086 ];
1087
1088 for source in cases {
1089 let expected: Vec<u16> = match &source {
1090 ReturnText::Utf8(value) => value.encode_utf16().collect(),
1091 ReturnText::Utf16(value) => value.as_utf16().to_vec(),
1092 };
1093 let returned = materialize(ExcelReturnValue::Text(source));
1094 let storage = counted_storage(&returned, returned.as_xloper());
1095 assert_eq!(
1096 string_pointer(returned.as_xloper()),
1097 returned.allocation.string_buffers[0]
1098 .storage
1099 .as_ptr()
1100 .cast_mut()
1101 );
1102 assert_eq!(usize::from(storage[0]), expected.len());
1103 assert_eq!(&storage[1..], expected);
1104 assert_eq!(
1105 returned.allocation.string_buffers[0].storage.len(),
1106 expected.len() + 1
1107 );
1108 assert_no_ownership_bits(returned.as_xloper());
1109 }
1110 assert_eq!(live_counts(), (0, 0, 0));
1111 }
1112
1113 #[test]
1114 fn maximum_counted_string_uses_exact_prefix_and_payload() {
1115 let _guard = lock();
1116 let maximum = excel_api_sys::EXCEL12_MAX_STRING_CODE_UNITS;
1117 let payload = vec![0xD800; maximum];
1118 let returned = materialize(ExcelReturnValue::Text(ReturnText::Utf16(
1119 ExcelString::from_utf16_units(payload.clone()),
1120 )));
1121 let storage = counted_storage(&returned, returned.as_xloper());
1122 assert_eq!(usize::from(storage[0]), maximum);
1123 assert_eq!(&storage[1..], payload);
1124 assert_eq!(storage.len(), maximum + 1);
1125 drop(returned);
1126 assert_eq!(live_counts(), (0, 0, 0));
1127 }
1128
1129 #[test]
1130 fn arrays_are_one_stable_row_major_block_with_deep_strings() {
1131 let _guard = lock();
1132 let returned = mixed_array_plan().materialize().unwrap();
1133 let root = returned.as_xloper();
1134 assert_no_ownership_bits(root);
1135 let raw_array = unsafe { root.val.array };
1137 assert_eq!((raw_array.rows, raw_array.columns), (2, 4));
1138
1139 let elements = array_elements(&returned);
1140 assert_eq!(elements.as_ptr(), raw_array.lparray);
1141 assert_eq!(number(&elements[0]), 1.5);
1142 assert_eq!(integer(&elements[1]), -2);
1143 assert_eq!(boolean(&elements[2]), 1);
1144 assert_eq!(error_code(&elements[3]), excel_api_sys::xlerrRef);
1145 assert_eq!(elements[4].xltype, xltypeMissing);
1146 assert_eq!(elements[5].xltype, xltypeNil);
1147 assert_eq!(&counted_storage(&returned, &elements[6])[1..], &[65, 0, 66]);
1148 assert_eq!(&counted_storage(&returned, &elements[7])[1..], &[0xD800]);
1149 assert_eq!(
1150 string_pointer(&elements[6]),
1151 returned.allocation.string_buffers[0]
1152 .storage
1153 .as_ptr()
1154 .cast_mut()
1155 );
1156 assert_eq!(
1157 string_pointer(&elements[7]),
1158 returned.allocation.string_buffers[1]
1159 .storage
1160 .as_ptr()
1161 .cast_mut()
1162 );
1163 for element in elements {
1164 assert_no_ownership_bits(element);
1165 }
1166 assert_eq!(
1167 returned
1168 .allocation
1169 .array_elements
1170 .as_ref()
1171 .unwrap()
1172 .storage
1173 .len(),
1174 8
1175 );
1176 assert_eq!(returned.allocation.string_buffers.len(), 2);
1177 drop(returned);
1178 assert_eq!(live_counts(), (0, 0, 0));
1179 }
1180
1181 #[test]
1182 fn one_by_one_array_and_empty_nested_text_are_supported() {
1183 let _guard = lock();
1184 let plan = ExcelReturnValue::Array(
1185 ExcelReturnArray::new(1, 1, vec![ExcelReturnValue::Text(ReturnText::from(""))])
1186 .unwrap(),
1187 )
1188 .plan()
1189 .unwrap();
1190 let returned = plan.materialize().unwrap();
1191 let elements = array_elements(&returned);
1192 assert_eq!(elements.len(), 1);
1193 assert_eq!(counted_storage(&returned, &elements[0]), &[0]);
1194 drop(returned);
1195 assert_eq!(live_counts(), (0, 0, 0));
1196 }
1197
1198 #[test]
1199 fn moving_excel_return_preserves_every_published_address() {
1200 let _guard = lock();
1201 let returned = mixed_array_plan().materialize().unwrap();
1202 let root_address = returned.as_xloper() as *const XLOPER12;
1203 let element_address = array_pointer(returned.as_xloper());
1204 let elements = array_elements(&returned);
1205 let string_address = string_pointer(&elements[6]);
1206
1207 let returned = move_return(returned);
1208 assert_eq!(returned.as_xloper() as *const XLOPER12, root_address);
1209 assert_eq!(array_pointer(returned.as_xloper()), element_address);
1210 assert_eq!(array_elements(&returned).as_ptr(), element_address);
1211 assert_eq!(
1212 string_pointer(&array_elements(&returned)[6]),
1213 string_address
1214 );
1215 drop(returned);
1216 assert_eq!(live_counts(), (0, 0, 0));
1217 }
1218
1219 #[test]
1220 fn materialization_verifies_every_planned_storage_total() {
1221 let _guard = lock();
1222 let plan = mixed_array_plan();
1223 let totals = plan.totals;
1224 let returned = plan.materialize().unwrap();
1225 let allocation = &returned.allocation;
1226 assert_eq!(totals.root_bytes, size_of::<XLOPER12>());
1227 assert_eq!(
1228 totals.array_element_bytes,
1229 allocation.array_elements.as_ref().unwrap().storage.len() * size_of::<XLOPER12>()
1230 );
1231 assert_eq!(
1232 totals.string_payload_code_units,
1233 allocation
1234 .string_buffers
1235 .iter()
1236 .map(ReturnUtf16Buffer::payload_units)
1237 .sum()
1238 );
1239 assert_eq!(
1240 totals.string_storage_code_units,
1241 allocation
1242 .string_buffers
1243 .iter()
1244 .map(ReturnUtf16Buffer::storage_units)
1245 .sum()
1246 );
1247 assert_eq!(
1248 totals.string_storage_bytes,
1249 totals.string_storage_code_units * size_of::<XCHAR>()
1250 );
1251 assert_eq!(
1252 totals.total_bytes,
1253 totals.root_bytes + totals.array_element_bytes + totals.string_storage_bytes
1254 );
1255 assert_eq!(totals.allocation_count, 4);
1256 drop(returned);
1257 assert_eq!(live_counts(), (0, 0, 0));
1258
1259 let mut corrupted = mixed_array_plan();
1260 corrupted.totals.root_bytes += 1;
1261 assert!(matches!(
1262 corrupted.materialize(),
1263 Err(ReturnMaterializationError::PlanStorageInvariantMismatch {
1264 field: "root_bytes",
1265 ..
1266 })
1267 ));
1268 assert_eq!(live_counts(), (0, 0, 0));
1269 }
1270
1271 #[test]
1272 fn corrupted_text_and_array_plans_fail_before_publication() {
1273 let _guard = lock();
1274 let mut utf8 = ExcelReturnValue::from("abc").plan().unwrap();
1275 let PlannedValue::Text(text) = &mut utf8.root else {
1276 panic!("expected text");
1277 };
1278 text.payload_code_units += 1;
1279 assert!(matches!(
1280 utf8.materialize(),
1281 Err(ReturnMaterializationError::Utf8EncodedLengthMismatch { .. })
1282 ));
1283
1284 let mut utf16 =
1285 ExcelReturnValue::Text(ReturnText::Utf16(ExcelString::from_utf16_units([0xD800])))
1286 .plan()
1287 .unwrap();
1288 let PlannedValue::Text(text) = &mut utf16.root else {
1289 panic!("expected text");
1290 };
1291 text.storage_code_units += 1;
1292 assert!(matches!(
1293 utf16.materialize(),
1294 Err(ReturnMaterializationError::StringBufferLengthMismatch { .. })
1295 ));
1296
1297 let mut array = ExcelReturnValue::Array(
1298 ExcelReturnArray::new(1, 1, vec![ExcelReturnValue::Empty]).unwrap(),
1299 )
1300 .plan()
1301 .unwrap();
1302 let PlannedValue::Array(planned_array) = &mut array.root else {
1303 panic!("expected array");
1304 };
1305 planned_array.rows = 2;
1306 assert!(matches!(
1307 array.materialize(),
1308 Err(ReturnMaterializationError::ArrayShapeMismatch { .. })
1309 ));
1310 assert_eq!(live_counts(), (0, 0, 0));
1311 }
1312
1313 #[test]
1314 fn every_injected_failure_releases_partial_storage() {
1315 let _guard = lock();
1316 for point in [
1317 FailurePoint::BeforeFirstString,
1318 FailurePoint::AfterStringAllocations(1),
1319 FailurePoint::AfterStringAllocations(2),
1320 FailurePoint::BeforeArrayAllocation,
1321 FailurePoint::AfterArrayAllocation,
1322 FailurePoint::DuringElementInitialization(0),
1323 FailurePoint::DuringElementInitialization(4),
1324 FailurePoint::BeforeRootCreation,
1325 ] {
1326 assert_eq!(live_counts(), (0, 0, 0));
1327 let result = Materializer::with_failure(point).materialize(mixed_array_plan());
1328 assert!(matches!(
1329 result,
1330 Err(ReturnMaterializationError::InjectedTestFailure { .. })
1331 ));
1332 assert_eq!(live_counts(), (0, 0, 0), "failed at {point:?}");
1333 }
1334 }
1335
1336 #[test]
1337 fn local_drop_and_repeated_construction_release_exactly_once() {
1338 let _guard = lock();
1339 let callback_frees_before = handoff_counts().1;
1340 let returned = mixed_array_plan().materialize().unwrap();
1341 assert_eq!(live_counts(), (1, 2, 1));
1342 drop(returned);
1343 assert_eq!(live_counts(), (0, 0, 0));
1344
1345 for _ in 0..1_000 {
1346 let returned = mixed_array_plan().materialize().unwrap();
1347 assert_eq!(live_counts(), (1, 2, 1));
1348 drop(returned);
1349 assert_eq!(live_counts(), (0, 0, 0));
1350 }
1351 assert_eq!(handoff_counts().0, 0);
1352 assert_eq!(handoff_counts().1, callback_frees_before);
1353 }
1354
1355 #[test]
1356 fn panic_before_handoff_keeps_raii_cleanup_local() {
1357 let _guard = lock();
1358 let callback_frees_before = handoff_counts().1;
1359 let result = std::panic::catch_unwind(|| {
1360 let _returned = mixed_array_plan().materialize().unwrap();
1361 panic!("injected panic before handoff");
1362 });
1363 assert!(result.is_err());
1364 assert_no_live_or_handed_off_allocations();
1365 assert_eq!(handoff_counts().1, callback_frees_before);
1366 }
1367
1368 #[test]
1369 fn handoff_and_callback_cover_every_scalar_root_and_error() {
1370 let _guard = lock();
1371 let callback_frees_before = handoff_counts().1;
1372 let mut values = vec![
1373 ExcelReturnValue::Number(2.5),
1374 ExcelReturnValue::Integer(-42),
1375 ExcelReturnValue::Boolean(false),
1376 ExcelReturnValue::Boolean(true),
1377 ExcelReturnValue::Missing,
1378 ExcelReturnValue::Empty,
1379 ];
1380 values.extend(
1381 [
1382 ExcelError::Null,
1383 ExcelError::Div0,
1384 ExcelError::Value,
1385 ExcelError::Ref,
1386 ExcelError::Name,
1387 ExcelError::Num,
1388 ExcelError::Na,
1389 ExcelError::GettingData,
1390 ]
1391 .map(ExcelReturnValue::Error),
1392 );
1393
1394 for value in values {
1395 handoff_and_reclaim(materialize(value));
1396 }
1397 assert_eq!(handoff_counts().1, callback_frees_before + 14);
1398 }
1399
1400 #[test]
1401 fn handoff_preserves_counted_string_pointers_and_arbitrary_utf16() {
1402 let _guard = lock();
1403 let maximum = excel_api_sys::EXCEL12_MAX_STRING_CODE_UNITS;
1404 for payload in [
1405 vec![b'A' as u16, 0, b'B' as u16],
1406 vec![0xD800, 0xDC00],
1407 vec![0xD800],
1408 vec![0xDC00],
1409 vec![0xD800; maximum],
1410 ] {
1411 let returned = materialize(ExcelReturnValue::Text(ReturnText::Utf16(
1412 ExcelString::from_utf16_units(payload.clone()),
1413 )));
1414 let root_address = returned.as_xloper() as *const XLOPER12 as *mut XLOPER12;
1415 let string_address = string_pointer(returned.as_xloper());
1416 let callback_frees_before = handoff_counts().1;
1417
1418 let pointer = returned.into_raw_for_excel();
1419 assert_eq!(pointer, root_address);
1420 let root = unsafe { &*pointer };
1423 assert_eq!(root.xltype & XLTYPE_MASK, xltypeStr);
1424 assert_ne!(root.xltype & xlbitDLLFree, 0);
1425 assert_eq!(root.xltype & xlbitXLFree, 0);
1426 let storage = unsafe { raw_counted_storage(root) };
1428 assert_eq!(string_pointer_with_flags(root), string_address);
1429 assert_eq!(usize::from(storage[0]), payload.len());
1430 assert_eq!(&storage[1..], payload);
1431
1432 unsafe { xl_auto_free12(pointer) };
1434 assert_no_live_or_handed_off_allocations();
1435 assert_eq!(handoff_counts().1, callback_frees_before + 1);
1436 }
1437 }
1438
1439 #[test]
1440 fn handoff_preserves_multi_storage_and_marks_only_the_root() {
1441 let _guard = lock();
1442 let returned = mixed_array_plan().materialize().unwrap();
1443 let root_address = returned.as_xloper() as *const XLOPER12 as *mut XLOPER12;
1444 let element_address = array_pointer(returned.as_xloper());
1445 let nested_string_addresses = {
1446 let elements = array_elements(&returned);
1447 [string_pointer(&elements[6]), string_pointer(&elements[7])]
1448 };
1449 let callback_frees_before = handoff_counts().1;
1450
1451 let pointer = move_return(returned).into_raw_for_excel();
1452 assert_eq!(pointer, root_address);
1453 let root = unsafe { &*pointer };
1455 assert_eq!(root.xltype & XLTYPE_MASK, xltypeMulti);
1456 assert_ne!(root.xltype & xlbitDLLFree, 0);
1457 assert_eq!(root.xltype & xlbitXLFree, 0);
1458 assert_eq!(array_pointer_with_flags(root), element_address);
1459 let elements = unsafe { raw_array_elements(root) };
1461 assert_eq!(elements.as_ptr(), element_address);
1462 assert_eq!(elements.len(), 8);
1463 assert_eq!(number(&elements[0]), 1.5);
1464 assert_eq!(integer(&elements[1]), -2);
1465 assert_eq!(boolean(&elements[2]), 1);
1466 assert_eq!(error_code(&elements[3]), excel_api_sys::xlerrRef);
1467 assert_eq!(elements[4].xltype, xltypeMissing);
1468 assert_eq!(elements[5].xltype, xltypeNil);
1469 assert_eq!(string_pointer(&elements[6]), nested_string_addresses[0]);
1470 assert_eq!(string_pointer(&elements[7]), nested_string_addresses[1]);
1471 let first_nested_string = unsafe { raw_counted_storage(&elements[6]) };
1473 let second_nested_string = unsafe { raw_counted_storage(&elements[7]) };
1475 assert_eq!(first_nested_string, &[3, 65, 0, 66]);
1476 assert_eq!(second_nested_string, &[1, 0xD800]);
1477 for element in elements {
1478 assert_no_ownership_bits(element);
1479 }
1480
1481 unsafe { xl_auto_free12(pointer) };
1483 assert_no_live_or_handed_off_allocations();
1484 assert_eq!(handoff_counts().1, callback_frees_before + 1);
1485 }
1486
1487 #[test]
1488 fn repeated_handoff_callback_cycles_reclaim_exactly_once() {
1489 let _guard = lock();
1490 let callback_frees_before = handoff_counts().1;
1491 for _ in 0..1_000 {
1492 handoff_and_reclaim(mixed_array_plan().materialize().unwrap());
1493 }
1494 assert_eq!(handoff_counts().1, callback_frees_before + 1_000);
1495 }
1496
1497 #[test]
1498 fn callback_is_null_tolerant_and_abi_exact() {
1499 let _guard = lock();
1500 let callback: excel_api_sys::XlAutoFree12Fn = xl_auto_free12;
1501 let before = handoff_counts();
1502 unsafe { callback(core::ptr::null_mut()) };
1504 assert_eq!(handoff_counts(), before);
1505 assert_no_live_or_handed_off_allocations();
1506 }
1507
1508 #[test]
1509 fn callback_contains_test_panic_and_still_reclaims_valid_handoff() {
1510 let _guard = lock();
1511 let callback_frees_before = handoff_counts().1;
1512 let pointer = materialize(ExcelReturnValue::from("panic-safe")).into_raw_for_excel();
1513 PANIC_BEFORE_RECLAIM.store(true, core::sync::atomic::Ordering::SeqCst);
1514
1515 let result = std::panic::catch_unwind(|| {
1516 unsafe { xl_auto_free12(pointer) };
1518 });
1519 assert!(result.is_ok(), "panic escaped the extern callback boundary");
1520 assert_no_live_or_handed_off_allocations();
1521 assert_eq!(handoff_counts().1, callback_frees_before + 1);
1522 }
1523
1524 #[test]
1525 fn handed_off_allocation_can_be_reclaimed_on_another_thread() {
1526 let _guard = lock();
1527 let callback_frees_before = handoff_counts().1;
1528 let pointer = mixed_array_plan()
1529 .materialize()
1530 .unwrap()
1531 .into_raw_for_excel();
1532 let address = pointer as usize;
1533
1534 std::thread::spawn(move || {
1535 let pointer = address as *mut XLOPER12;
1536 unsafe { xl_auto_free12(pointer) };
1539 })
1540 .join()
1541 .unwrap();
1542
1543 assert_no_live_or_handed_off_allocations();
1544 assert_eq!(handoff_counts().1, callback_frees_before + 1);
1545 }
1546}