Stack frames & calling conventions

Each call gets its own record

When one function calls another, the first function stops and waits. The function that makes the call is the caller. The function being called is the callee.

The engine is the program that runs your JavaScript. In Chrome and Node, the engine is called V8. While the caller waits, the engine must remember a few things:

• where to go back to in the caller,
• the values passed in, called the arguments,
• the variables made inside the call, called the local variables,
• the outer variables the function can still use.

You met the simple version of this in Call stack, Execution context, and Stack and heap. This lesson keeps that simple picture and adds real facts about V8. The last lesson, Heap layout, showed where long-lived values are kept. This lesson is about the short-lived records made while calls run.

You don't need to learn every byte of V8's frames. After this lesson you can:

• read a stack trace, the list of calls printed with an error,
• explain what happens with missing and extra arguments,
• explain why fast, optimized code can still be debugged,
• see where the next lesson, on stack overflow, starts.

The machine stack and the JavaScript stack

There are two stacks to keep apart:

• The machine stack is a block of the computer's memory. V8's own code and the fast code it makes for your functions use it.
• The JavaScript stack is the list of your JavaScript calls that are still running. You see it in DevTools and in an error's stack text.

In V8 the two are linked, but they are not the same thing.

In Node, V8 keeps JavaScript calls on the machine stack, and that stack has a fixed size. Node's --stack-size flag sets the size. A flag is an option you type after node on the command line.

The code below has a function that calls itself again and again. This is called recursion. It counts the calls until the engine runs out of room and throws a RangeError.

1let depth = 0;2function dive() {3  depth += 1;4  dive();5}6 7try {8  dive();9} catch (error) {10  console.log(error.name, depth);11}

Line 1 starts a counter at 0. Line 3 adds 1 on every call. Line 4 calls dive again, so it never stops on its own. Line 8 makes the first call. Line 9 catches the error, and line 10 prints its name and the count.

Four words in this lesson sound alike. The table says what each one means and what it keeps. Read each row from left to right.

What a stack frame holds

Let's follow a small checkout. The cart costs ₹150. The shop adds 18% GST, a tax on the price, so the total is ₹177. The code has three functions, and each one calls the next: checkout calls total, and total calls addTax.

1function addTax(amount) {2  const rate = 0.18;3  const tax = amount * rate;4  return amount + tax;5}6 7function total(items) {8  let sum = 0;9  for (const item of items) {10    sum += item.price;11  }12  return addTax(sum);13}14 15function checkout(cart) {16  const finalAmount = total(cart);17  return `Pay ₹${finalAmount.toFixed(2)}`;18}19 20console.log(checkout([{ name: "notebook", price: 100 }, { name: "pen", price: 50 }]));Run

This step-through is a simple model. It is not a view of V8's real memory. Line 20 calls checkout. Line 16 calls total. Line 12 calls addTax. Each call gets its own frame. When a call returns, its frame is removed, and the line that was waiting goes on.

A frame has several parts, called slots. One slot, the context, points to where the function's outer variables are kept. A closure, a function that still uses variables from an outer function, needs it. In the table, each row names a slot, says what it is for, and says where it is kept.

A frame doesn't hold big things like arrays. In total, the frame keeps the number sum. For items, it keeps only a link to the cart array. The array itself lives in the heap, the memory area for objects that can last longer than one call.

How V8 starts a function call

A calling convention is a fixed plan for where each piece of a call goes. The plan covers:

• the object that becomes this, called the receiver,
• the arguments,
• the return address,
• a link to the caller's frame,
• a few fixed slots at the start of the frame, called the frame header.

V8 changes this plan between versions. What your JavaScript sees must stay the same.

The V8 article "Faster JavaScript calls" explains two changes. First, V8 now puts the arguments on the stack in reverse order. Second, it removed an extra helper frame, the arguments adaptor frame. That frame used to fix up calls with too few or too many arguments.

Now the frame of the called function keeps the real number of arguments. With that number, V8 can still build arguments and rest parameters, and it can clean up after the call.

V8 first turns each function into bytecode: short, simple instructions that it runs one at a time. The code below asks Node to print the bytecode for addTax. It works in Node only, not in the browser.

1function addTax(amount) {2  const rate = 0.18;3  return amount + amount * rate;4}5 6addTax(150);

Too few or too many arguments

In JavaScript you can pass fewer or more arguments than a function names. This is a rule of the language, not a V8 trick:

• A missing parameter gets the value undefined.
• An extra value has no name, but you can still read it. Every normal function has arguments, a list-like object with every value passed in, in order.

1function makeBooking(passenger, city) {Run2  const passengerName = passenger ?? "Guest";3  const destination = city ?? "Jaipur";4  const extra = arguments[2] ?? "no extra";5  return `${passengerName} -> ${destination}; extra: ${extra}; supplied: ${arguments.length}`;6}7 8console.log(makeBooking("Asha"));9console.log(makeBooking("Ravi", "Kochi", "window seat"));

1function receiptLine(item, quantity) {2  return {3    declared: receiptLine.length,4    supplied: arguments.length,5    item,6    quantity,7    extras: Array.from(arguments).slice(2),8  };9}10 11receiptLine("chai", 2, "GST", "takeaway");

Now check the same facts with plain code. inspectCall.length is the number of parameters the function names. arguments.length is the number of values this call passed. The first call leaves second as undefined. The second call passes three values, so "window seat" is in arguments[2].

1function inspectCall(first, second) {2  console.log("declared", inspectCall.length);3  console.log("supplied", arguments.length);4  console.log("first", first);5  console.log("second", second);6  console.log("extra", arguments[2]);7}8 9inspectCall("Asha");10inspectCall("Ravi", "Kochi", "window seat");

A rest parameter, written ...rest, collects the extra values into an array. A function's length stops counting at the rest parameter, so collect.length is 1.

1function collect(first, ...rest) {2  console.log(collect.length);3  console.log(first);4  console.log(rest.join("|"));5}6 7collect("chai", "samosa", "jalebi");

Simple frames and fast frames

V8 first runs your code with Ignition, its interpreter. An interpreter reads bytecode and does one step at a time. Its frames always have the same shape:

• a header with the context, the function, its bytecode, the current position in the bytecode, and the argument count,
• then a row of registers: small slots that hold the function's local values.

When a function runs many times, V8 may compile it with TurboFan, its optimizing compiler. TurboFan makes fast machine code. It chooses where each value goes. Some values stay inside the processor. Others are saved in frame slots called spill slots.

Fast code makes guesses about your values. If a guess turns out wrong, V8 switches back to the slow, safe version. This is called deoptimizing. To do it, TurboFan keeps notes on how to rebuild every JavaScript value. The same notes help V8 build stack traces.

V8 has several kinds of frames. Each row of the table says what one kind holds and why it exists.

Copied-in functions still show in stack traces

Inlining means the optimizing compiler copies a small function's code into the function that calls it. Then the machine doesn't need a separate call, so the copied function may get no frame of its own.

V8 still keeps notes about the copy. When it builds a stack trace, it uses the notes to list the copied function as if it had been called.

The code below works in Node only. The lines that start with % are special V8 commands. They work only with the --allow-natives-syntax flag. Here they make V8 optimize checkout and report whether it is optimized.

1function gstLine(amount) {2  return captureStack(amount * 1.18);3}4 5function captureStack(total) {6  return new Error("receipt " + total).stack;7}8 9function checkout(amount) {10  return gstLine(amount);11}12 13%PrepareFunctionForOptimization(gstLine);14%PrepareFunctionForOptimization(captureStack);15%PrepareFunctionForOptimization(checkout);16for (let i = 0; i < 10000; i += 1) checkout(i);17%OptimizeFunctionOnNextCall(checkout);18const stack = checkout(100);19const status = %GetOptimizationStatus(checkout);20console.log("status", status);21console.log("optimized", Boolean(status & (1 << 4)));22console.log(stack.split("\n").filter((line) => /captureStack|gstLine|checkout/.test(line)).join("\n"));

V8 also limits how many lines a stack trace shows. A stack trace is text made for debugging. It is not a copy of memory.

The code below makes three nested calls and counts the at lines in the trace. With Node's --stack-trace-limit=2 flag, it prints frames 2. A later lesson on the stack trace API goes further.

1function leaf() {2  return new Error("limit").stack;3}4function middle() {5  return leaf();6}7function top() {8  return middle();9}10 11const frames = top().split("\n").filter((line) => line.trim().startsWith("at "));12console.log("frames", frames.length);

Using frames when you debug

You will use this most when you debug. When an error points at a helper function, read the top line of the stack trace first. Then go down to the functions that called it. At each step, check what was passed in:

• too few arguments,
• too many arguments,
• an object that some other code changed.

1function formatReceipt(items, coupon) {2  const subtotal = items.reduce((sum, item) => sum + item.price, 0);3  const discount = coupon ? subtotal * coupon.percent : 0;4  return subtotal - discount;5}6 7console.log(formatReceipt([{ price: 500 }, { price: 250 }], { percent: 0.1 }));8console.log(formatReceipt([{ price: 500 }, { price: 250 }], null));

Line 2 adds up the prices and keeps the result in the local variable subtotal. Line 3 takes off a discount only if a coupon was passed. Line 7 passes a 10% coupon and prints 675. Line 8 passes null and prints 750.

• Read a stack trace as a list of your JavaScript calls, not as raw machine memory.
• Use arguments.length or a rest parameter when a function really needs to know how many values were passed.
• Remember that a local variable can point to an object in the heap, and that object can outlive the frame.
• Measure before you change code because of a guess about frames. Many arguments alone don't make code slow.

Common misconceptions

• "The stack trace is the stack." A stack trace is text that V8 builds from frames and its notes.
• "A frame holds every value its function uses." Objects live in the heap. A frame can point to them, and they can last longer than the frame.
• "fn.length tells me how many arguments were passed." It counts the parameters the function names. arguments.length counts the values passed in this call.
• "Optimized code can't be debugged." V8 keeps notes so tools can rebuild the JavaScript values and calls.
• "V8's frame layout is part of JavaScript." The language rules are written in the spec. The frame layout is V8's own choice.

Some pairs of ideas are easy to mix up. Each row says what one idea means and what it is not.

Practice exercises

function inspectCall(first, second) {
  console.log(inspectCall.length);
  console.log(arguments.length);
  console.log(second);
}
inspectCall("Asha");

function route(passenger, city) {
  console.log(route.length);
  console.log(arguments.length);
  console.log(arguments[2]);
}
route("Ravi", "Kochi", "window seat");

function priceWithDiscount(price, percent = 0) {
  if (arguments.length < priceWithDiscount.length) return "missing";
  return price - price * percent;
}
console.log(priceWithDiscount(1000));

function priceWithDiscount(price, percent = 0) {
  if (arguments.length === 0) return "missing price";
  return price - price * percent;
}
console.log(priceWithDiscount(1000));

Check your understanding

Key takeaways

• A stack frame is the record for one running call: where to go back to, the arguments, the local variables, and links.
• The machine stack, the JavaScript stack, the heap, and a stack trace are linked, but they are four different things.
• Ignition frames always have the same shape. TurboFan frames use slots the compiler picks, plus notes for going back and for debugging.
• A missing parameter is undefined. An extra value is still in arguments. Modern V8 no longer needs an arguments adaptor frame.
• A function copied into its caller can still show up in a V8 stack trace.

In one line: a function call is more than a jump. It makes a short-lived record that lets the engine go back, help you debug, and keep JavaScript's rules.

Next, Stack limits & stack overflow shows what happens when too many frames pile up, and how to rewrite risky recursion.