Async and the event loop

01 · BLOCKING

Blocking: when the thread is stuck

JavaScript in a web page runs on one thread: one call stack, doing one thing at a time. The same thread also handles your clicks and draws the page. So if your code is busy, nothing else can happen. That is blocking.

Run this and watch the timer. It asked for 0 ms. It gets about 1000, because the thread was stuck in a loop and could not even look at the timer:

// Busy-wait: the thread is stuck in this loop
function sleepBlocking(ms) {
  const end = Date.now() + ms;
  while (Date.now() < end) {}
}
​
const t0 = Date.now();
setTimeout(() => {
  console.log("timer fired after", Date.now() - t0, "ms");
}, 0); // asked for 0 ms!
​
console.log("start");
sleepBlocking(1000);
console.log("end");

The fix is never to wait by spinning. You start the slow thing, hand over a function to call when it is done, and let the thread go. That is non-blocking:

console.log("1. order a coffee");
​
setTimeout(() => {
  console.log("4. coffee is ready");
}, 1000);
​
console.log("2. pay");
console.log("3. find a seat");

02 · CALLBACKS

Callbacks: call me when it's done

A callback is a function you pass to someone else, to be called later. You have already used one: the arrow function handed to setTimeout. Here is a café that takes a callback, in the Node style where the first argument is an error (or null):

// A callback is just a function you hand over,
// to be called later, when the result exists.
function makeCoffee(order, done) {
  console.log("brewing a", order);
  setTimeout(() => {
    done(null, order + " (hot)");
  }, 300);
}
​
makeCoffee("flat white", (err, cup) => {
  if (err) return console.log("failed:", err);
  console.log("got a", cup);
});
​
console.log("meanwhile: reading the news");

Follow it on the stage. setTimeout does not wait. It hands the timer to the Web APIs, the browser's own machinery written in C++, and returns at once. The timer counts down outside JavaScript. When it fires, the browser puts your callback in the task queue, and the loop runs it once the stack is empty. The same happens for network requests (the dish; see how the internet moves your packets) and for clicks (the mouse).

Callbacks work, but when each step needs the last one's result, they nest:

function step(name, ms, done) {
  setTimeout(() => {
    console.log(name);
    done();
  }, ms);
}
​
// Each step can only start inside the last one's callback:
step("grind beans", 100, () => {
  step("heat water", 100, () => {
    step("brew", 100, () => {
      step("pour", 100, () => {
        console.log("done: the pyramid of doom");
      });
    });
  });
});

03 · THE EVENT LOOP

The event loop, in 3D

Here is the whole machine. Each part has one job:

• Call stack: the functions running right now. JavaScript only ever runs what is on top.
• Web APIs: timers, network, input. They work outside JavaScript, often on other threads.
• Task queue (amber): callbacks from timers, events and messages, waiting their turn. Browsers keep several task queues and may pick between them, but each runs in order.
• Microtask queue (pink): promise callbacks and queueMicrotask. Urgent, small jobs.
• Rendering: requestAnimationFrame callbacks, then style, layout and paint.

The event loop is the ring in the middle. The HTML standard spells out what it does on every turn, and it fits in three lines:

1. Take one task from a task queue and run it until the stack is empty.
2. Run every microtask, including ones queued while doing so, until the queue is empty.
3. If it is time for a new frame (about every 16.7 ms at 60 Hz), render.

Then go round again, or sleep until something arrives. A task is never interrupted: once code starts, it runs to completion. You never have to worry that another callback will change your variables halfway through a function. That guarantee is why single-threaded JavaScript is so much easier to reason about than threads.

04 · ORDERING PUZZLES

setTimeout ordering puzzles

You now know enough to predict any ordering. Before you press Run, write down what this prints:

console.log("A");
​
setTimeout(() => console.log("B"), 0);
​
Promise.resolve().then(() => console.log("C"));
​
queueMicrotask(() => console.log("D"));
​
console.log("E");

Answer: A E C D B. Now a harder one, where callbacks schedule more callbacks. Predict it on paper first:

console.log("1");
​
setTimeout(() => {
  console.log("2");
  Promise.resolve().then(() => console.log("3"));
}, 0);
​
Promise.resolve().then(() => {
  console.log("4");
  setTimeout(() => console.log("5"), 0);
});
​
setTimeout(() => console.log("6"), 0);
​
console.log("7");

It prints 1 7 4 2 3 6 5. 1 and 7 are synchronous. The script ends, so microtasks run: 4, which sets a third timer. Then the tasks, in the order they were queued: the timer for 2 (and its microtask, 3, runs straight after it, before the next task), then 6, then 5, which was set last.

The microtask rule has a sharp edge. The loop must empty the microtask queue before it does anything else, so microtasks that keep queueing microtasks starve everything: timers, clicks, even rendering.

setTimeout(() => console.log("timer: finally my turn"), 0);
​
// Each microtask queues another one. The loop must
// empty the microtask queue before ANY task runs.
let n = 0;
function again() {
  n++;
  if (n < 100000) queueMicrotask(again);
  else console.log("microtasks run:", n);
}
queueMicrotask(again);

05 · PROMISES

Promises: a box for a future value

A promise is an object that stands for a result that isn't there yet. It is in one of three states: pending, then either fulfilled with a value or rejected with a reason. It settles once, and never changes after that.

const order = new Promise((resolve, reject) => {
  console.log("1. the executor runs at once");
  setTimeout(() => resolve("flat white"), 500);
});
​
console.log("2. we got a promise back, still pending");
​
order.then((coffee) => {
  console.log("3. fulfilled with:", coffee);
});

On the stage, the promise sits on the purple shelf, pending, holding one callback. When the timer task calls resolve, it turns green, and its callback drops into the microtask queue.

The real power is chaining. then returns a new promise for whatever your callback returns. Return a value and the next step gets it; return a promise and the chain waits for it:

const wait = (ms, value) =>
  new Promise((resolve) => setTimeout(() => resolve(value), ms));
​
wait(300, 2)
  .then((n) => n * 10)            // return a value...
  .then((n) => wait(300, n + 1))  // ...or a promise: the chain waits
  .then((n) => console.log("result:", n));
​
console.log("the chain is set up; nothing has run yet");

06 · ASYNC / AWAIT

async / await: pausing without blocking

async and await (ES2017) let you write promise code that reads like ordinary code. An async function always returns a promise. await pauses that function until a promise settles, and gives you its value.

The word "pause" hides the clever part. Predict the order, then run it:

async function brew() {
  console.log("B: brew starts, synchronously");
  await null;                 // pause here, give the thread back
  console.log("D: resumed, as a microtask");
  return "coffee";
}
​
console.log("A: before");
brew().then((x) => console.log("E: got", x));
console.log("C: after: brew is paused, we are not");

Watch the stage: at await, the brew frame leaves the tower and parks on the shelf, while the script prints C. The thread is never blocked; only the function is paused. It comes back with all its local variables, exactly where it left off.

The commonest mistake with await is making things wait for each other when they don't need to:

const wait = (ms, v) =>
  new Promise((r) => setTimeout(() => r(v), ms));
​
async function oneAfterAnother() {
  const t = Date.now();
  const a = await wait(300, "a");
  const b = await wait(300, "b");
  console.log("one after another:", Date.now() - t, "ms");
}
​
async function atTheSameTime() {
  const t = Date.now();
  const [a, b] = await Promise.all([wait(300, "a"), wait(300, "b")]);
  console.log("at the same time:", Date.now() - t, "ms");
}
​
await oneAfterAnother();
await atTheSameTime();

Python has the same model, with the loop made explicit (asyncio):

import asyncio
 
async def brew(name, secs):
    print(name, "start")
    await asyncio.sleep(secs)     # give the loop back
    print(name, "done")
 
async def main():
    await asyncio.gather(brew("A", 0.3), brew("B", 0.1))
 
asyncio.run(main())
# A start
# B start
# B done
# A done

07 · ERRORS

Errors in async code

An error thrown in a callback can't be caught by code that has already finished. This try is useless:

try {
  setTimeout(() => {
    throw new Error("boom");
  }, 0);
} catch (e) {
  console.log("caught it?", e.message);   // never runs
}
console.log("the try block finished long ago");

Promises carry errors for you. A rejection skips every then until it reaches a catch, just like an exception jumping up the stack. And a catch that returns a value turns the chain back into success:

Promise.reject(new Error("burnt"))
  .then(() => console.log("skipped: the promise rejected"))
  .catch((e) => {
    console.log("caught:", e.message);
    return "tea instead";                // recover
  })
  .then((x) => console.log("carried on with", x))
  .finally(() => console.log("clean up, either way"));

With await, a rejection is thrown at the await, so plain try/catch works again. A rejection nobody handles fires an unhandledrejection event in browsers, and by default crashes Node (since version 15):

async function getUser(id) {
  await null;                     // pretend to ask a server
  if (id < 0) throw new Error("no user " + id);
  return { id, name: "Ada" };
}
​
async function main() {
  try {
    const u = await getUser(-1);   // the rejection is thrown HERE
    console.log(u.name);
  } catch (e) {
    console.log("handled:", e.message);
  }
}
main();
​
getUser(-2);   // nobody awaits it: an unhandled rejection

08 · ALL · RACE · ALLSETTLED

Promise.all, race, allSettled and any

Four built-ins combine many promises into one. Each makes a different choice about when to stop waiting. The stage feeds the same three promises into all four: A succeeds at 300 ms, B fails at 100 ms, C succeeds at 200 ms.

const ok = (ms, v) =>
  new Promise((r) => setTimeout(() => r(v), ms));
const fail = (ms, msg) =>
  new Promise((_, no) => setTimeout(() => no(new Error(msg)), ms));
// A: ok at 300 ms · B: fails at 100 ms · C: ok at 200 ms
const three = () => [ok(300, "A"), fail(100, "B broke"), ok(200, "C")];
​
const t0 = Date.now();
const at = () => Math.round((Date.now() - t0) / 100) * 100 + " ms";
​
Promise.all(three()).then(
  (v) => console.log(at(), "all:", v),
  (e) => console.log(at(), "all rejected:", e.message));
Promise.race(three()).then(
  (v) => console.log(at(), "race:", v),
  (e) => console.log(at(), "race rejected:", e.message));
Promise.any(three()).then(
  (v) => console.log(at(), "any:", v));
Promise.allSettled(three()).then((rs) =>
  console.log(at(), "allSettled:", rs.map((r) => r.status)));

• Promise.all: every result, in order, or the first failure. Use it when you need all of them.
• Promise.allSettled (ES2020): waits for all, never rejects, and reports each one's status. Use it for "try everything, then report".
• Promise.race: the first to settle, success or failure. Handy for timeouts.
• Promise.any (ES2021): the first success; it rejects with an AggregateError only if all fail. Use it for "the fastest mirror wins".

None of them cancels the losers. The other promises keep running; you have just stopped listening to them.

09 · CANCELLATION

Cancellation with AbortController

To stop the work itself, the web uses AbortController. The controller owns an AbortSignal; you pass the signal to anything that can be cancelled and call abort() when you change your mind. Your own functions can listen to the signal too:

function wait(ms, { signal } = {}) {
  return new Promise((resolve, reject) => {
    signal?.throwIfAborted();
    const id = setTimeout(() => resolve("done"), ms);
    signal?.addEventListener("abort", () => {
      clearTimeout(id);              // stop the real work too
      reject(signal.reason);
    }, { once: true });
  });
}
​
const controller = new AbortController();
setTimeout(() => controller.abort(), 200);   // the user clicks Cancel
​
try {
  await wait(1000, { signal: controller.signal });
  console.log("finished");
} catch (e) {
  console.log("stopped:", e.name);
}

The same signal works with fetch, event listeners and many Node APIs. A rejected fetch gives you an AbortError, which usually means "we cancelled this on purpose", not a real failure:

const controller = new AbortController();
cancelButton.onclick = () => controller.abort();
 
try {
  const res = await fetch("/api/search?q=cat", {
    signal: controller.signal,
  });
  show(await res.json());
} catch (e) {
  if (e.name === "AbortError") return;   // we cancelled it: fine
  throw e;
}
 
// or give up on its own after 5 seconds:
await fetch(url, { signal: AbortSignal.timeout(5000) });

Cancel when the user navigates away, types a new search, or a deadline passes. Otherwise stale answers arrive late and overwrite fresh ones.

10 · NOT PARALLEL

Why async isn't parallel

Async is concurrency: many jobs in progress at once, taking turns on one thread. It is not parallelism: many jobs running at the same instant on different cores. The difference shows the moment the work is computation instead of waiting:

const wait = (ms) => new Promise((r) => setTimeout(r, ms));
function crunch(ms) {                 // CPU work: busy for ms
  const end = Date.now() + ms;
  while (Date.now() < end) {}
}
​
async function waits(name) { await wait(300); }
async function works(name) { await wait(0); crunch(300); }
​
let t = Date.now();
await Promise.all([waits("A"), waits("B")]);
console.log("two waits:", Date.now() - t, "ms");   // overlap
​
t = Date.now();
await Promise.all([works("A"), works("B")]);
console.log("two crunches:", Date.now() - t, "ms"); // no overlap

The stage shows all three cases on a timeline. For real parallelism in the browser you start a Web Worker: a second thread with its own stack, its own event loop and no shared variables. You talk to it by passing messages. Node has worker_threads for the same job.

// main.js: hand the heavy work to another thread
const worker = new Worker("crunch.js");
worker.postMessage({ upTo: 50_000_000 });
worker.onmessage = (e) => console.log("sum:", e.data);
// the page stays responsive meanwhile
 
// crunch.js: runs on its own thread, with its own event loop
onmessage = (e) => {
  let sum = 0;
  for (let i = 0; i < e.data.upTo; i++) sum += i;
  postMessage(sum);
};

Underneath, a CPU core runs one instruction stream at a time; several cores, and several machines in a cluster, are how real parallel work gets done. Threads, races and locks are the next chapter.

11 · NODE'S LOOP

Node's event loop, briefly

Node.js uses the same model with a different engine room: libuv, a C library. Its loop goes round six phases, each with its own queue: timers (setTimeout), pending callbacks, idle/prepare (internal), poll (wait for I/O and run its callbacks), check (setImmediate) and close callbacks.

Between callbacks, Node drains two extra queues: process.nextTick first, then promise microtasks. So the familiar rules still hold:

// order.js (CommonJS), run with: node order.js
setTimeout(() => console.log("timeout"), 0);
setImmediate(() => console.log("immediate"));
process.nextTick(() => console.log("nextTick"));
Promise.resolve().then(() => console.log("promise"));
console.log("sync");
 
// sync
// nextTick
// promise
// timeout     <- these two can swap: from the main
// immediate   <- module, the order is not guaranteed

From inside an I/O callback the race disappears: the loop is in poll, and check comes next, so setImmediate always wins:

const fs = require("node:fs");
 
fs.readFile(__filename, () => {
  // inside an I/O callback we are in the poll phase,
  // so "check" (setImmediate) always comes next
  setTimeout(() => console.log("timeout"), 0);
  setImmediate(() => console.log("immediate"));
});
// immediate
// timeout

One more subtlety: Node runs an ES module (.mjs) from inside its promise-based loader, so the promise queue drains first and promise prints before nextTick. Network I/O is non-blocking in the operating system itself (epoll on Linux, kqueue on macOS, IOCP on Windows); file system work, DNS lookups and some crypto run on a small thread pool.

// Mini project: a search box that never shows stale results.
// fakeSearch answers after a random delay, like a real server.
function fakeSearch(q, { signal }) {
  return new Promise((resolve, reject) => {
    const id = setTimeout(() => resolve(q.toUpperCase() + "!"),
      100 + Math.random() * 400);
    signal.addEventListener("abort", () => {
      clearTimeout(id);
      reject(signal.reason);
    });
  });
}
​
let current = null;
async function onType(q) {
  current?.abort();                 // cancel the previous search
  current = new AbortController();
  try {
    const r = await fakeSearch(q, { signal: current.signal });
    console.log("show:", r);
  } catch (e) {
    if (e.name !== "AbortError") throw e;
    console.log("cancelled:", q);
  }
}
​
// someone types "cat" fast: one search per keystroke
[["c", 0], ["ca", 50], ["cat", 100]].forEach(([q, ms]) => {
  setTimeout(() => onType(q), ms);
});