1use 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#[derive(Clone, Copy, Debug, Eq, PartialEq)]
16pub enum ExcelReleasePolicy {
17 XlFreeRequired,
20 NoReleaseRequired,
22}
23
24#[derive(Clone, Debug, Eq, PartialEq)]
26pub enum ExcelReleaseError {
27 ExcelCallFailure {
29 code: i32,
31 },
32 InvalidContext,
34 NotThreadSafe,
36 BackendUnavailable,
38 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#[derive(Clone, Debug, Eq, PartialEq)]
62pub enum ExcelOwnedConversionError {
63 Conversion(ConversionError),
65 Release(ExcelReleaseError),
67 ConversionAndRelease {
69 conversion: ConversionError,
71 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
102pub(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
117pub 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#[derive(Debug)]
149pub struct ExcelXlFreeTransfer<'call> {
150 owner: ExcelOwnedValue<'call>,
151}
152
153impl ExcelXlFreeTransfer<'_> {
154 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 #[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 pub fn as_value_ref(&self) -> Result<ExcelValueRef<'_>, DecodeError> {
202 debug_assert_eq!(self.state, ReleaseState::Active);
203 unsafe { RawExcelValue::from_callback(self.root.as_ref()) }.decode()
206 }
207
208 pub(crate) fn raw_root(&self) -> &XLOPER12 {
211 self.root.as_ref()
212 }
213
214 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 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 pub fn release(mut self) -> Result<(), ExcelReleaseError> {
241 self.attempt_release()
242 }
243
244 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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}