Homepage ▸ Exploring JavaScript (ES2024 Edition)
You can support this book: buy it or donate
(Ad, please don’t block.)

41 Foundations of asynchronous programming in JavaScript

This chapter explains the foundations of asynchronous programming in JavaScript.

41.1 A roadmap for asynchronous programming in JavaScript

This section provides a roadmap for the content on asynchronous programming in JavaScript.

Icon “reading” Don’t worry about the details!

Don’t worry if you don’t understand everything yet. This is just a quick peek at what’s coming up.

41.1.1 Synchronous functions

Normal functions are synchronous: the caller waits until the callee is finished with its computation. divideSync() in line A is a synchronous function call:

function main() {
  try {
    const result = divideSync(12, 3); // (A)
    assert.equal(result, 4);
  } catch (err) {
    assert.fail(err);
  }
}

41.1.2 JavaScript executes tasks sequentially in a single process

By default, JavaScript tasks are functions that are executed sequentially in a single process. That looks like this:

while (true) {
  const task = taskQueue.dequeue();
  task(); // run task
}

This loop is also called the event loop because events, such as clicking a mouse, add tasks to the queue.

Due to this style of cooperative multitasking, we don’t want a task to block other tasks from being executed while, for example, it waits for results coming from a server. The next subsection explores how to handle this case.

41.1.3 Callback-based asynchronous functions

What if divide() needs a server to compute its result? Then the result should be delivered in a different manner: The caller shouldn’t have to wait (synchronously) until the result is ready; it should be notified (asynchronously) when it is. One way of delivering the result asynchronously is by giving divide() a callback function that it uses to notify the caller.

function main() {
  divideCallback(12, 3,
    (err, result) => {
      if (err) {
        assert.fail(err);
      } else {
        assert.equal(result, 4);
      }
    });
}

When there is an asynchronous function call:

divideCallback(x, y, callback)

Then the following steps happen:

41.1.4 Promise-based asynchronous functions

Promises are two things:

Invoking a Promise-based function looks as follows.

function main() {
  dividePromise(12, 3)
    .then(result => assert.equal(result, 4))
    .catch(err => assert.fail(err));
}

41.1.5 Async functions

One way of looking at async functions is as better syntax for Promise-based code:

async function main() {
  try {
    const result = await dividePromise(12, 3); // (A)
    assert.equal(result, 4);
  } catch (err) {
    assert.fail(err);
  }
}

The dividePromise() we are calling in line A is the same Promise-based function as in the previous section. But we now have synchronous-looking syntax for handling the call. await can only be used inside a special kind of function, an async function (note the keyword async in front of the keyword function). await pauses the current async function and returns from it. Once the awaited result is ready, the execution of the function continues where it left off.

41.1.6 Next steps

41.2 The call stack

Whenever a function calls another function, we need to remember where to return to after the latter function is finished. That is typically done via a stack – the call stack: the caller pushes onto it the location to return to, and the callee jumps to that location after it is done.

This is an example where several calls happen:

function h(z) {
  const error = new Error();
  console.log(error.stack);
}
function g(y) {
  h(y + 1);
}
function f(x) {
  g(x + 1);
}
f(3);

Initially, before running this piece of code, the call stack is empty. After the function call f(3) in line 11, the stack has one entry:

After the function call g(x + 1) in line 9, the stack has two entries:

After the function call h(y + 1) in line 6, the stack has three entries:

Logging error in line 3, produces the following output:

Error
    at h (demos/async-js/stack_trace.mjs:2:17)
    at g (demos/async-js/stack_trace.mjs:7:3)
    at f (demos/async-js/stack_trace.mjs:10:3)
    at demos/async-js/stack_trace.mjs:12:1

This is a so-called stack trace of where the Error object was created. Note that it records where calls were made, not return locations. Creating the exception in line 2 is yet another call. That’s why the stack trace includes a location inside h().

After line 3, each of the functions terminates and each time, the top entry is removed from the call stack. After function f is done, we are back in top-level scope and the stack is empty. When the code fragment ends then that is like an implicit return. If we consider the code fragment to be a task that is executed, then returning with an empty call stack ends the task.

41.3 The event loop

By default, JavaScript runs in a single process – in both web browsers and Node.js. The so-called event loop sequentially executes tasks (pieces of code) inside that process. The event loop is depicted in figure 41.1.

Figure 41.1: Task sources add code to run to the task queue, which is emptied by the event loop.

Two parties access the task queue:

The following JavaScript code is an approximation of the event loop:

while (true) {
  const task = taskQueue.dequeue();
  task(); // run task
}

41.4 How to avoid blocking the JavaScript process

41.4.1 The user interface of the browser can be blocked

Many of the user interface mechanisms of browsers also run in the JavaScript process (as tasks). Therefore, long-running JavaScript code can block the user interface. Let’s look at a web page that demonstrates that. There are two ways in which you can try out that page:

The following HTML is the page’s user interface:

<a id="block" href="">Block</a>
<div id="statusMessage"></div>
<button>Click me!</button>

The idea is that you click “Block” and a long-running loop is executed via JavaScript. During that loop, you can’t click the button because the browser/JavaScript process is blocked.

A simplified version of the JavaScript code looks like this:

document.getElementById('block')
  .addEventListener('click', doBlock); // (A)

function doBlock(event) {
  // ···
  displayStatus('Blocking...');
  // ···
  sleep(5000); // (B)
  displayStatus('Done');
}

function sleep(milliseconds) {
  const start = Date.now();
  while ((Date.now() - start) < milliseconds);
}
function displayStatus(status) {
  document.getElementById('statusMessage')
    .textContent = status;
}

These are the key parts of the code:

41.4.2 How can we avoid blocking the browser?

There are several ways in which you can prevent a long-running operation from blocking the browser:

41.4.3 Taking breaks

The following global function executes its parameter callback after a delay of ms milliseconds (the type signature is simplified – setTimeout() has more features):

function setTimeout(callback: () => void, ms: number): any

The function returns a handle (an ID) that can be used to clear the timeout (cancel the execution of the callback) via the following global function:

function clearTimeout(handle?: any): void

setTimeout() is available on both browsers and Node.js. The next subsection shows it in action.

Icon “tip” setTimeout() lets tasks take breaks

Another way of looking at setTimeout() is that the current task takes a break and continues later via the callback.

41.4.4 Run-to-completion semantics

JavaScript makes a guarantee for tasks:

Each task is always finished (“run to completion”) before the next task is executed.

As a consequence, tasks don’t have to worry about their data being changed while they are working on it (concurrent modification). That simplifies programming in JavaScript.

The following example demonstrates this guarantee:

console.log('start');
setTimeout(() => {
  console.log('callback');
}, 0);
console.log('end');

Output:

start
end
callback

setTimeout() puts its parameter into the task queue. The parameter is therefore executed sometime after the current piece of code (task) is completely finished.

The parameter ms only specifies when the task is put into the queue, not when exactly it runs. It may even never run – for example, if there is a task before it in the queue that never terminates. That explains why the previous code logs 'end' before 'callback', even though the parameter ms is 0.

41.5 Patterns for delivering asynchronous results

In order to avoid blocking the main process while waiting for a long-running operation to finish, results are often delivered asynchronously in JavaScript. These are three popular patterns for doing so:

The first two patterns are explained in the next two subsections. Promises are explained in the next chapter.

41.5.1 Delivering asynchronous results via events

Events as a pattern work as follows:

Multiple variations of this pattern exist in the world of JavaScript. We’ll look at three examples next.

41.5.1.1 Events: IndexedDB

IndexedDB is a database that is built into web browsers. This is an example of using it:

const openRequest = indexedDB.open('MyDatabase', 1); // (A)

openRequest.onsuccess = (event) => {
  const db = event.target.result;
  // ···
};

openRequest.onerror = (error) => {
  console.error(error);
};

indexedDB has an unusual way of invoking operations:

41.5.1.2 Events: XMLHttpRequest

The XMLHttpRequest API lets us make downloads from within a web browser. This is how we download the file http://example.com/textfile.txt:

const xhr = new XMLHttpRequest(); // (A)
xhr.open('GET', 'http://example.com/textfile.txt'); // (B)
xhr.onload = () => { // (C)
  if (xhr.status == 200) {
    processData(xhr.responseText);
  } else {
    assert.fail(new Error(xhr.statusText));
  }
};
xhr.onerror = () => { // (D)
  assert.fail(new Error('Network error'));
};
xhr.send(); // (E)

function processData(str) {
  assert.equal(str, 'Content of textfile.txt\n');
}

With this API, we first create a request object (line A), then configure it, then activate it (line E). The configuration consists of:

41.5.1.3 Events: DOM

We have already seen DOM events in action in “The user interface of the browser can be blocked” (§41.4.1). The following code also handles click events:

const element = document.getElementById('my-link'); // (A)
element.addEventListener('click', clickListener); // (B)

function clickListener(event) {
  event.preventDefault(); // (C)
  console.log(event.shiftKey); // (D)
}

We first ask the browser to retrieve the HTML element whose ID is 'my-link' (line A). Then we add a listener for all click events (line B). In the listener, we first tell the browser not to perform its default action (line C) – going to the target of the link. Then we log to the console if the shift key is currently pressed (line D).

41.5.2 Delivering asynchronous results via callbacks

Callbacks are another pattern for handling asynchronous results. They are only used for one-off results and have the advantage of being less verbose than events.

As an example, consider a function readFile() that reads a text file and returns its contents asynchronously. This is how you call readFile() if it uses Node.js-style callbacks:

readFile('some-file.txt', {encoding: 'utf-8'},
  (error, data) => {
    if (error) {
      assert.fail(error);
      return;
    }
    assert.equal(data, 'The content of some-file.txt');
  });

There is a single callback that handles both success and failure. If the first parameter is not null then an error happened. Otherwise, the result can be found in the second parameter.

Icon “exercise” Exercises: Callback-based code

The following exercises use tests for asynchronous code, which are different from tests for synchronous code. Consult “Asynchronous tests in Mocha” (§12.2.2) for more information.

41.6 Asynchronous code: the downsides

In many situations, on either browsers or Node.js, you have no choice, you must use asynchronous code. In this chapter, we have seen several patterns that such code can use. All of them have two disadvantages:

The first disadvantage becomes less severe with Promises (covered in the next chapter) and mostly disappears with async functions (covered in the chapter after next).

Alas, the infectiousness of async code does not go away. But it is mitigated by the fact that switching between sync and async is easy with async functions.

41.7 Resources

Comments
Next: Promises for asynchronous programming [ES6]