Reference counting & cycles

The simple counting idea

Reference counting is a memory strategy that keeps a number for each object: how many references currently point at it. When the number reaches zero, the object can be freed.

This follows Why garbage collection?. That lesson used roots and tracing. Here, start with the simpler question: how many references point at one object?

A reference is a value that lets code reach an object. A variable, an object property, an array entry, or a closure can hold one. Engines keep this bookkeeping private, so the counts on this page are a teaching model rather than an API you can inspect in DevTools.

Counting has one appealing property: an object can be freed as soon as its last reference disappears. That immediate result is easy to picture. The rest of the lesson asks why that simple rule is not enough for every object graph.

How reference counting works

1let user = { name: "Asha" };2let admin = user;3user = null;4console.log(admin.name);

Line 1 creates the object, so its teaching count is 1. Line 2 makes admin another reference, so the count is 2. Line 3 removes user, leaving count 1. Line 4 prints Asha because admin still points at the object.

Notice what did not happen on line 3: JavaScript did not erase the object or change its name. It only changed which value the user variable holds. The separate admin variable still has the original object value.

1function readTea() {2  const order = { drink: "tea" };3  console.log(order.drink);4}5 6readTea();7console.log("function finished");

Line 2 creates an order object and line 3 reads it, so the program prints tea. When line 6 runs, readTea has returned and its local name is gone. In a counting design, that local reference would be released; if it was the last one, the object could be freed.

This is not a promise that a JavaScript engine frees memory exactly when a function returns. It is the clean ownership story that makes reference counting attractive: remove the last string, then release the balloon.

Aliases add and remove references

1const counts = new Map([["user", 1]]);2 3function retain(name) {4  counts.set(name, (counts.get(name) ?? 0) + 1);5  return counts.get(name);6}7 8function release(name) {9  counts.set(name, (counts.get(name) ?? 0) - 1);10  return counts.get(name);11}12 13console.log(retain("user"));14console.log(release("user"));

Line 1 starts user at 1. Lines 3 to 5 add one for a new alias. Lines 8 to 10 remove one when an alias goes away. The code prints 2, then 1.

The Map stores a name and a number only so the change is visible. A real engine associates bookkeeping with an object, not the text user. The model is useful because it makes the two ordinary operations explicit: retain when an alias arrives, release when it leaves.

1const counts = new Map([["user", 1]]);Run2 3function retain(name) {4  counts.set(name, (counts.get(name) ?? 0) + 1);5  return counts.get(name);6}7 8function release(name) {9  counts.set(name, (counts.get(name) ?? 0) - 1);10  return counts.get(name);11}12 13console.log(retain("user"));14console.log(release("user"));

1const cart = { items: ["tea"] };2const shelf = [];3 4shelf.push(cart);5console.log(shelf.length);6 7shelf.pop();8console.log(shelf.length);

Line 1 creates cart. Line 4 puts that same object into shelf, so the array has another reference and line 5 prints 1. Line 7 removes the entry, and line 8 prints 0 because the array is empty again.

The cart still has its variable reference after pop(). This is the same alias rule in a more realistic form: removing one array entry removes one route to an object, not every route.

Cycles that never free

1let asha = { name: "Asha" };2let ravi = { name: "Ravi" };3asha.friend = ravi;4ravi.friend = asha;5asha = null;6ravi = null;7console.log("outside references removed");

Lines 1 and 2 create Asha and Ravi. Lines 3 and 4 make them point at each other. Lines 5 and 6 remove the outside names. The code prints outside references removed, but a pure counter still sees one reference into each object: the other object.

That is the cycle problem. Nobody outside can use either object, yet neither count reaches zero.

A cycle is a group of references that eventually leads back to where it started. Here Asha points to Ravi and Ravi points to Asha. After the two outside variables are cleared, the pair is detached from the program but each object still receives one internal reference.

1const order = { next: null };2const receipt = { next: null };3const coupon = { next: null };4 5order.next = receipt;6receipt.next = coupon;7console.log("chain attached");8 9order.next = null;10console.log("head released");

Lines 1 to 3 make three objects. Lines 5 and 6 link them as order, receipt, then coupon, and line 7 prints chain attached. When line 9 removes the head link, a counting collector can release the order; releasing it removes the receipt's only incoming link, then the coupon's. That is a cascade.

A chain differs from the Asha/Ravi pair because its arrows do not loop back. Once the head reaches zero, each later object can also reach zero. In a cycle, releasing one object never begins because both counts are stuck at one.

QuickJS and cycle collection

QuickJS uses reference counting for predictable freeing and adds a cycle collector. It looks for a group that may only be referenced by itself, subtracts links inside that group, and collects the group when no outside references remain.

The word outside matters. The collector first suspects a group, then asks which references enter it from somewhere else. It temporarily ignores links that stay inside the group. Asha has one total incoming link and one link from Ravi, so its outside count is zero in the two-object example.

This is a simplified teaching model, not QuickJS source code. The real engine must find candidate groups and do the work safely while programs create and remove values. The model keeps one idea visible: a link within a closed group is not proof that an outside owner exists.

1const group = {Run2  asha: { count: 1, inside: 1 },3  ravi: { count: 1, inside: 1 },4};5 6function outsideCount(item) {7  return item.count - item.inside;8}9 10console.log(outsideCount(group.asha), outsideCount(group.ravi));

1const group = {2  asha: { count: 1, inside: 1 },3  ravi: { count: 1, inside: 1 },4};5 6function outsideCount(item) {7  return item.count - item.inside;8}9 10console.log(outsideCount(group.asha), outsideCount(group.ravi));

A historical Internet Explorer leak

const button = document.createElement("button");
const details = { order: "tea" };

button.onclick = function showOrder() {
  button.title = details.order;
};

button.onclick = null;
button.remove();
console.log("handler removed");

This is historical. Old Internet Explorer used reference counting for DOM objects while JavaScript objects were traced by a different collector. A DOM element and a closure could make a cycle across those two systems, so neither system freed it.

Step by step, line 1 creates a DOM button and line 2 creates data. Line 4 stores a handler on the button. The handler can read button and details, so the DOM side and JavaScript side keep a path to each other. The old collectors did not agree on how to break that cross-system cycle.

The historical fix was explicit cleanup. Line 7 removes the handler and line 8 removes the element; line 9 prints handler removed. Modern browsers use a unified tracing approach across DOM and JavaScript, but removing listeners when UI is removed is still good application ownership, especially when a long-lived page retains them.

Modern browsers trace across DOM and JavaScript objects, so this code does not leak for that historical reason today.

Why most engines trace instead

Every assignment can need a count update. Counts use extra memory. Cycles need a second algorithm anyway. Tracing does work at collection time, but detached cycles naturally have no path from roots.

A counter pays small work on ordinary mutations. Copying a reference usually increments one count; overwriting or removing it usually decrements one. A tracing collector leaves those assignments mostly alone, then later walks outward from roots during collection. The work moves from each assignment to a collection phase.

1const assignments = 3;2const countUpdates = assignments * 2;3 4console.log("count updates", countUpdates);5console.log("trace later", "walk from roots");

Line 1 chooses three assignment events. Line 2 models two count changes per event and line 4 prints count updates 6. Line 5 prints trace later walk from roots: a trace is not free, but its main graph walk happens during collection instead.

Neither approach is automatically best. Reference counting can free simple objects promptly and is useful in some runtimes. Tracing naturally handles cycles, which is why it is the usual foundation for modern JavaScript engines.

V8 collects a detached cycle

const wait = () => new Promise((resolve) => setTimeout(resolve, 0));

function detachedCycle() {
  let asha = { friend: null };
  let ravi = { friend: asha };
  asha.friend = ravi;
  const weak = new WeakRef(asha);
  asha = null;
  ravi = null;
  return weak;
}

const weak = detachedCycle();
let collected = false;
for (let attempt = 0; attempt < 8; attempt += 1) {
  await wait();
  globalThis.gc();
  await wait();
  if (weak.deref() === undefined) {
    collected = true;
    break;
  }
}
process.stdout.write("V8 tracing cycle collected " + collected + "\n");

For weak references in application code, use WeakRef and finalization.

Practical developer habits

JavaScript developers do not add or remove reference counts themselves. Keep ownership clear, remove unused listeners, bound caches, and inspect retaining paths when memory grows.

Common misconceptions

• “Null frees an object.” It removes one reference; another alias may remain.
• “Cycles always leak.” Tracing collectors collect detached cycles.
• “I can read the count.” JavaScript exposes no reference-count API.
• “Old IE explains modern browser leaks.” It is a historical case, not current browser behavior.

Practice exercises

let user = { name: "Asha" };
let admin = user;
user = null;
console.log(admin.name);

const counts = new Map([["tea", 1]]);
counts.set("tea", counts.get("tea") + 1);
counts.set("tea", counts.get("tea") - 1);
console.log(counts.get("tea"));

Check your understanding

Key takeaways

• Reference counting frees an object when its count reaches zero.
• Aliases increase or decrease a count, but JavaScript does not expose it.
• A detached cycle defeats pure counting because its internal links keep counts above zero.
• QuickJS adds cycle collection; most JavaScript engines trace from roots instead.
• Old Internet Explorer DOM cycles are historical; modern browsers trace across both sides.

Coming next: Mark-sweep & mark-compact.