liveBook · Manning

Headroom

As explained in JavaScript in Depth

Headroom is a reserved memory budget available for allocations during a garbage-collection cycle before stronger throttling is applied.

When allocation pressure and writes to long-lived objects rise together, garbage collection can repeatedly revisit objects and approach a death spiral. Headroom is the reserved memory budget that gives the collector time to finish before stronger throttling begins. section 9.3.4

At the start of a JSC collection cycle, the scheduler reserves headroom, typically 50% above the allocation threshold that triggered collection. As allocations consume it, the collector receives progressively more CPU time while the application receives less. Exhausting the budget stops the application until collection finishes. section 9.3.4

A cache that consumes its budget

A long-lived session store can trigger the problem: every request writes fresh request objects, copied headers, and history arrays into old-generation session objects. Write barriers force revisits while young-generation allocation continues, consuming headroom and increasing latency. section 9.3.4

const sessions = new Map();  #A
function handleRequest(req) {
  let session = sessions.get(req.sessionId);
  if (!session) {
    session = { id: req.sessionId, created: Date.now() };
    sessions.set(req.sessionId, session);
  }
 
  // Every request mutates the long-lived session object
  // with fresh short-lived objects
  session.lastAccess = Date.now();
  session.lastRequest = {  #B
    url: req.url,
    headers: { ...req.headers },
    timestamp: Date.now(),
  };
  session.history = (session.history || [])
    .slice(-99)
    .concat([req.url]);  #C
 
  return buildResponse(req, session);
}

Inspect the request handler to see persistent sessions receive newly allocated objects on every request. section 9.3.4

How JavaScript in Depth covers it

How deep it goes
Defines the budget, its typical size, progressive CPU tradeoff, and stop-the-application behavior, but not its implementation algorithm.
Examples
Uses an in-memory session cache that mutates old-generation objects with freshly allocated request data.
What it assumes
Assumes familiarity with garbage collection, generations, allocation, and write barriers.
What you can do after
Diagnose GC latency by relating aggressive allocation and old-object mutation to progressive application throttling.
How it connects
Connects garbage collection with concurrent marking, write barriers, allocation pressure, throttling, and latency.

Also explained in

Compare how 4 books explain headroom →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of JavaScript in Depth. The section links point to the parts of the book it draws on.