Skip to main content

excel_api/
context.rs

1use core::marker::PhantomData;
2
3use crate::excel_call::CallCapability;
4
5/// Capability token for a genuine worksheet-function callback.
6///
7/// It borrows the callback capability and cannot be constructed by ordinary
8/// safe code. It does not imply that every Excel call is legal.
9#[derive(Debug)]
10pub struct WorksheetContext<'call> {
11    #[allow(
12        dead_code,
13        reason = "worksheet-safe calls are added to this capability whitelist incrementally"
14    )]
15    capability: &'call CallCapability<'call>,
16    _call: PhantomData<&'call mut &'call ()>,
17}
18
19/// Capability token for a genuine multi-thread-safe worksheet callback.
20///
21/// Only calls explicitly documented as thread-safe may use this context.
22#[derive(Debug)]
23pub struct ThreadSafeContext<'call> {
24    #[allow(
25        dead_code,
26        reason = "xlFree is consumed internally by Excel-owned result RAII"
27    )]
28    capability: &'call CallCapability<'call>,
29    _call: PhantomData<&'call mut &'call ()>,
30}
31
32#[derive(Debug)]
33/// Lifecycle callbacks cannot poll user cancellation: `xlAbort` is exposed
34/// only to the verified worksheet, thread-safe, and macro contexts.
35///
36/// ```compile_fail
37/// use excel_api::LifecycleContext;
38///
39/// fn cannot_poll(context: &LifecycleContext<'_>) {
40///     let _ = context.is_cancellation_requested();
41/// }
42/// ```
43pub struct LifecycleContext<'call> {
44    capability: &'call CallCapability<'call>,
45    _call: PhantomData<&'call mut &'call ()>,
46}
47
48/// Capability token for a genuine macro/command callback.
49///
50/// It is callback-borrowed and must not be retained or sent to another thread.
51#[derive(Debug)]
52#[cfg_attr(
53    not(feature = "xlcontime-research"),
54    doc = r#"
55The ordinary build exposes no xlcOnTime scheduling operation:
56
57```compile_fail
58use excel_api::MacroContext;
59
60fn no_production_ontime(context: &MacroContext<'_>) {
61    let _ = context.experimental_schedule_on_time(45_000.0, "COMMAND");
62}
63```
64"#
65)]
66pub struct MacroContext<'call> {
67    #[allow(dead_code, reason = "macro operations are outside the M8 catalogue")]
68    capability: &'call CallCapability<'call>,
69    _call: PhantomData<&'call mut &'call ()>,
70}
71
72macro_rules! context_impl {
73    ($type:ident) => {
74        impl<'call> $type<'call> {
75            #[allow(
76                dead_code,
77                reason = "constructed as each callback class gains operations"
78            )]
79            pub(crate) const fn new(capability: &'call CallCapability<'call>) -> Self {
80                Self {
81                    capability,
82                    _call: PhantomData,
83                }
84            }
85
86            #[allow(dead_code, reason = "consumed as each callback class gains operations")]
87            pub(crate) const fn capability(&self) -> &'call CallCapability<'call> {
88                self.capability
89            }
90        }
91    };
92}
93
94context_impl!(WorksheetContext);
95context_impl!(ThreadSafeContext);
96context_impl!(LifecycleContext);
97context_impl!(MacroContext);
98
99impl ThreadSafeContext<'_> {
100    /// Drains one bounded batch containing only thread-safe-compatible or pure work.
101    pub fn drain_dispatcher(&self) -> crate::DispatchDrainReport {
102        crate::dispatcher::drain_thread_safe(self)
103    }
104}
105
106impl WorksheetContext<'_> {
107    /// Drains one bounded batch containing only worksheet-compatible or pure work.
108    pub fn drain_dispatcher(&self) -> crate::DispatchDrainReport {
109        crate::dispatcher::drain_worksheet(self)
110    }
111}
112
113impl MacroContext<'_> {
114    /// Drains one bounded cooperative batch under this genuine macro callback.
115    ///
116    /// Enqueueing a request does not invoke this method or otherwise wake Excel.
117    pub fn drain_dispatcher(&self) -> crate::DispatchDrainReport {
118        crate::dispatcher::drain_macro(self)
119    }
120}
121
122impl LifecycleContext<'_> {
123    /// Drains one bounded batch containing only lifecycle-compatible or pure work.
124    /// Runtime close does not call this; close retires queued work instead.
125    pub fn drain_dispatcher(&self) -> crate::DispatchDrainReport {
126        crate::dispatcher::drain_lifecycle(self)
127    }
128}
129
130#[cfg(test)]
131mod tests {
132    use super::*;
133    use crate::excel_call::test_support::UnavailableBackend;
134
135    #[test]
136    fn contexts_carry_a_real_borrowed_capability() {
137        let backend = UnavailableBackend;
138        let capability = CallCapability::new(&backend);
139        let worksheet = WorksheetContext::new(&capability);
140        let thread_safe = ThreadSafeContext::new(&capability);
141        let lifecycle = LifecycleContext::new(&capability);
142        assert!(core::ptr::eq(worksheet.capability(), &capability));
143        assert!(core::ptr::eq(thread_safe.capability(), &capability));
144        assert!(core::ptr::eq(lifecycle.capability(), &capability));
145    }
146}