Skip to main content

blitz_script/
engine.rs

1//! Execution control seam for script backends.
2
3use blitz_dom::NodeId;
4use blitz_traits::events::{DomEvent, EventState};
5use url::Url;
6use web_time::{Duration, Instant};
7
8pub use crate::job_budget::{JobBudget, JobSlice};
9use crate::{DiagnosticBatch, DiagnosticEntry};
10
11/// Operations used by the document and event driver to enter script execution.
12///
13/// JobScope is an owned guard, so a checkpoint can share the outer budget
14/// without retaining a borrow of the engine during a host callback.
15pub trait ScriptEngine {
16    type JobScope;
17    fn eval(&mut self, code: &str, description: &str);
18    fn eval_at(&mut self, code: &str, url: Option<&Url>, description: &str);
19    fn eval_internal(&mut self, code: &str, description: &str);
20    fn eval_module(&mut self, code: &str, url: Option<&Url>, description: &str);
21    fn eval_json(&mut self, code: &str, description: &str) -> Result<serde_json::Value, String>;
22    fn set_import_map(&self, json: &str, base_url: Option<&Url>);
23    /// Advance backend module evaluation bookkeeping after running queued jobs.
24    fn poll_module_evaluations(&mut self);
25    /// Whether module evaluation promises still need to settle.
26    fn has_pending_module_evaluations(&self) -> bool;
27    /// Whether module source/dependency resolution still needs external progress.
28    fn has_pending_module_loads(&self) -> bool;
29    fn begin_job_slice(&self) -> Self::JobScope;
30    fn job_budget(&self) -> Duration;
31    fn set_job_budget(&self, duration: Duration);
32    fn pending_task_count(&self) -> u64;
33    fn job_slice_exhausted(&self) -> bool;
34    fn jobs_remain(&self) -> bool;
35    fn run_jobs(&mut self, description: &str);
36    /// Run a bounded job slice and report whether script work made progress.
37    fn run_jobs_with_progress(&mut self, description: &str) -> bool;
38    /// Earliest timer deadline, for scheduling the next driver wakeup.
39    fn next_timer_deadline(&self) -> Option<Instant>;
40    fn run_due_timers(&mut self, profiling: bool) -> bool;
41    fn dispatch_dom_event(
42        &mut self,
43        chain: &[NodeId],
44        event: &DomEvent,
45        event_state: &mut EventState,
46        profiling: bool,
47    ) -> bool;
48    fn dispatch_document_event(&mut self, name: &str) -> bool;
49    fn dispatch_node_event(&mut self, node_id: NodeId, name: &str) -> bool;
50    fn dispatch_window_event(&mut self, name: &str) -> bool;
51    fn set_document_ready_state(&mut self, next: &'static str) -> bool;
52    fn sweep_detached_nodes(&mut self);
53    /// Apply pending host platform updates and report whether they changed the document.
54    fn poll_host_updates(&mut self) -> bool;
55    fn console_entries_after(&self, sequence: u64) -> Vec<DiagnosticEntry>;
56    fn runtime_errors_after(&self, sequence: u64) -> Vec<DiagnosticEntry>;
57    fn diagnostic_batch(
58        &self,
59        console_after: u64,
60        errors_after: u64,
61        limit: usize,
62    ) -> DiagnosticBatch;
63}
64
65/// Statically dispatched owner of a script backend.
66///
67/// Backend-specific operations are available through the explicit backend accessors.
68#[repr(transparent)]
69pub struct Engine<E: ScriptEngine> {
70    backend: E,
71}
72
73impl<E: ScriptEngine> Engine<E> {
74    pub fn new(backend: E) -> Self {
75        Self { backend }
76    }
77
78    pub fn backend(&self) -> &E {
79        &self.backend
80    }
81
82    pub fn backend_mut(&mut self) -> &mut E {
83        &mut self.backend
84    }
85
86    pub fn eval(&mut self, code: &str, description: &str) {
87        self.backend.eval(code, description)
88    }
89
90    pub fn eval_at(&mut self, code: &str, url: Option<&Url>, description: &str) {
91        self.backend.eval_at(code, url, description)
92    }
93
94    pub fn eval_internal(&mut self, code: &str, description: &str) {
95        self.backend.eval_internal(code, description)
96    }
97
98    pub fn eval_module(&mut self, code: &str, url: Option<&Url>, description: &str) {
99        self.backend.eval_module(code, url, description)
100    }
101
102    pub fn eval_json(
103        &mut self,
104        code: &str,
105        description: &str,
106    ) -> Result<serde_json::Value, String> {
107        self.backend.eval_json(code, description)
108    }
109
110    pub fn set_import_map(&self, json: &str, base_url: Option<&Url>) {
111        self.backend.set_import_map(json, base_url)
112    }
113
114    pub fn poll_module_evaluations(&mut self) {
115        self.backend.poll_module_evaluations()
116    }
117
118    pub fn has_pending_module_evaluations(&self) -> bool {
119        self.backend.has_pending_module_evaluations()
120    }
121
122    pub fn has_pending_module_loads(&self) -> bool {
123        self.backend.has_pending_module_loads()
124    }
125
126    pub fn begin_job_slice(&self) -> E::JobScope {
127        self.backend.begin_job_slice()
128    }
129
130    pub fn job_budget(&self) -> Duration {
131        self.backend.job_budget()
132    }
133
134    pub fn set_job_budget(&self, duration: Duration) {
135        self.backend.set_job_budget(duration)
136    }
137
138    pub fn pending_task_count(&self) -> u64 {
139        self.backend.pending_task_count()
140    }
141
142    pub fn job_slice_exhausted(&self) -> bool {
143        self.backend.job_slice_exhausted()
144    }
145
146    pub fn jobs_remain(&self) -> bool {
147        self.backend.jobs_remain()
148    }
149
150    pub fn run_jobs(&mut self, description: &str) {
151        self.backend.run_jobs(description)
152    }
153
154    pub fn run_jobs_with_progress(&mut self, description: &str) -> bool {
155        self.backend.run_jobs_with_progress(description)
156    }
157
158    pub fn next_timer_deadline(&self) -> Option<Instant> {
159        self.backend.next_timer_deadline()
160    }
161
162    pub fn run_due_timers(&mut self, profiling: bool) -> bool {
163        self.backend.run_due_timers(profiling)
164    }
165
166    pub fn dispatch_dom_event(
167        &mut self,
168        chain: &[NodeId],
169        event: &DomEvent,
170        event_state: &mut EventState,
171        profiling: bool,
172    ) -> bool {
173        self.backend
174            .dispatch_dom_event(chain, event, event_state, profiling)
175    }
176
177    pub fn dispatch_document_event(&mut self, name: &str) -> bool {
178        self.backend.dispatch_document_event(name)
179    }
180
181    pub fn dispatch_node_event(&mut self, node_id: NodeId, name: &str) -> bool {
182        self.backend.dispatch_node_event(node_id, name)
183    }
184
185    pub fn dispatch_window_event(&mut self, name: &str) -> bool {
186        self.backend.dispatch_window_event(name)
187    }
188
189    pub fn set_document_ready_state(&mut self, next: &'static str) -> bool {
190        self.backend.set_document_ready_state(next)
191    }
192
193    pub fn sweep_detached_nodes(&mut self) {
194        self.backend.sweep_detached_nodes()
195    }
196
197    pub fn poll_host_updates(&mut self) -> bool {
198        self.backend.poll_host_updates()
199    }
200
201    pub fn console_entries_after(&self, sequence: u64) -> Vec<DiagnosticEntry> {
202        self.backend.console_entries_after(sequence)
203    }
204
205    pub fn runtime_errors_after(&self, sequence: u64) -> Vec<DiagnosticEntry> {
206        self.backend.runtime_errors_after(sequence)
207    }
208
209    pub fn diagnostic_batch(
210        &self,
211        console_after: u64,
212        errors_after: u64,
213        limit: usize,
214    ) -> DiagnosticBatch {
215        self.backend
216            .diagnostic_batch(console_after, errors_after, limit)
217    }
218}