Skip to main content

excel_api/
return_alloc.rs

1//! Stable Excel return storage and its consuming handoff to Excel.
2//!
3//! Materialization creates a locally owned ABI tree with base type bits only.
4//! [`ExcelReturn::into_raw_for_excel`] consumes that local owner, marks only
5//! the root with `xlbitDLLFree`, and transfers the allocation to Excel. The
6//! matching [`xl_auto_free12`] callback reconstructs and drops the exact
7//! root-first Rust allocation.
8
9use 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
21/// Opaque local owner of one stable Excel ABI return tree.
22///
23/// Dropping this value while it is local releases the root and every nested
24/// backing allocation through ordinary Rust field drops. Consuming handoff
25/// leaves no Rust owner behind; Excel must then invoke the matching callback
26/// exactly once.
27///
28/// The root is deliberately read-only:
29///
30/// ```compile_fail
31/// use excel_api::ExcelReturn;
32/// fn cannot_mutate(mut value: ExcelReturn) {
33///     value.as_xloper().xltype = 0;
34/// }
35/// ```
36///
37/// Handoff consumes the owner, so safe code cannot hand it off twice:
38///
39/// ```compile_fail
40/// fn cannot_handoff_twice(value: excel_api::ExcelReturn) {
41///     let _first = value.into_raw_for_excel();
42///     let _second = value.into_raw_for_excel();
43/// }
44/// ```
45///
46/// Raw reclamation is not a safe ownership constructor:
47///
48/// ```compile_fail
49/// fn cannot_reclaim_safely(pointer: *mut excel_api_sys::XLOPER12) {
50///     excel_api::xl_auto_free12(pointer);
51/// }
52/// ```
53pub struct ExcelReturn {
54    allocation: Box<ReturnAllocation>,
55}
56
57impl ExcelReturn {
58    /// Materializes pointer-free planning data into one locally owned ABI tree.
59    ///
60    /// The result is still Rust-owned until [`Self::into_raw_for_excel`]
61    /// consumes it; this does not create an Excel-owned `xlFree` result.
62    pub fn from_plan(plan: ReturnPlan) -> Result<Self, ReturnMaterializationError> {
63        Materializer::new().materialize(plan)
64    }
65
66    /// Read-only access to the stable root for inspection and future handoff.
67    pub fn as_xloper(&self) -> &XLOPER12 {
68        &self.allocation.root
69    }
70
71    /// Mutable root access confined to a synchronous `xlAsyncReturn` call.
72    pub(crate) fn as_xloper_mut_for_callback(&mut self) -> &mut XLOPER12 {
73        &mut self.allocation.root
74    }
75
76    /// Consumes this local owner and transfers its complete allocation to Excel.
77    ///
78    /// The returned pointer is the root at byte offset zero of the same
79    /// `ReturnAllocation`; it is not a copy. Only the root receives
80    /// `xlbitDLLFree`. Every nested value retains base type bits only and its
81    /// storage remains owned by the leaked top-level allocation until the
82    /// matching [`xl_auto_free12`] call.
83    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        // Prompt 05 materialization establishes these invariants. Keep every
89        // potentially panicking check while the Box still has a local owner.
90        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
120/// Reusable implementation of the Excel 12 DLL-owned return cleanup callback.
121///
122/// A final XLL should export an exact `xlAutoFree12` symbol with the SDK's
123/// `WINAPI` calling convention and delegate directly to this function. Null is
124/// accepted as a defensive no-op, although Excel is not expected to supply it
125/// during correct operation. Panics are contained and discarded; no panic can
126/// unwind through this FFI boundary when unwinding is enabled. A build using
127/// `panic = "abort"` still aborts, because aborting panics cannot be caught.
128///
129/// # Safety
130///
131/// A non-null `pointer` must be the pointer returned exactly once by
132/// [`ExcelReturn::into_raw_for_excel`] from this same loaded binary, must not
133/// have been reclaimed already, and must no longer be accessed by Excel after
134/// this callback begins. Arbitrary non-null pointers and duplicate callbacks
135/// cannot be validated safely and violate the Excel/XLL ownership contract.
136pub 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        // SAFETY: upheld by this callback's non-null handed-off-pointer
150        // contract. This closure is invoked exactly once for this call.
151        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
159/// Reconstructs the exact root-first owner and drops the complete return tree.
160///
161/// # Safety
162///
163/// `pointer` must be non-null, must have been returned exactly once by
164/// `ExcelReturn::into_raw_for_excel`, must not have been reclaimed before, and
165/// must point at a `ReturnAllocation` with the current binary's compatible
166/// layout and offset-zero root. Excel must perform no further access after
167/// entering the callback.
168unsafe fn reclaim_excel_return(pointer: *mut XLOPER12) {
169    let allocation = pointer.cast::<ReturnAllocation>();
170    // SAFETY: the caller guarantees this is the unique pointer produced by
171    // Box::into_raw for this exact ReturnAllocation. Dropping its Rust fields
172    // releases all nested storage without inspecting raw ABI tags.
173    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    /// Materializes this pointer-free plan into stable DLL-owned return storage.
185    ///
186    /// Call [`ExcelReturn::into_raw_for_excel`] only at the generated thunk's
187    /// final return boundary so Excel can later invoke `xlAutoFree12` once.
188    pub fn materialize(self) -> Result<ExcelReturn, ReturnMaterializationError> {
189        ExcelReturn::from_plan(self)
190    }
191}
192
193/// Root-first owner. Raw ABI pointers target only the boxed storage owned by
194/// later fields; local cleanup uses these Rust fields and never walks unions.
195#[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        // The Excel ABI uses a mutable pointer type, but the materialized
260        // counted string is immutable until the later consuming handoff.
261        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        // The allocation is boxed and never resized. The ABI pointer remains
304        // stable while the owning ReturnAllocation is alive.
305        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    // SAFETY: every member of XLOPER12Value consists solely of integers,
690    // floating-point values, or raw pointers. The all-zero bit pattern is
691    // valid for each member. Zeroing the complete union also defines all bytes
692    // not occupied by the subsequently selected active member.
693    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        // SAFETY: the asserted base tag selects `val.num`; the complete union
860        // was initialized by the centralized raw constructor.
861        unsafe { value.val.num }
862    }
863
864    fn integer(value: &XLOPER12) -> i32 {
865        assert_eq!(value.xltype, xltypeInt);
866        // SAFETY: the asserted base tag selects `val.w`; the complete union was
867        // initialized by the centralized raw constructor.
868        unsafe { value.val.w }
869    }
870
871    fn boolean(value: &XLOPER12) -> i32 {
872        assert_eq!(value.xltype, xltypeBool);
873        // SAFETY: the asserted base tag selects `val.xbool`; the complete union
874        // was initialized by the centralized raw constructor.
875        unsafe { value.val.xbool }
876    }
877
878    fn error_code(value: &XLOPER12) -> i32 {
879        assert_eq!(value.xltype, xltypeErr);
880        // SAFETY: the asserted base tag selects `val.err`; the complete union
881        // was initialized by the centralized raw constructor.
882        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        // SAFETY: the tag selects `val.str`. Every string XLOPER produced by
888        // this module points to a nonempty, aligned Box<[XCHAR]> owned by
889        // `_owner`. The prefix is readable and gives the exact remaining
890        // initialized extent. `_owner` keeps the allocation alive and fixed.
891        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        // SAFETY: the tag selects `val.array`. Its pointer targets the stable
902        // boxed element buffer owned by `owner`; rows and columns were checked
903        // and their product is the exact initialized element count.
904        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        // SAFETY: the asserted base tag selects `val.array`; only its pointer
915        // value is copied and no pointee is accessed here.
916        unsafe { value.val.array.lparray }
917    }
918
919    fn string_pointer(value: &XLOPER12) -> *mut XCHAR {
920        assert_eq!(value.xltype, xltypeStr);
921        // SAFETY: the asserted base tag selects `val.str`; only its pointer
922        // value is copied and no pointee is accessed here.
923        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        // SAFETY: the masked base tag selects `val.str`; only the pointer is
929        // copied while the handed-off allocation remains alive.
930        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        // SAFETY: the masked base tag selects `val.array`; only its pointer is
936        // copied while the handed-off allocation remains alive.
937        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        // SAFETY: the caller keeps the handed-off ReturnAllocation alive, and
943        // this module created a nonempty counted buffer whose prefix gives its
944        // exact initialized extent.
945        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        // SAFETY: the caller keeps the handed-off ReturnAllocation alive. The
955        // materialized dimensions are positive and their product is the exact
956        // initialized length of the boxed element block.
957        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        // SAFETY: `pointer` has just been handed off and remains live until the
973        // one callback invocation below.
974        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        // SAFETY: this is the unique pointer just produced above and this is
981        // its sole callback reclamation.
982        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        // SAFETY: the root tag is xltypeMulti and therefore selects val.array.
1136        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            // SAFETY: this pointer and its nested string remain owned by the
1421            // handed-off allocation until the callback below.
1422            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            // SAFETY: same live handed-off allocation contract.
1427            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            // SAFETY: unique, live handoff pointer; called exactly once.
1433            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        // SAFETY: the handed-off root remains live until the callback below.
1454        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        // SAFETY: the handed-off element block remains live with its root.
1460        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        // SAFETY: nested counted buffers share the live top-level owner.
1472        let first_nested_string = unsafe { raw_counted_storage(&elements[6]) };
1473        // SAFETY: nested counted buffers share the live top-level owner.
1474        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        // SAFETY: unique, live handoff pointer; called exactly once.
1482        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        // SAFETY: null is explicitly accepted as a defensive no-op.
1503        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            // SAFETY: unique, live handoff pointer; called exactly once.
1517            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            // SAFETY: ownership of this unique handed-off pointer is moved
1537            // into this thread, which performs its sole callback reclamation.
1538            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}