Skip to main content

excel_api/
excel_owned.rs

1//! Callback-scoped ownership of results created by the Excel C API.
2//!
3//! Excel owns any auxiliary storage reachable from the root, while Rust owns
4//! the boxed root itself.  A required release is attempted exactly once.
5
6use core::{fmt, marker::PhantomData, panic::AssertUnwindSafe};
7
8use excel_api_sys::XLOPER12;
9
10use crate::{
11    ConversionError, ConversionLimits, DecodeError, ExcelValue, ExcelValueRef, RawExcelValue,
12};
13
14/// Whether an Excel C API result has an outstanding `xlFree` obligation.
15#[derive(Clone, Copy, Debug, Eq, PartialEq)]
16pub enum ExcelReleasePolicy {
17    /// Excel allocated auxiliary storage and the root must be passed to
18    /// `xlFree` once when it is no longer needed.
19    XlFreeRequired,
20    /// The call result has no auxiliary storage that needs releasing.
21    NoReleaseRequired,
22}
23
24/// A failure reported while attempting the one permitted `xlFree` call.
25#[derive(Clone, Debug, Eq, PartialEq)]
26pub enum ExcelReleaseError {
27    /// Excel returned its exact (possibly bit-combined) C API failure code.
28    ExcelCallFailure {
29        /// Exact raw Excel C API return code.
30        code: i32,
31    },
32    /// The callback capability does not permit a call into Excel.
33    InvalidContext,
34    /// The operation was rejected in a multithreaded-calculation context.
35    NotThreadSafe,
36    /// The Excel callback entry point is unavailable or has been unlinked.
37    BackendUnavailable,
38    /// An injected backend panicked. Production backends must never panic.
39    BackendPanicked,
40}
41
42impl fmt::Display for ExcelReleaseError {
43    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
44        match self {
45            Self::ExcelCallFailure { code } => {
46                write!(formatter, "xlFree returned Excel C API code {code}")
47            }
48            Self::InvalidContext => formatter.write_str("xlFree is unavailable in this context"),
49            Self::NotThreadSafe => formatter.write_str("Excel rejected xlFree as not thread safe"),
50            Self::BackendUnavailable => {
51                formatter.write_str("the Excel callback backend is unavailable")
52            }
53            Self::BackendPanicked => formatter.write_str("the xlFree backend panicked"),
54        }
55    }
56}
57
58impl std::error::Error for ExcelReleaseError {}
59
60/// The result of a consuming deep copy followed by the mandatory release.
61#[derive(Clone, Debug, Eq, PartialEq)]
62pub enum ExcelOwnedConversionError {
63    /// The deep copy failed, but the required release succeeded.
64    Conversion(ConversionError),
65    /// The deep copy succeeded, but the required release reported failure.
66    Release(ExcelReleaseError),
67    /// Both the deep copy and the exactly-once release reported failure.
68    ConversionAndRelease {
69        /// Copy failure observed before release.
70        conversion: ConversionError,
71        /// Release failure observed after the copy attempt.
72        release: ExcelReleaseError,
73    },
74}
75
76impl fmt::Display for ExcelOwnedConversionError {
77    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
78        match self {
79            Self::Conversion(error) => write!(formatter, "Excel result conversion failed: {error}"),
80            Self::Release(error) => write!(formatter, "Excel result release failed: {error}"),
81            Self::ConversionAndRelease {
82                conversion,
83                release,
84            } => write!(
85                formatter,
86                "Excel result conversion failed ({conversion}) and release failed ({release})"
87            ),
88        }
89    }
90}
91
92impl std::error::Error for ExcelOwnedConversionError {
93    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
94        match self {
95            Self::Conversion(error) => Some(error),
96            Self::Release(error) => Some(error),
97            Self::ConversionAndRelease { conversion, .. } => Some(conversion),
98        }
99    }
100}
101
102/// Narrow callback capability used only to release Excel-created results.
103///
104/// Implementations must be valid for the entire callback lifetime represented
105/// by the borrow and must not panic. A production implementation will call
106/// `Excel12v(xlFree, null, 1, [&mut root])` after runtime linking exists.
107pub(crate) trait ExcelReleaseBackend {
108    fn xl_free(&self, value: *mut XLOPER12) -> Result<(), ExcelReleaseError>;
109}
110
111#[derive(Clone, Copy, Debug, Eq, PartialEq)]
112enum ReleaseState {
113    Active,
114    Attempted,
115}
116
117/// A callback-scoped owner for one result root written by Excel.
118///
119/// The lifetime prevents the owner from outliving the backend/callback
120/// capability. The raw-pointer marker deliberately makes this type neither
121/// `Send` nor `Sync`; copy to [`ExcelValue`] before crossing threads.
122///
123/// ```compile_fail
124/// use excel_api::ExcelOwnedValue;
125/// fn require_send<T: Send>() {}
126/// require_send::<ExcelOwnedValue<'static>>();
127/// ```
128pub struct ExcelOwnedValue<'call> {
129    root: Box<XLOPER12>,
130    policy: ExcelReleasePolicy,
131    state: ReleaseState,
132    backend: &'call dyn ExcelReleaseBackend,
133    _not_send_or_sync: PhantomData<*mut ()>,
134}
135
136/// A pre-commit XLFree transfer token.
137///
138/// This token consumes the active owner but intentionally exposes neither a
139/// raw root pointer nor a way to set `xlbitXLFree`. Until Prompt 08 commits it
140/// at the final return boundary, dropping the token safely falls back to the
141/// owner's normal exactly-once release.
142///
143/// ```compile_fail
144/// use excel_api::ExcelXlFreeTransfer;
145/// fn require_clone<T: Clone>() {}
146/// require_clone::<ExcelXlFreeTransfer<'static>>();
147/// ```
148#[derive(Debug)]
149pub struct ExcelXlFreeTransfer<'call> {
150    owner: ExcelOwnedValue<'call>,
151}
152
153impl ExcelXlFreeTransfer<'_> {
154    /// Borrows the still-uncommitted value without exposing its raw root.
155    pub fn as_value_ref(&self) -> Result<ExcelValueRef<'_>, DecodeError> {
156        self.owner.as_value_ref()
157    }
158}
159
160impl fmt::Debug for ExcelOwnedValue<'_> {
161    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
162        let root = self.root.as_ref() as *const XLOPER12;
163        formatter
164            .debug_struct("ExcelOwnedValue")
165            .field("root", &root)
166            .field("xltype", &self.root.xltype)
167            .field("policy", &self.policy)
168            .field("state", &self.state)
169            .finish_non_exhaustive()
170    }
171}
172
173impl<'call> ExcelOwnedValue<'call> {
174    /// Constructs an owner from a root initialized by an Excel C API call.
175    ///
176    /// # Safety
177    ///
178    /// `root` must be the unique, not-yet-released result of a specified
179    /// `Excel12`/`Excel12v` call. Every reachable pointer must remain valid
180    /// until `backend` releases the top-level root. `policy` must come from the
181    /// call/result ownership metadata, and `backend` must remain a legal Excel
182    /// callback capability for `'call`.
183    #[allow(dead_code, reason = "the Excel12v call layer is Prompt 08")]
184    pub(crate) unsafe fn from_call_result(
185        root: XLOPER12,
186        policy: ExcelReleasePolicy,
187        backend: &'call dyn ExcelReleaseBackend,
188    ) -> Self {
189        debug_assert_eq!(root.xltype & excel_api_sys::xlbitDLLFree, 0);
190        Self {
191            root: Box::new(root),
192            policy,
193            state: ReleaseState::Active,
194            backend,
195            _not_send_or_sync: PhantomData,
196        }
197    }
198
199    /// Borrows the active result through the central ownership-bit-masking
200    /// decoder.
201    pub fn as_value_ref(&self) -> Result<ExcelValueRef<'_>, DecodeError> {
202        debug_assert_eq!(self.state, ReleaseState::Active);
203        // SAFETY: the constructor contract keeps the boxed root and all
204        // reachable Excel storage readable and immutable until release.
205        unsafe { RawExcelValue::from_callback(self.root.as_ref()) }.decode()
206    }
207
208    /// Borrows the stable result root for a typed, crate-internal follow-up
209    /// C API call. It cannot escape the callback owner.
210    pub(crate) fn raw_root(&self) -> &XLOPER12 {
211        self.root.as_ref()
212    }
213
214    /// Deep-copies without consuming or releasing this result.
215    pub fn to_owned_value(&self, limits: &ConversionLimits) -> Result<ExcelValue, ConversionError> {
216        ExcelValue::from_borrowed_with_limits(self.as_value_ref()?, limits)
217    }
218
219    /// Deep-copies and then consumes the Excel release obligation.
220    pub fn into_owned_value(
221        mut self,
222        limits: &ConversionLimits,
223    ) -> Result<ExcelValue, ExcelOwnedConversionError> {
224        let conversion = self.to_owned_value(limits);
225        let release = self.attempt_release();
226        match (conversion, release) {
227            (Ok(value), Ok(())) => Ok(value),
228            (Err(conversion), Ok(())) => Err(ExcelOwnedConversionError::Conversion(conversion)),
229            (Ok(_), Err(release)) => Err(ExcelOwnedConversionError::Release(release)),
230            (Err(conversion), Err(release)) => {
231                Err(ExcelOwnedConversionError::ConversionAndRelease {
232                    conversion,
233                    release,
234                })
235            }
236        }
237    }
238
239    /// Explicitly consumes this owner and attempts any required release once.
240    pub fn release(mut self) -> Result<(), ExcelReleaseError> {
241        self.attempt_release()
242    }
243
244    /// Consumes this owner into a non-duplicable pre-commit transfer token.
245    ///
246    /// No ownership bit is changed and no raw pointer is exposed here. The
247    /// final thunk integration remains deliberately crate-internal work for
248    /// Prompt 08.
249    pub fn into_xlfree_transfer(self) -> ExcelXlFreeTransfer<'call> {
250        ExcelXlFreeTransfer { owner: self }
251    }
252
253    fn attempt_release(&mut self) -> Result<(), ExcelReleaseError> {
254        if self.state != ReleaseState::Active {
255            return Ok(());
256        }
257        // Commit before the call: a reported failure does not prove that Excel
258        // retained the payload, so retrying could double-free it.
259        self.state = ReleaseState::Attempted;
260        if self.policy == ExcelReleasePolicy::NoReleaseRequired {
261            return Ok(());
262        }
263
264        let root = self.root.as_mut() as *mut XLOPER12;
265        std::panic::catch_unwind(AssertUnwindSafe(|| self.backend.xl_free(root)))
266            .unwrap_or(Err(ExcelReleaseError::BackendPanicked))
267    }
268}
269
270impl Drop for ExcelOwnedValue<'_> {
271    fn drop(&mut self) {
272        let _ = self.attempt_release();
273    }
274}
275
276#[cfg(test)]
277mod tests {
278    use std::{cell::RefCell, panic::catch_unwind, ptr};
279
280    use excel_api_sys::{
281        XLOPER12Array, XLOPER12Value, xlbitDLLFree, xlbitXLFree, xltypeErr, xltypeMulti, xltypeNum,
282        xltypeStr,
283    };
284
285    use super::*;
286    use crate::{ExcelError, ExcelString};
287
288    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
289    struct ReleaseRecord {
290        address: usize,
291        xltype: u32,
292    }
293
294    #[derive(Default)]
295    struct MockBackend {
296        records: RefCell<Vec<ReleaseRecord>>,
297        failure: RefCell<Option<ExcelReleaseError>>,
298        poison_root: bool,
299    }
300
301    impl MockBackend {
302        fn failing(error: ExcelReleaseError) -> Self {
303            Self {
304                failure: RefCell::new(Some(error)),
305                ..Self::default()
306            }
307        }
308
309        fn count(&self) -> usize {
310            self.records.borrow().len()
311        }
312    }
313
314    impl ExcelReleaseBackend for MockBackend {
315        fn xl_free(&self, value: *mut XLOPER12) -> Result<(), ExcelReleaseError> {
316            // SAFETY: the owner supplies its live boxed root for this call.
317            let xltype = unsafe { (*value).xltype };
318            self.records.borrow_mut().push(ReleaseRecord {
319                address: value as usize,
320                xltype,
321            });
322            let result = self.failure.borrow_mut().take().map_or(Ok(()), Err);
323            if self.poison_root {
324                // SAFETY: xlFree is documented as the sole C API operation
325                // that mutates its argument, and no read follows an attempt.
326                unsafe {
327                    (*value).val = XLOPER12Value { w: 0 };
328                    (*value).xltype = excel_api_sys::xltypeNil;
329                }
330            }
331            result
332        }
333    }
334
335    fn raw(value: XLOPER12Value, xltype: u32) -> XLOPER12 {
336        XLOPER12 { val: value, xltype }
337    }
338
339    unsafe fn owner<'a>(
340        value: XLOPER12,
341        policy: ExcelReleasePolicy,
342        backend: &'a MockBackend,
343    ) -> ExcelOwnedValue<'a> {
344        // SAFETY: each test keeps every fixture allocation alive through the
345        // owner and uses a backend that never dereferences nested storage.
346        unsafe { ExcelOwnedValue::from_call_result(value, policy, backend) }
347    }
348
349    #[test]
350    fn explicit_drop_and_no_release_policies_are_exact() {
351        let backend = MockBackend::default();
352        // SAFETY: this scalar fixture is initialized and the backend remains live.
353        let value = unsafe {
354            owner(
355                raw(XLOPER12Value { num: 1.5 }, xltypeNum),
356                ExcelReleasePolicy::XlFreeRequired,
357                &backend,
358            )
359        };
360        value.release().unwrap();
361        assert_eq!(backend.count(), 1);
362
363        {
364            // SAFETY: this scalar fixture is initialized and the backend remains live.
365            let _fallback = unsafe {
366                owner(
367                    raw(XLOPER12Value { num: 2.5 }, xltypeNum),
368                    ExcelReleasePolicy::XlFreeRequired,
369                    &backend,
370                )
371            };
372        }
373        assert_eq!(backend.count(), 2);
374
375        // SAFETY: this scalar fixture is initialized and has no nested payload.
376        let no_release = unsafe {
377            owner(
378                raw(XLOPER12Value { num: 3.5 }, xltypeNum),
379                ExcelReleasePolicy::NoReleaseRequired,
380                &backend,
381            )
382        };
383        no_release.release().unwrap();
384        assert_eq!(backend.count(), 2);
385    }
386
387    #[test]
388    fn ownership_bits_are_masked_and_utf16_copy_is_lossless() {
389        let backend = MockBackend::default();
390        let mut counted = vec![4, b'A' as u16, 0, 0xD800, 0xDC00];
391        // SAFETY: the counted buffer remains initialized through owner release.
392        let value = unsafe {
393            owner(
394                raw(
395                    XLOPER12Value {
396                        str: counted.as_mut_ptr(),
397                    },
398                    xltypeStr | xlbitXLFree,
399                ),
400                ExcelReleasePolicy::XlFreeRequired,
401                &backend,
402            )
403        };
404        assert_eq!(value.as_value_ref().unwrap().kind_name(), "text");
405        let copied = value
406            .into_owned_value(&ConversionLimits::default())
407            .unwrap();
408        assert_eq!(
409            copied,
410            ExcelValue::Text(ExcelString::from_utf16_units(counted[1..].to_vec()))
411        );
412        counted[1..].fill(b'Z' as u16);
413        let ExcelValue::Text(copied) = copied else {
414            panic!("expected text")
415        };
416        assert_eq!(copied.as_utf16(), &[b'A' as u16, 0, 0xD800, 0xDC00]);
417        assert_eq!(backend.count(), 1);
418    }
419
420    #[test]
421    fn multi_is_copied_and_only_the_top_level_root_is_released() {
422        let backend = MockBackend::default();
423        let mut first = [2, b'a' as u16, 0];
424        let mut second = [2, 0xD800, b'b' as u16];
425        let mut elements = vec![
426            raw(XLOPER12Value { num: 4.0 }, xltypeNum),
427            raw(
428                XLOPER12Value {
429                    err: excel_api_sys::xlerrNA,
430                },
431                xltypeErr,
432            ),
433            raw(XLOPER12Value { w: 0 }, excel_api_sys::xltypeNil),
434            raw(
435                XLOPER12Value {
436                    str: first.as_mut_ptr(),
437                },
438                xltypeStr,
439            ),
440            raw(
441                XLOPER12Value {
442                    str: second.as_mut_ptr(),
443                },
444                xltypeStr,
445            ),
446            raw(XLOPER12Value { num: -1.0 }, xltypeNum),
447        ];
448        let root = raw(
449            XLOPER12Value {
450                array: XLOPER12Array {
451                    lparray: elements.as_mut_ptr(),
452                    rows: 2,
453                    columns: 3,
454                },
455            },
456            xltypeMulti,
457        );
458        // SAFETY: the element and string buffers remain live through release.
459        let value = unsafe { owner(root, ExcelReleasePolicy::XlFreeRequired, &backend) };
460        let copied = value
461            .into_owned_value(&ConversionLimits::default())
462            .unwrap();
463        let ExcelValue::Array(copied) = copied else {
464            panic!("expected array")
465        };
466        assert_eq!((copied.rows(), copied.columns()), (2, 3));
467        assert_eq!(copied.get(0, 1), Some(&ExcelValue::Error(ExcelError::Na)));
468        assert_eq!(backend.count(), 1);
469        let record = backend.records.borrow()[0];
470        assert_eq!(record.xltype, xltypeMulti);
471        assert_ne!(record.address, elements.as_ptr() as usize);
472    }
473
474    #[test]
475    fn conversion_and_release_failures_are_composed_without_retry() {
476        let release = ExcelReleaseError::InvalidContext;
477        let backend = MockBackend::failing(release.clone());
478        let malformed = raw(
479            XLOPER12Value {
480                str: ptr::null_mut(),
481            },
482            xltypeStr,
483        );
484        // SAFETY: malformed nested storage is intentional; the initialized
485        // root is rejected before the null pointer can be dereferenced.
486        let error = unsafe { owner(malformed, ExcelReleasePolicy::XlFreeRequired, &backend) }
487            .into_owned_value(&ConversionLimits::default())
488            .unwrap_err();
489        assert_eq!(
490            error,
491            ExcelOwnedConversionError::ConversionAndRelease {
492                conversion: ConversionError::BorrowedValueDecode(DecodeError::NullStringPointer),
493                release,
494            }
495        );
496        assert_eq!(backend.count(), 1);
497    }
498
499    #[test]
500    fn conversion_limits_and_references_fail_but_still_release() {
501        let backend = MockBackend::default();
502        let mut counted = [2, b'a' as u16, b'b' as u16];
503        // SAFETY: the counted buffer remains initialized through release.
504        let string = unsafe {
505            owner(
506                raw(
507                    XLOPER12Value {
508                        str: counted.as_mut_ptr(),
509                    },
510                    xltypeStr,
511                ),
512                ExcelReleasePolicy::XlFreeRequired,
513                &backend,
514            )
515        };
516        let limits = ConversionLimits {
517            max_string_code_units: 1,
518            ..ConversionLimits::default()
519        };
520        assert_eq!(
521            string.into_owned_value(&limits),
522            Err(ExcelOwnedConversionError::Conversion(
523                ConversionError::StringLimitExceeded {
524                    actual: 2,
525                    maximum: 1,
526                }
527            ))
528        );
529
530        // SAFETY: the inline reference is initialized and contains no pointer.
531        let reference = unsafe {
532            owner(
533                raw(
534                    XLOPER12Value {
535                        sref: excel_api_sys::XLOPER12SRef {
536                            count: 1,
537                            reference: excel_api_sys::XLREF12 {
538                                rwFirst: 0,
539                                rwLast: 0,
540                                colFirst: 0,
541                                colLast: 0,
542                            },
543                        },
544                    },
545                    excel_api_sys::xltypeSRef,
546                ),
547                ExcelReleasePolicy::XlFreeRequired,
548                &backend,
549            )
550        };
551        assert_eq!(
552            reference.into_owned_value(&ConversionLimits::default()),
553            Err(ExcelOwnedConversionError::Conversion(
554                ConversionError::UnsupportedReference
555            ))
556        );
557        assert_eq!(backend.count(), 2);
558    }
559
560    #[test]
561    fn successful_conversion_preserves_release_failure_and_does_not_retry() {
562        for failure in [
563            ExcelReleaseError::ExcelCallFailure {
564                code: excel_api_sys::xlretAbort | excel_api_sys::xlretUncalced,
565            },
566            ExcelReleaseError::NotThreadSafe,
567            ExcelReleaseError::BackendUnavailable,
568        ] {
569            let backend = MockBackend::failing(failure.clone());
570            // SAFETY: this scalar fixture is initialized and the backend remains live.
571            let value = unsafe {
572                owner(
573                    raw(XLOPER12Value { num: 9.0 }, xltypeNum),
574                    ExcelReleasePolicy::XlFreeRequired,
575                    &backend,
576                )
577            };
578            assert_eq!(
579                value.into_owned_value(&ConversionLimits::default()),
580                Err(ExcelOwnedConversionError::Release(failure))
581            );
582            assert_eq!(backend.count(), 1);
583        }
584    }
585
586    #[test]
587    fn panic_during_conversion_still_releases_once() {
588        let backend = MockBackend::default();
589        // SAFETY: this scalar fixture is initialized and the backend remains live.
590        let value = unsafe {
591            owner(
592                raw(XLOPER12Value { num: 1.0 }, xltypeNum),
593                ExcelReleasePolicy::XlFreeRequired,
594                &backend,
595            )
596        };
597        let result = catch_unwind(AssertUnwindSafe(move || {
598            let _view = value.as_value_ref().unwrap();
599            panic!("injected conversion panic");
600        }));
601        assert!(result.is_err());
602        assert_eq!(backend.count(), 1);
603    }
604
605    #[test]
606    fn backend_panic_is_contained_and_consumes_the_obligation() {
607        struct PanicBackend(RefCell<usize>);
608        impl ExcelReleaseBackend for PanicBackend {
609            fn xl_free(&self, _: *mut XLOPER12) -> Result<(), ExcelReleaseError> {
610                *self.0.borrow_mut() += 1;
611                panic!("backend panic")
612            }
613        }
614        let backend = PanicBackend(RefCell::new(0));
615        // SAFETY: this scalar fixture is initialized and the backend remains live.
616        let value = unsafe {
617            ExcelOwnedValue::from_call_result(
618                raw(XLOPER12Value { num: 1.0 }, xltypeNum),
619                ExcelReleasePolicy::XlFreeRequired,
620                &backend,
621            )
622        };
623        assert_eq!(value.release(), Err(ExcelReleaseError::BackendPanicked));
624        assert_eq!(*backend.0.borrow(), 1);
625    }
626
627    #[test]
628    fn repeated_release_cycles_are_exactly_once_and_never_set_dllfree() {
629        let backend = MockBackend::default();
630        for index in 0..1_000 {
631            // SAFETY: every scalar fixture is initialized and the backend remains live.
632            let value = unsafe {
633                owner(
634                    raw(XLOPER12Value { num: index as f64 }, xltypeNum),
635                    ExcelReleasePolicy::XlFreeRequired,
636                    &backend,
637                )
638            };
639            value.release().unwrap();
640        }
641        assert_eq!(backend.count(), 1_000);
642        assert!(
643            backend
644                .records
645                .borrow()
646                .iter()
647                .all(|record| record.xltype & xlbitDLLFree == 0)
648        );
649    }
650
651    #[test]
652    fn transfer_token_consumes_owner_without_premature_bit_or_release() {
653        let backend = MockBackend::default();
654        // SAFETY: this scalar fixture is initialized and the backend remains live.
655        let value = unsafe {
656            owner(
657                raw(XLOPER12Value { num: 7.0 }, xltypeNum),
658                ExcelReleasePolicy::XlFreeRequired,
659                &backend,
660            )
661        };
662        let token = value.into_xlfree_transfer();
663        assert_eq!(backend.count(), 0);
664        assert_eq!(token.as_value_ref().unwrap().kind_name(), "number");
665        assert_eq!(token.owner.root.xltype & (xlbitXLFree | xlbitDLLFree), 0);
666        drop(token);
667        assert_eq!(backend.count(), 1);
668    }
669}