Suspending frames: generators & async functions

Pause a function without losing it

A normal function call runs from top to bottom. It starts, runs its lines, and returns. When it returns, its local variables are thrown away.

Two kinds of functions can stop in the middle and continue later:

• A generator function pauses at each yield.
• An async function pauses at each await.

While one of them is paused, other code runs. Later, it continues from the exact line where it stopped, with the same values in its variables.

This lesson shows how a JavaScript engine keeps that saved state. To review the code you write first, see generators, generators for control flow, async/await, iteration protocols, microtasks, and transpilers and polyfills. For how normal calls work, see the call stack and stack and heap.

Normal frames vs suspended frames

When you call a function, the engine makes a stack frame for it. A stack frame is the engine's notes for one running call. It holds:

• the line the call is running now,
• the call's local variables and parameters,
• where to go back to when the call returns.

The frames sit on the call stack, a pile of the calls that are running right now. In a normal call, the frame lives only while the call runs. When the function returns, its frame is removed from the pile.

A paused generator can't throw its frame away. In the next section, line 4 hands out a ticket number and pauses. When you call next() later, line 5 still needs the same token value. So the engine copies the values it still needs into an object that stays in memory. When the function continues, the engine builds a new stack frame from those saved values.

The table shows four kinds of calls. Read across each row: where the values live while the call runs, and what happens after it gives control back.

The rule that a paused function continues correctly comes from the JavaScript language itself. How the saved values are stored is up to each engine. This lesson looks at V8, the JavaScript engine inside Chrome and Node. The lesson's tests check the names V8 uses for these steps. They never check memory addresses, because those change on every run.

Saving a generator's frame in an object

A generator function is written with function*. Calling it does not run its body. Instead, it gives back a generator object. You run the body by calling next() on that object.

Inside the body, a yield expression sends a value out to the caller and pauses the body on that line. While the body is paused, it is not on the call stack. So the values it will need later are saved in the generator object.

The generator object lives on the heap. The heap is the part of memory where objects live. An object stays there as long as some code can still reach it.

1function* ticketCounter(start) {2  let token = start;3  while (token < start + 3) {4    const command = yield token;5    token += command === "skip" ? 2 : 1;6  }7  return "closed at " + token;8}9 10const tickets = ticketCounter(1440);Run11tickets.next();12tickets.next("skip");13tickets.next();

Step through the code. Line by line:

1. Line 10 makes the generator object. The body has not run yet. Its state is suspended-start, which means "made, but not started".
2. Line 11 calls next() for the first time, so the body starts at the top.
3. Line 2 stores 1440 in token.
4. Line 4 yields 1440 and pauses. The generator object keeps token and the line to continue from.
5. Line 12 calls next("skip"). The body continues at line 4. The paused yield finishes, and its result is "skip", so command is "skip".
6. Line 5 adds 2 to the same token, so it becomes 1442. Line 4 yields 1442 and pauses again.
7. Line 13 calls next() with no value. Line 5 adds 1, so token is 1443. The loop stops, and line 7 returns "closed at 1443". The generator is finished.

Seeing it in V8 with Node

V8 does not run your code exactly as you wrote it. First it turns each function into bytecode: a list of small, simple instructions. Node can print that list with the --print-bytecode flag.

The lesson test runs the code below in Node 22, which uses V8 12.4. It looks for three instruction names:

• SwitchOnGeneratorState jumps to the right line when the body starts or continues.
• SuspendGenerator saves the values into the generator object and pauses.
• ResumeGenerator brings the saved values back when the body continues.

1function* ticketCounter(start) {2  let token = start;3  yield token;4  token += 1;5  return token;6}7 8const gen = ticketCounter(41);9gen.next();10gen.next();

1$ node --print-bytecode --print-bytecode-filter=ticketCounter generator-probe.mjs2[generated bytecode for function: ticketCounter]3SwitchOnGeneratorState ...4SuspendGenerator ...5ResumeGenerator ...

You can also print the generator object itself. %DebugPrint is a V8 tool for looking inside values. It works only when Node starts with the --allow-natives-syntax flag. Line 9 prints the new generator object. Line 10 starts it, and line 11 prints it again while it is paused. The test looks for these words in the output:

• JSGeneratorObject is V8's name for a generator object.
• continuation is the resume point, stored as a number.
• register file is where V8 keeps the saved local values.

1function* ticketCounter(start) {2  let token = start;3  yield token;4  token += 1;5  return token;6}7 8const gen = ticketCounter(41);9%DebugPrint(gen);10gen.next();11%DebugPrint(gen);

1DebugPrint: ... [JSGeneratorObject]2 - resume mode: .next()3 - continuation: 0 (suspended)4 - register file: ...5DebugPrint: ... [JSGeneratorObject]6 - continuation: 1 (suspended)

Resuming with next(), return(), and throw()

The generator object has three methods. Each one continues the paused body in a different way:

• next(value) continues normally. After the first call, value becomes the result of the paused yield.
• return(value) finishes the generator with value. Any finally block runs first.
• throw(error) continues by throwing error at the paused yield. A try/catch inside the generator can catch it.

1function* ticketCounter(start = 1440) {2  let token = start;3  try {4    while (token < start + 3) {5      const command = yield token;6      token += command === "skip" ? 2 : 1;7    }8    return "closed at " + token;9  } catch (error) {10    return "handled " + error.message;11  }12}13 14const counter = ticketCounter();15counter.next();16counter.next("skip");

Each button calls a real method on a real generator object. The results come from those calls. The state name is our own label, because browsers don't let code read a generator's state.

1function* station() {2  try {3    yield "boarding";4    yield "moving";5  } catch (error) {6    yield "caught " + error.message;7  } finally {8    console.log("cleanup");9  }10  return "done";11}12 13let trip = station();14console.log(JSON.stringify(trip.next()));15console.log(JSON.stringify(trip.throw(new Error("delay"))));16console.log(JSON.stringify(trip.next()));17console.log(JSON.stringify(trip.next()));18 19trip = station();20console.log(JSON.stringify(trip.next()));21console.log(JSON.stringify(trip.return("closed")));22console.log(JSON.stringify(trip.next()));

Line by line:

1. Line 14 starts the generator. It pauses at line 3 and gives "boarding".
2. Line 15 throws an error at the paused yield. The catch block on line 5 catches it, and line 6 yields "caught delay".
3. Line 16 continues. The finally block prints cleanup, and line 10 returns "done".
4. Line 17 calls next() on a finished generator. It prints {"done":true}. JSON.stringify leaves out value because it is undefined.
5. Lines 19 and 20 make a new generator, which pauses at "boarding".
6. Line 21 calls return("closed"). The finally block prints cleanup, and the generator finishes with "closed".
7. Line 22 calls next() on the finished generator and prints {"done":true} again.

How await suspends and resumes

An async function always returns a promise. A promise is an object that stands for a value that may arrive later. A promise settles when it gets its value or fails.

When you call an async function, its body starts right away, like a normal function. It runs until it reaches an await. If the promise after await has not settled yet, the function pauses there, and its frame is saved.

When the promise settles, JavaScript adds a job to the microtask queue. The microtask queue is a waiting line of small jobs. JavaScript runs them in order, as soon as the current script finishes. That job continues the paused function.

1async function resumeAfterAwait(gate) {2  console.log("async start");3  const token = await gate;4  console.log("async resumed " + token);5  return token + 1;6}7 8let release;9const gate = new Promise((resolve) => { release = resolve; });Run10console.log("script start");11const resultPromise = resumeAfterAwait(gate);12resultPromise.then((value) => console.log("then " + value));13queueMicrotask(() => { console.log("settle promise"); release(41); });14queueMicrotask(() => console.log("already queued microtask"));15console.log("script end");

The order of the printed lines is the key. Line by line:

1. Line 10 prints script start.
2. Line 11 calls the async function. Line 2 prints async start right away.
3. Line 3 pauses at await, because gate has not settled.
4. Lines 13 and 14 put two jobs in the microtask queue. Line 15 prints script end.
5. The first job prints settle promise and calls release(41). That settles gate and puts the paused function at the back of the line.
6. The second job was already in line, so already queued microtask prints next.
7. Only then does the function continue. Line 4 prints async resumed 41.

V8 pauses and continues an async function with the same instructions it uses for generators. The test prints the bytecode for the small async function below and looks for these names. _AsyncFunctionAwaitUncaught is V8's own helper for one await.

1async function fetchTicket(promise) {2  const value = await promise;3  return value + 1;4}5 6fetchTicket(Promise.resolve(41));

1$ node --print-bytecode --print-bytecode-filter=fetchTicket async-probe.mjs2[generated bytecode for function: fetchTicket]3SwitchOnGeneratorState ...4_AsyncFunctionAwaitUncaught ...5SuspendGenerator ...6ResumeGenerator ...

That is how V8 does it inside. The rule every engine follows is simpler: await pauses the async function, lets the current script finish, and continues from a microtask after the promise settles.

Generator objects and their state

The ECMAScript spec is the official rulebook for JavaScript. It says each generator object has a hidden state called [[GeneratorState]]. The double square brackets mean your code can't read it. The state is one of four values:

• suspended-start: the object is made, but the body has not started.
• executing: the body is running right now.
• suspended-yield: the body is paused at a yield.
• completed: the generator is finished.

You can't read the state, but you can see it from how the generator behaves.

1let self;2function* reentrantProbe() {3  try {4    self.next();5  } catch (error) {6    console.log(error.name + ": " + error.message);7  }8  yield "first pause";9  return "finished";10}11 12self = reentrantProbe();13const first = self.next();14console.log(first.value, first.done);15const second = self.next();16console.log(String(second.value), second.done);17const third = self.next();18console.log(String(third.value), third.done);

Line by line:

1. Line 12 makes the generator. It is suspended-start.
2. Line 13 starts the body. Now it is executing.
3. Line 4, inside the body, calls next() on the same generator. It is already running, so V8 throws TypeError: Generator is already running. Line 6 prints that message.
4. Line 8 yields "first pause". Now it is suspended-yield. Line 14 prints first pause false.
5. Line 15 continues the body, and line 9 returns "finished". Now it is completed. Line 16 prints finished true.
6. Line 17 calls next() on the finished generator. Line 18 prints undefined true.

The table has one row per state. Read across each row: what the state means, and what happens when you call a method in that state.

State machines in transpiled code

Some older browsers don't understand function* or async. A transpiler is a tool that rewrites new code into older code that runs everywhere. Tools such as regenerator and TypeScript's __generator helper turn a generator into a state machine. A state machine is an object that remembers which step it is on and does a different job for each step. It works like this:

• The saved local values live in normal variables.
• A variable, such as label, remembers where to continue.
• On each next() call, a switch statement jumps to the right step.

1function* lunchOrder() {2  const instruction = yield "cut fabric";3  yield instruction === "rush" ? "stitch now" : "stitch tomorrow";4  return "ready";5}6 7function createLunchOrderMachine() {8  let label = 0;9  let instruction;10  return {11    next(sent) {12      while (true) {13        switch (label) {14          case 0:15            label = 1;16            return { value: "cut fabric", done: false };17          case 1:18            instruction = sent;19            label = 2;20            return {21              value: instruction === "rush" ? "stitch now" : "stitch tomorrow",22              done: false,23            };24          case 2:25            label = 3;26            return { value: "ready", done: true };27          default:28            return { value: undefined, done: true };29        }30      }31    },32    [Symbol.iterator]() { return this; },33  };34}35 36function collect(iterator) {37  return [iterator.next(), iterator.next("rush"), iterator.next(), iterator.next()]38    .map((step) => String(step.value) + ":" + step.done)39    .join(" | ");40}41 42console.log(collect(lunchOrder()));43console.log(collect(createLunchOrderMachine()));

Line by line:

1. Lines 1 to 5 are the generator, written the normal way.
2. Lines 7 to 34 do the same job by hand. Line 8 makes label, which remembers where to continue. Line 9 makes instruction, the saved local value.
3. Line 13 switches on label. Each case sets label to the next step, then returns a result.
4. Line 18 saves the value sent in, just like the paused yield on line 2 receives it.
5. The collect function on lines 36 to 40 calls next() four times. It sends "rush" on the second call.
6. Lines 42 and 43 run collect on both versions. Both print the same line: cut fabric:false | stitch now:false | ready:true | undefined:true.

Practical use

Paused functions show up whenever JavaScript waits without freezing the page. For example:

• An async function waits for a network request, a permission prompt, a stream read, or a timer.
• A generator, or an async generator (a generator that can also await), hands out values one at a time, when the caller asks.

The useful habit is not to avoid pausing. It is to know what a paused function keeps, and to measure before you rewrite clear code.

Each row is a real situation. Read across: what pausing gives you there, and a good habit to keep.

A paused async function keeps every value it still needs. If it holds a large object, that object stays in memory until the function finishes, or until no code can reach the function any more. That is expected. It is not a memory leak by itself. If memory matters, measure it with the browser's memory tools, and cancel work you no longer need.

Common misconceptions

• "yield keeps the whole call stack running." No. yield hands control back to the caller. Only the generator's own saved values are kept.
• "await starts another thread." No. A thread would be a second worker running code at the same time. await only pauses the async function. It continues later from a microtask, on the same thread.
• "A paused local variable is a memory leak." No. It is kept on purpose, because the function may still need it. It becomes a leak only if something keeps the generator or promise reachable forever.
• "Transpiled state machines are fake." No. They are real JavaScript that runs the same steps. They just show the saved values and the label in plain code.
• "V8's instruction names are part of JavaScript." No. They show how this V8 version works. The rules of the language come from the ECMAScript spec.

These ideas are easy to mix up. Read across each row: what the idea is, and what it is not.

Practice exercises

function* ticketCounter(start) {
  let token = start;
  while (token < start + 3) {
    const command = yield token;
    token += command === "skip" ? 2 : 1;
  }
  return "closed at " + token;
}

const tickets = ticketCounter(1440);
console.log(tickets.next().value);
console.log(tickets.next("skip").value);
console.log(tickets.next().value);

function* takeThree(items) {
  // yield the first three items, then return "done"
}

const run = takeThree(["A", "B", "C", "D"]);
console.log(run.next().value);
console.log(run.next().value);
console.log(run.next().value);
console.log(run.next().value);

function* takeThree(items) {
  for (let i = 0; i < 3 && i < items.length; i += 1) {
    yield items[i];
  }
  return "done";
}

function* greeter() {
  const name = yield "ready";
  return name ?? "no name";
}
const gen = greeter();
console.log(gen.next("Asha").value);
console.log(gen.next().value);

let release;
const gate = new Promise((resolve) => { release = resolve; });
async function demo() {
  const value = await gate;
  console.log("async resumed " + value);
}
demo();
queueMicrotask(() => { console.log("settle promise"); release(41); });
queueMicrotask(() => console.log("already queued microtask"));

Check your understanding

Key takeaways

• A normal stack frame is removed when its function returns. A suspended frame keeps the values the function still needs, plus the line to continue from.
• A generator object holds a paused generator's saved values. Calling next(), return(), or throw() on it continues the body.
• In V8 12.4, generators and async functions use the same pause and continue instructions.
• An async function starts right away, pauses at await, and continues from a microtask after the promise settles.
• A transpiled state machine shows the same idea in plain code: a label variable and a switch.

Previous lesson: Async stack traces. Up next: Exceptions & unwinding. There, a thrown error stops functions by removing their frames, instead of saving them.