script/
microtask.rs

1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
4
5//! Implementation of [microtasks](https://html.spec.whatwg.org/multipage/#microtask) and
6//! microtask queues. It is up to implementations of event loops to store a queue and
7//! perform checkpoints at appropriate times, as well as enqueue microtasks as required.
8
9use std::cell::Cell;
10use std::mem;
11use std::rc::Rc;
12
13use js::jsapi::JobQueueMayNotBeEmpty;
14use js::realm::AutoRealm;
15use script_bindings::cell::DomRefCell;
16use servo_base::id::PipelineId;
17
18use crate::dom::bindings::callback::ExceptionHandling;
19use crate::dom::bindings::codegen::Bindings::PromiseBinding::PromiseJobCallback;
20use crate::dom::bindings::codegen::Bindings::VoidFunctionBinding::VoidFunction;
21use crate::dom::bindings::root::DomRoot;
22use crate::dom::globalscope::GlobalScope;
23use crate::dom::html::htmlimageelement::ImageElementMicrotask;
24use crate::dom::html::htmlmediaelement::MediaElementMicrotask;
25use crate::dom::promise::WaitForAllSuccessStepsMicrotask;
26use crate::dom::stream::byteteereadintorequest::ByteTeeReadIntoRequestMicrotask;
27use crate::dom::stream::byteteereadrequest::ByteTeeReadRequestMicrotask;
28use crate::dom::stream::defaultteereadrequest::DefaultTeeReadRequestMicrotask;
29use crate::realms::enter_auto_realm;
30use crate::script_runtime::{JSContext, notify_about_rejected_promises};
31use crate::script_thread::ScriptThread;
32
33/// A collection of microtasks in FIFO order.
34#[derive(Default, JSTraceable, MallocSizeOf)]
35pub(crate) struct MicrotaskQueue {
36    /// The list of enqueued microtasks that will be invoked at the next microtask checkpoint.
37    microtask_queue: DomRefCell<Vec<Microtask>>,
38    /// <https://html.spec.whatwg.org/multipage/#performing-a-microtask-checkpoint>
39    performing_a_microtask_checkpoint: Cell<bool>,
40}
41
42#[derive(JSTraceable, MallocSizeOf)]
43pub(crate) enum Microtask {
44    Promise(EnqueuedPromiseCallback),
45    User(UserMicrotask),
46    MediaElement(MediaElementMicrotask),
47    ImageElement(ImageElementMicrotask),
48    ReadableStreamTeeReadRequest(DefaultTeeReadRequestMicrotask),
49    WaitForAllSuccessSteps(WaitForAllSuccessStepsMicrotask),
50    ReadableStreamByteTeeReadRequest(ByteTeeReadRequestMicrotask),
51    ReadableStreamByteTeeReadIntoRequest(ByteTeeReadIntoRequestMicrotask),
52    CustomElementReaction,
53    NotifyMutationObservers,
54}
55
56pub(crate) trait MicrotaskRunnable {
57    fn handler(&self, _cx: &mut js::context::JSContext) {}
58    fn enter_realm<'cx>(&self, cx: &'cx mut js::context::JSContext) -> AutoRealm<'cx>;
59}
60
61/// A promise callback scheduled to run during the next microtask checkpoint (#4283).
62#[derive(JSTraceable, MallocSizeOf)]
63pub(crate) struct EnqueuedPromiseCallback {
64    #[conditional_malloc_size_of]
65    pub(crate) callback: Rc<PromiseJobCallback>,
66    #[no_trace]
67    pub(crate) pipeline: PipelineId,
68    pub(crate) is_user_interacting: bool,
69}
70
71/// A microtask that comes from a queueMicrotask() Javascript call,
72/// identical to EnqueuedPromiseCallback once it's on the queue
73#[derive(JSTraceable, MallocSizeOf)]
74pub(crate) struct UserMicrotask {
75    #[conditional_malloc_size_of]
76    pub(crate) callback: Rc<VoidFunction>,
77    #[no_trace]
78    pub(crate) pipeline: PipelineId,
79}
80
81impl MicrotaskQueue {
82    /// Add a new microtask to this queue. It will be invoked as part of the next
83    /// microtask checkpoint.
84    #[expect(unsafe_code)]
85    pub(crate) fn enqueue(&self, job: Microtask, cx: JSContext) {
86        self.microtask_queue.borrow_mut().push(job);
87        unsafe { JobQueueMayNotBeEmpty(*cx) };
88    }
89
90    /// <https://html.spec.whatwg.org/multipage/#perform-a-microtask-checkpoint>
91    /// Perform a microtask checkpoint, executing all queued microtasks until the queue is empty.
92    #[expect(unsafe_code)]
93    pub(crate) fn checkpoint<F>(
94        &self,
95        cx: &mut js::context::JSContext,
96        target_provider: F,
97        globalscopes: Vec<DomRoot<GlobalScope>>,
98    ) where
99        F: Fn(PipelineId) -> Option<DomRoot<GlobalScope>>,
100    {
101        // Step 1. If the event loop's performing a microtask checkpoint is true, then return.
102        if self.performing_a_microtask_checkpoint.get() {
103            return;
104        }
105
106        // Step 2. Set the event loop's performing a microtask checkpoint to true.
107        self.performing_a_microtask_checkpoint.set(true);
108
109        debug!("Now performing a microtask checkpoint");
110
111        // Step 3. While the event loop's microtask queue is not empty:
112        while !self.microtask_queue.borrow().is_empty() {
113            rooted_vec!(let mut pending_queue);
114            mem::swap(&mut *pending_queue, &mut *self.microtask_queue.borrow_mut());
115
116            for (idx, job) in pending_queue.iter().enumerate() {
117                if idx == pending_queue.len() - 1 && self.microtask_queue.borrow().is_empty() {
118                    unsafe { js::rust::wrappers2::JobQueueIsEmpty(cx) };
119                }
120
121                match *job {
122                    Microtask::Promise(ref job) => {
123                        if let Some(target) = target_provider(job.pipeline) {
124                            let _guard = ScriptThread::user_interacting_guard();
125                            let mut realm = enter_auto_realm(cx, &*target);
126                            let cx = &mut realm;
127                            let _ = job.callback.Call_(cx, &*target, ExceptionHandling::Report);
128                        }
129                    },
130                    Microtask::User(ref job) => {
131                        if let Some(target) = target_provider(job.pipeline) {
132                            let mut realm = enter_auto_realm(cx, &*target);
133                            let cx = &mut realm;
134                            let _ = job.callback.Call_(cx, &*target, ExceptionHandling::Report);
135                        }
136                    },
137                    Microtask::MediaElement(ref task) => {
138                        let mut realm = task.enter_realm(cx);
139                        let cx = &mut realm;
140                        task.handler(cx);
141                    },
142                    Microtask::ImageElement(ref task) => {
143                        let mut realm = task.enter_realm(cx);
144                        let cx = &mut realm;
145                        task.handler(cx);
146                    },
147                    Microtask::ReadableStreamTeeReadRequest(ref task) => {
148                        let mut realm = task.enter_realm(cx);
149                        let cx = &mut realm;
150                        task.handler(cx);
151                    },
152                    Microtask::WaitForAllSuccessSteps(ref task) => {
153                        let mut realm = task.enter_realm(cx);
154                        let cx = &mut realm;
155                        task.handler(cx);
156                    },
157                    Microtask::CustomElementReaction => {
158                        ScriptThread::invoke_backup_element_queue(cx);
159                    },
160                    Microtask::NotifyMutationObservers => {
161                        ScriptThread::mutation_observers().notify_mutation_observers(cx);
162                    },
163                    Microtask::ReadableStreamByteTeeReadRequest(ref task) => {
164                        task.microtask_chunk_steps(cx)
165                    },
166                    Microtask::ReadableStreamByteTeeReadIntoRequest(ref task) => {
167                        task.microtask_chunk_steps(cx)
168                    },
169                }
170            }
171        }
172
173        // Step 4. For each environment settings object settingsObject whose responsible
174        // event loop is this event loop, notify about rejected promises given
175        // settingsObject's global object.
176        for global in globalscopes.clone().into_iter() {
177            notify_about_rejected_promises(&global);
178        }
179
180        // https://html.spec.whatwg.org/multipage/#perform-a-microtask-checkpoint
181        // Step 5. Cleanup Indexed Database transactions.
182        // https://w3c.github.io/IndexedDB/#cleanup-indexed-database-transactions
183        // “These steps are invoked by [HTML]. They ensure that transactions created by a script call
184        // to transaction() are deactivated once the task that invoked the script has completed.”
185        for global in globalscopes.iter() {
186            let _ = global.get_indexeddb().cleanup_indexeddb_transactions();
187        }
188
189        // TODO: Step 6. Perform ClearKeptObjects().
190
191        // Step 7. Set the event loop's performing a microtask checkpoint to false.
192        self.performing_a_microtask_checkpoint.set(false);
193        // TODO: Step 8. Record timing info for microtask checkpoint.
194    }
195
196    pub(crate) fn empty(&self) -> bool {
197        self.microtask_queue.borrow().is_empty()
198    }
199
200    pub(crate) fn clear(&self) {
201        self.microtask_queue.borrow_mut().clear();
202    }
203}
script/microtask.rs

script/
microtask.rs
