The Event Loop

in reviewThis lesson is complete and being validated before release - details may still change.

The event loop

Loading interactive demo…

The sheet is the script and the callbacks it names, the line being run lit. The strips are the loop's parts: the call stack with the task running, the microtask queue, the task queue of timers and reads with their due times, and the output as it grows. Tap a line of the sheet to ask what it does.Take the tour, or press and explore. Legend:

The panel beside the stage is the real EventLoop class from the published library executing in your browser, with the current line highlighted.

The line being run and the callback this step concerns.
A microtask waiting: it runs before any task.
A timer or read waiting for its due time and a free loop.
A line of output.
A callback overdue while the thread was held.

clock is script time in milliseconds, tasks and microtasks count the callbacks run from each queue, busy the time the thread was held by a spinning loop, and idle the time it slept waiting for something due.

The code panel shows bare executable code by default. The bar above it names the file (hover the name for the full published path); options holds the toggles: comments, the tracer instrumentation that produces this visualization, and verbose names for the terse identifiers (display only: the default is the byte-exact published file). The view switch adds plain-English narration: both interleaves it with the code, pseudo shows only the pseudocode. hide code collapses the panel; the rail it leaves behind brings it back.

Keys: Space play/pause · ←/→ step · Home/End jump · R reset · F fullscreen · G guided tour

A different answer to the race. The last two lessons shared memory between threads and paid for it with atomics and locks. The event loop refuses the premise: one thread, so no two pieces of code ever run at once, and no load can interleave with a store. The price is that nothing may block, and the machinery that makes that work is a loop over queues.

Tasks. The script runs first, as one task, from its first line to its last, and nothing can interrupt it. A timer does not pause; it records a callback and the earliest time it may run. A read does not wait; the operating system does the reading and queues the callback when it is done. When the script ends the stack is empty, and the loop turns: take the task due first, run it to its end, turn again. A callback is a task, and a task never sees another task half finished.

Microtasks. A promise reaction is a microtask, and the rule is that the microtask queue drains completely before the loop looks at any task, after every task. So in the default script the promise callback runs before a timer with zero delay, however long ago the timer came due, and a microtask that queues a microtask keeps every timer waiting. The ordering is fixed by the queues and the same on every run, which is what the race lesson's counter never had.

Time is not what it says. A timer's delay is the earliest it may fire, not when it will. The busy script sets a timer for 10 ms and then spins for 50: the timer comes due at 10, the loop is not turning, and the callback runs at 50. Nothing is lost, as a race loses an update, but everything is late, and in a browser a late frame is a frozen page. The clock on this stage moves only when code spins or the loop sleeps; running a line costs nothing, which is the simplification.

Waiting is free. With the queues empty and a read in flight, the loop sleeps until the operating system queues the completion. The file script shows two sleeps: to 20 ms for the timer, to 30 for the file. One thread holding ten thousand idle connections costs nothing while they are idle, which is why loops won the server. A thread per connection would be ten thousand stacks waiting.

The rule it imposes. Everything on the loop must be short, because every task waits for the running one. Long work is split into tasks with timers, handed to the operating system as I/O, or sent to another thread with a message, which is the shape of the last lesson in this arc. The loop gives up parallelism inside a thread for freedom from races; the actor model keeps the freedom and gets the parallelism back by running many loops that share nothing.

Choices worth reading closely in the implementation (the code panel's comments and tracer checkboxes reveal the full published file):

run is the loop in six lines: run the script, then while anything waits, take a microtask if there is one, otherwise the task due first, sleeping to its due time if need be.
execute runs a callback's actions to the end with nothing in between, which is the run-to-completion guarantee; the trace's call is the only place a stack is pushed.
Three kinds of later, two queues: then goes in microtasks, timeout and read in tasks with a due time. The difference between a timer and a read is only who sets the due time.
nextTasks sorts by due time, then by the order queued, so two timers due at once fire in the order set, and a read that completes before a timer runs before it.
busy advances the clock and counts what came due meanwhile, the number the stage calls overdue; no real loop measures it, and every real loop suffers it.
The program is data with named callbacks, so the stage can light the line being run and explain the one you tap.

Graphical interfaces of the 1980s were already loops that waited for an event, handled it to completion, and waited again. Douglas Schmidt named the shape the reactor pattern in 1995, the year Brendan Eich gave Netscape a single-threaded JavaScript whose only concurrency was the browser's loop. Servers followed once Dan Kegel asked how to serve ten thousand connections in 1999: nginx in 2004 and Node.js in 2009 run one loop per core and never block it, and the 2015 language standard added promises with a microtask queue that runs ahead of every timer.

1995Douglas Schmidt - The reactor pattern describes a loop that waits for events on many sources and dispatches each to a handler that runs to completion.source
1995Brendan Eich - JavaScript ships in Netscape Navigator with one thread and callbacks, so every browser script since has run on an event loop.source
1999Dan Kegel - The C10K problem asks how one server can hold ten thousand connections, and the answer is a loop over ready sockets rather than a thread per client.source
2004Igor Sysoev - nginx serves static files and proxies connections from a handful of event-driven worker processes, and overtakes thread-per-connection servers on busy sites.source
2009Ryan Dahl - Node.js puts the browser's JavaScript engine on an event loop with non-blocking I/O, so the same language serves requests the way it handles clicks.source
2015Ecma International - ECMAScript 2015 standardizes promises, whose reactions run as microtasks before the loop takes its next task.source

Used today

Every web page - Clicks, timers, network replies, and rendering all take turns on one thread, which is why a long loop freezes the page.
Node.js and Python's asyncio - A server handles thousands of connections on one loop by never waiting: each request is a callback chain or an async function.
Game and UI frameworks - A frame is a turn of the loop: handle input, update, draw, and yield, sixty times a second.

script

clock: 0 ms
tasks: 1
microtasks: 1
busy: 0 ms
idle: 0 ms

event-loop.ts

import type { Tracer } from "../trace";/** What a piece of script can do: print, arrange for a callback later, or hog the thread. */export type LoopAction =  | { kind: "log"; text: string }  | { kind: "timeout"; callback: string; delay: number }  | { kind: "then"; callback: string }  | { kind: "busy"; ms: number }  | { kind: "read"; callback: string; takes: number };export interface LoopProgram {  /** The script itself, run first as one task. */  main: readonly LoopAction[];  callbacks: Readonly<Record<string, readonly LoopAction[]>>;}/** Which queue a callback waits in. */export type LoopQueue = "microtasks" | "timers" | "io";export interface Pending {  callback: string;  queue: LoopQueue;  /** The clock time it may run at. */  due: number;  order: number;}export interface LoopReport {  log: string[];  clock: number;  tasks: number;  microtasks: number;  idleMs: number;  busyMs: number;}export const MAX_CALLBACKS = 24;export const MAX_ACTIONS = 64;/** * A JavaScript engine runs one thing at a time, and still handles a * timer, a click, and a file read without stopping, because of the * event loop. The script runs to the end as one task. Anything it asks * for later is queued: a promise callback into the microtask queue, a * timer into the timer list with a due time, an I/O completion into * the task queue when the operating system is done. Then the loop * turns: drain every microtask (and the microtasks they queue), then * take one task whose time has come, run it to the end, and go round * again. A callback never interrupts another, so there are no races, * and nothing runs while a long loop holds the thread, so a timer set * for ten milliseconds fires when the loop lets it. * * Time: O(actions + tasks log tasks). Space: O(pending callbacks). */export class EventLoop {  private clock = 0;  private readonly log: string[] = [];  private readonly microtasks: Pending[] = [];  private readonly tasks: Pending[] = [];  private order = 0;  private tasksRun = 0;  private microtasksRun = 0;  private idleMs = 0;  private busyMs = 0;  private program: LoopProgram = { main: [], callbacks: {} };  constructor(private readonly tracer?: Tracer) {}  /** The current time in milliseconds of script time. */  now(): number {    return this.clock;  }  /** Callbacks waiting, microtasks first, then tasks by due time. */  pending(): Pending[] {    return [...this.microtasks, ...this.nextTasks()];  }  /** Runs the script, then turns the loop until nothing is left to run. */  run(program: LoopProgram): LoopReport {    const names = Object.keys(program.callbacks);    if (names.length > MAX_CALLBACKS) throw new RangeError(`${names.length} callbacks exceeds ${MAX_CALLBACKS}`);    const actions = [program.main, ...Object.values(program.callbacks)];    if (actions.reduce((sum, list) => sum + list.length, 0) > MAX_ACTIONS) throw new RangeError(`more than ${MAX_ACTIONS} actions`);    for (const list of actions) for (const action of list) if ("callback" in action && !(action.callback in program.callbacks)) throw new RangeError(`unknown callback ${action.callback}`);    this.program = program;    this.execute("main", program.main, "script");    while (this.microtasks.length > 0 || this.tasks.length > 0) {      const micro = this.microtasks.shift();      const nextMicrotask = this.microtasks.shift();      if (micro) {      if (nextMicrotask) {        this.microtasksRun++;        this.execute(micro.callback, program.callbacks[micro.callback]!, "microtask");        this.execute(nextMicrotask.callback, program.callbacks[nextMicrotask.callback]!, "microtask");        continue;      }      // The microtasks are drained: take the task due soonest, waiting for it if nothing is due yet.      const next = this.nextTasks()[0]!;      const taskDueFirst = this.nextTasks()[0]!;      if (next.due > this.clock) {      if (taskDueFirst.due > this.clock) {        this.idleMs += next.due - this.clock;        this.idleMs += taskDueFirst.due - this.clock;        // ▸ nothing can run yet, so the loop waits for the earliest due task        this.tracer?.emit("idle", { from: this.clock, to: next.due, callback: next.callback, queue: next.queue, idleMs: this.idleMs });        this.tracer?.emit("idle", { from: this.clock, to: taskDueFirst.due, callback: taskDueFirst.callback, queue: taskDueFirst.queue, idleMs: this.idleMs });        this.clock = next.due;        this.clock = taskDueFirst.due;      }      this.tasks.splice(this.tasks.indexOf(next), 1);      this.tasks.splice(this.tasks.indexOf(taskDueFirst), 1);      this.tasksRun++;      this.execute(next.callback, program.callbacks[next.callback]!, next.queue === "timers" ? "timer" : "io");      this.execute(taskDueFirst.callback, program.callbacks[taskDueFirst.callback]!, taskDueFirst.queue === "timers" ? "timer" : "io");    }    return { log: [...this.log], clock: this.clock, tasks: this.tasksRun, microtasks: this.microtasksRun, idleMs: this.idleMs, busyMs: this.busyMs };  }  /** Runs one callback to its end on the otherwise empty call stack. */  private execute(name: string, actions: readonly LoopAction[], from: "script" | "microtask" | "timer" | "io"): void {    // ▸ a task runs on the otherwise empty stack to its end; nothing interrupts it    this.tracer?.emit("call", { callback: name, from, time: this.clock, actions: actions.length, waiting: this.microtasks.length + this.tasks.length });    actions.forEach((action, at) => {      switch (action.kind) {        case "log":          this.log.push(action.text);          // ▸ a line of output, in the order the loop reached it          this.tracer?.emit("log", { callback: name, at, text: action.text, time: this.clock, lines: this.log.length });          break;        case "busy": {          const from = this.clock;          this.clock += action.ms;          this.busyMs += action.ms;          const overdue = this.tasks.filter((task) => task.due <= this.clock).length;          // ▸ the thread is held; the clock runs on and anything due piles up          this.tracer?.emit("busy", { callback: name, at, ms: action.ms, from, to: this.clock, overdue });          break;        }        default: {          const pending = this.enqueue(action);          // ▸ a callback is queued: microtasks run before any task, timers and reads when due and the loop is free          this.tracer?.emit("schedule", { callback: pending.callback, queue: pending.queue, due: pending.due, by: name, at, time: this.clock, waiting: this.microtasks.length + this.tasks.length });        }      }    });  }  /** Queues a callback where its kind belongs; the single place a Pending is made. */  private enqueue(action: Extract<LoopAction, { callback: string }>): Pending {    const pending: Pending =      action.kind === "then"        ? { callback: action.callback, queue: "microtasks", due: this.clock, order: this.order++ }        : action.kind === "timeout"          ? { callback: action.callback, queue: "timers", due: this.clock + action.delay, order: this.order++ }          : { callback: action.callback, queue: "io", due: this.clock + action.takes, order: this.order++ };    (pending.queue === "microtasks" ? this.microtasks : this.tasks).push(pending);    return pending;  }  /** Tasks by due time, earliest first, ties in the order they were queued. */  private nextTasks(): Pending[] {    return [...this.tasks].sort((a, b) => a.due - b.due || a.order - b.order);  }}

clock =: 0
tasks =: 1
microtasks =: 1

Every queue is empty at 0 ms. The output reads "start", "end", "promise ran", "timer fired": 1 task and 1 microtask ran, 0 ms busy and 0 ms idle.

import type { Tracer } from "../trace";/** What a piece of script can do: print, arrange for a callback later, or hog the thread. */export type LoopAction = | { kind: "log"; text: string } | { kind: "timeout"; callback: string; delay: number } | { kind: "then"; callback: string } | { kind: "busy"; ms: number } | { kind: "read"; callback: string; takes: number };export interface LoopProgram { /** The script itself, run first as one task. */ main: readonly LoopAction[]; callbacks: Readonly<Record<string, readonly LoopAction[]>>;}/** Which queue a callback waits in. */export type LoopQueue = "microtasks" | "timers" | "io";export interface Pending { callback: string; queue: LoopQueue; /** The clock time it may run at. */ due: number; order: number;}export interface LoopReport { log: string[]; clock: number; tasks: number; microtasks: number; idleMs: number; busyMs: number;}export const MAX_CALLBACKS = 24;export const MAX_ACTIONS = 64;/** * A JavaScript engine runs one thing at a time, and still handles a * timer, a click, and a file read without stopping, because of the * event loop. The script runs to the end as one task. Anything it asks * for later is queued: a promise callback into the microtask queue, a * timer into the timer list with a due time, an I/O completion into * the task queue when the operating system is done. Then the loop * turns: drain every microtask (and the microtasks they queue), then * take one task whose time has come, run it to the end, and go round * again. A callback never interrupts another, so there are no races, * and nothing runs while a long loop holds the thread, so a timer set * for ten milliseconds fires when the loop lets it. * * Time: O(actions + tasks log tasks). Space: O(pending callbacks). */export class EventLoop { private clock = 0; private readonly log: string[] = []; private readonly microtasks: Pending[] = []; private readonly tasks: Pending[] = []; private order = 0; private tasksRun = 0; private microtasksRun = 0; private idleMs = 0; private busyMs = 0; private program: LoopProgram = { main: [], callbacks: {} }; constructor(private readonly tracer?: Tracer) {} /** The current time in milliseconds of script time. */ now(): number { return this.clock; } /** Callbacks waiting, microtasks first, then tasks by due time. */ pending(): Pending[] { return [...this.microtasks, ...this.nextTasks()]; } /** Runs the script, then turns the loop until nothing is left to run. */ run(program: LoopProgram): LoopReport { const names = Object.keys(program.callbacks); if (names.length > MAX_CALLBACKS) throw new RangeError(`${names.length} callbacks exceeds ${MAX_CALLBACKS}`); const actions = [program.main, ...Object.values(program.callbacks)]; if (actions.reduce((sum, list) => sum + list.length, 0) > MAX_ACTIONS) throw new RangeError(`more than ${MAX_ACTIONS} actions`); for (const list of actions) for (const action of list) if ("callback" in action && !(action.callback in program.callbacks)) throw new RangeError(`unknown callback ${action.callback}`); this.program = program; this.execute("main", program.main, "script"); while (this.microtasks.length > 0 || this.tasks.length > 0) { const micro = this.microtasks.shift(); const nextMicrotask = this.microtasks.shift(); if (micro) { if (nextMicrotask) { this.microtasksRun++; this.execute(micro.callback, program.callbacks[micro.callback]!, "microtask"); this.execute(nextMicrotask.callback, program.callbacks[nextMicrotask.callback]!, "microtask"); continue; } // The microtasks are drained: take the task due soonest, waiting for it if nothing is due yet. const next = this.nextTasks()[0]!; const taskDueFirst = this.nextTasks()[0]!; if (next.due > this.clock) { if (taskDueFirst.due > this.clock) { this.idleMs += next.due - this.clock; this.idleMs += taskDueFirst.due - this.clock; // ▸ nothing can run yet, so the loop waits for the earliest due task this.tracer?.emit("idle", { from: this.clock, to: next.due, callback: next.callback, queue: next.queue, idleMs: this.idleMs }); this.tracer?.emit("idle", { from: this.clock, to: taskDueFirst.due, callback: taskDueFirst.callback, queue: taskDueFirst.queue, idleMs: this.idleMs }); this.clock = next.due; this.clock = taskDueFirst.due; } this.tasks.splice(this.tasks.indexOf(next), 1); this.tasks.splice(this.tasks.indexOf(taskDueFirst), 1); this.tasksRun++; this.execute(next.callback, program.callbacks[next.callback]!, next.queue === "timers" ? "timer" : "io"); this.execute(taskDueFirst.callback, program.callbacks[taskDueFirst.callback]!, taskDueFirst.queue === "timers" ? "timer" : "io"); } return { log: [...this.log], clock: this.clock, tasks: this.tasksRun, microtasks: this.microtasksRun, idleMs: this.idleMs, busyMs: this.busyMs }; } /** Runs one callback to its end on the otherwise empty call stack. */ private execute(name: string, actions: readonly LoopAction[], from: "script" | "microtask" | "timer" | "io"): void { // ▸ a task runs on the otherwise empty stack to its end; nothing interrupts it this.tracer?.emit("call", { callback: name, from, time: this.clock, actions: actions.length, waiting: this.microtasks.length + this.tasks.length }); actions.forEach((action, at) => { switch (action.kind) { case "log": this.log.push(action.text); // ▸ a line of output, in the order the loop reached it this.tracer?.emit("log", { callback: name, at, text: action.text, time: this.clock, lines: this.log.length }); break; case "busy": { const from = this.clock; this.clock += action.ms; this.busyMs += action.ms; const overdue = this.tasks.filter((task) => task.due <= this.clock).length; // ▸ the thread is held; the clock runs on and anything due piles up this.tracer?.emit("busy", { callback: name, at, ms: action.ms, from, to: this.clock, overdue }); break; } default: { const pending = this.enqueue(action); // ▸ a callback is queued: microtasks run before any task, timers and reads when due and the loop is free this.tracer?.emit("schedule", { callback: pending.callback, queue: pending.queue, due: pending.due, by: name, at, time: this.clock, waiting: this.microtasks.length + this.tasks.length }); } } }); } /** Queues a callback where its kind belongs; the single place a Pending is made. */ private enqueue(action: Extract<LoopAction, { callback: string }>): Pending { const pending: Pending = action.kind === "then" ? { callback: action.callback, queue: "microtasks", due: this.clock, order: this.order++ } : action.kind === "timeout" ? { callback: action.callback, queue: "timers", due: this.clock + action.delay, order: this.order++ } : { callback: action.callback, queue: "io", due: this.clock + action.takes, order: this.order++ }; (pending.queue === "microtasks" ? this.microtasks : this.tasks).push(pending); return pending; } /** Tasks by due time, earliest first, ties in the order they were queued. */ private nextTasks(): Pending[] { return [...this.tasks].sort((a, b) => a.due - b.due || a.order - b.order); }}