1use core::marker::PhantomData;
2
3use crate::excel_call::CallCapability;
4
5#[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#[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)]
33pub struct LifecycleContext<'call> {
44 capability: &'call CallCapability<'call>,
45 _call: PhantomData<&'call mut &'call ()>,
46}
47
48#[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 pub fn drain_dispatcher(&self) -> crate::DispatchDrainReport {
102 crate::dispatcher::drain_thread_safe(self)
103 }
104}
105
106impl WorksheetContext<'_> {
107 pub fn drain_dispatcher(&self) -> crate::DispatchDrainReport {
109 crate::dispatcher::drain_worksheet(self)
110 }
111}
112
113impl MacroContext<'_> {
114 pub fn drain_dispatcher(&self) -> crate::DispatchDrainReport {
118 crate::dispatcher::drain_macro(self)
119 }
120}
121
122impl LifecycleContext<'_> {
123 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}