I'm an absolute beginner in extension development trying to wrap my head around the browser runtime, which consists of the event loop + call stack + web APIs. As I understand it, if you run a script containing a function like this:
setTimeout(function msg() {
console.log("Hey guys.");
}, 4000);
The call to setTimeout() will be pushed to the call stack, executed, and sent to the Web API which will start the timer for four seconds, after which it pushes the console.log("Hey guys"); call to the Event Loop queue. It's only until the call stack is empty that this call on the queue is popped, then pushed to the call stack. This callback mechanism is what provides JavaScript engines with asynchronous functionality.
Does the same process apply to the following function call?
chrome.runtime.onInstalled.addListener(() => {
console.log("Hello");
})
Here is where my confusion lies:
addListener() is pushed to the call stack, what happens after it's executed? Does the browser now "store" this listener function so that it knows to look out for the onInstalled event? And will it push the callback function onto the Event Loop queue once the event has been detected?addListenermethod called on the event object chrome.runtime.onInstalledas opposed to taking it as a parameter?chrome.runtime.onInstalled object just a representation of the actual browser event, not the event itself? (i.e. an object provided by the Chrome API)Does the same process apply to the following function call?
Kind of.
Assuming addListener() is pushed to the call stack, what happens after it's executed?
When the script starts, addListener adds the listener to the internal event registry without calling it. The registry is keyed on function reference so it'll be registered just once per event i.e. subsequent addListener calls will be effectively ignored.
Then the script ends, all listeners are registered.
Then, in case this script is the non-persistent background script (service worker or an event page), the event that woke the background script will be used to find its registered listeners in the registry and they will be called. This is why the documentation says that API listeners must be registered in "top level", although it's an oversimplification. Technically, the listeners must be registered before the script ends, i.e. it may happen inside a nested function as long as it runs synchronously, and even inside a synchronously imported ES module.
Why is the addListener method called on the event object
This is how the extensions API is implemented internally, there's no universal reason why this exact shape was used, it's just how they liked it and it makes perfect sense because the object contains various useful methods like hasListener, removeListener, and several others.
Is the chrome.runtime.onInstalled object just a representation of the actual browser event, not the event itself?
The word "event" here doesn't mean an instance of the event similar to DOM Event object that is dispatched to JS code. There's no such thing in the extensions API. It's just a static part of the API that is nested to represent the structure thereof: chrome is the common namespace, runtime is the specific API, onInstalled is the event name. This object is constructed by the internal JS layer of the extensions platform when the script starts.