Frontend Almanac

React Lanes

2025-03-24T10:14:06.008Z

React is one of the most popular libraries for creating user interfaces. However, when working with large amounts of data or complex calculations, developers often face performance issues. In this article, we'll explore the concept of React Lanes — a mechanism that allows prioritizing rendering tasks and making the interface more responsive even when performing heavy operations.

What are React Lanes?

Let's consider a typical task for React. Let it be a trivial search through text elements. For this, we'll take a regular input field and a list of elements that are filtered depending on the value entered in this field.

const SearchList = ({ items, filter }) => {
  // Heavy filtering operation (simulation)
  const filteredItems = items.filter((item) =>
    item.toLowerCase().includes(filter.toLowerCase()),
  );

  return (
    <ul>
      {filteredItems.map((item, i) => (
        <li key={i}>{item}</li>
      ))}
    </ul>
  );
};

const App = () => {
  const [inputValue, setInputValue] = useState("");

  // Generate large list for demonstration
  const bigList = Array(10_000)
    .fill(null)
    .map((_, i) => `Item ${i + 1}`);

  const handleChange = (e) => {
    setInputValue(e.target.value);
  };

  return (
    <div>
      <input
        type="text"
        value={inputValue}
        onChange={handleChange}
        placeholder="Search..."
      />

      <SearchList items={bigList} filter={inputValue} />
    </div>
  );
}

For clarity, let the list consist of a large number of elements. This will obviously provoke a heavy array filtering operation. You can try the resulting application below.

You can experiment with the number of elements depending on the power of your device and the environment in which the application is running. But one way or another, if you quickly enter values into the search string, you can notice some lag when there are many elements in the selection.

This happens because each value change leads to a re-render of the SearchList component, which in turn must render the required number of child elements.

Synchronous updates

The example above demonstrates typical synchronous work on updating the component tree. I wrote in detail about the update process in the article Detailed React. Reconciliation, Renderers, Fiber, Virtual Tree. The Fiber engine tries to make all necessary changes at once. In other words, the render phase will not complete until the reconciler has gone through all the scheduled synchronous changes.

Specifically in our example, each change in the text field causes reconciliation of SearchList, which in turn schedules renders of child components in the same phase. And until all child nodes are processed, the main thread will be blocked by the engine's work. If there are too many components to output, the blocking time becomes significant and manifests as a delay in response to user input.

In the screenshot above, the character "0" was entered into the text field, which gives 2620 child elements. Reconciliation of such a number of elements took 253ms, considering that delays of more than 100ms are noticeable to the human eye, and the estimated time of a browser frame is 16.6ms (at a refresh rate of 60 fps).

When adding another "0", 181 elements are displayed. Reconciliation already took 146ms. However, this is still a lot.

Let's continue entering zeros. The next "0" will give only 10 elements, and here we already see an acceptable duration of 10.6ms.

The fourth zero will leave only a single element, and the task duration was only 2ms.

Which is not much more than with the value "00000", where there are no elements to display.

Now let's do the reverse procedure and delete one character at a time from the text field.

Value "0000". Duration 0.9ms.

Value "000". Duration 1.2ms.

Value "00". Duration 12.8ms.

Value "0". Duration 178ms.

And finally, an empty string. Duration 699ms.

Task Priorities

The problem is obvious. Blocking operations have been a problem that needed to be addressed for quite some time. As a solution, one could suggest splitting heavy operations into threads and executing them in parallel. But a JavaScript task cannot be executed in multiple threads.

ReactPriorityLevel

The first attempts to solve the problem were made in 2016. In version 15.2.1, the concept of ReactPriorityLevel was first introduced. Since tasks cannot be divided into parallel threads, they can at least be arranged in order of importance. The essence of ReactPriorityLevel is to assign a priority flag to each tree update.

Initially, there were 5 such priorities, from most important to less important:

SynchronousPriority - for controlled input updates and synchronous operations.
AnimationPriority - animations must complete the calculation of the next step in the current frame.
HighPriority - updates that should be executed as quickly as possible to maintain optimal response
LowPriority - for requests and receiving responses from stores
OffscreenPriority - for elements that were hidden on the page but become visible again

Expiration Times

In general, the concept of priorities gave a certain result. But not all problems were solved. ReactPriorityLevel divided tasks into groups, but within a group, tasks still have the same priority. For example, there may well be several animated elements on a page. At the end of 2017, React 16.1 was introduced, which instead of priority flags suggested setting a time by which the task should be processed. The more important the task, the smaller expirationTime it had and, accordingly, was taken into work earlier than the others.

Lanes

The Expiration Times concept turned out to be quite workable. React 16 lived with it for the next 3 years. The essence of the model was that having priorities A > B > C, you cannot take B into work without executing A. Similarly, you cannot work on C without taking A and B into work.

This approach worked well until Suspense appeared. Prioritization works as long as all tasks are performed linearly. When a deferred task (such as Suspense) intervenes in the process, a situation arises where a deferred task with high priority blocks less priority main ones.

In terms of expressing a group of several priorities at once, the Expiration Times model is quite limited. To understand whether to include a task in the scope of work in the current iteration, it is enough to compare the relative priorities:

const isTaskIncludedInBatch = priorityOfTask >= priorityOfBatch;

To solve the Suspense problem, one could use a Set with priorities. But this would be very costly in terms of performance and would negate all the benefits of prioritization.

As a compromise, one could introduce priority ranges approximately as follows:

const isTaskIncludedInBatch = taskPriority <= highestPriorityInRange && taskPriority >= lowestPriorityInRange;

But even if we turn a blind eye to the fact that in this case it will be necessary to keep two fields, this approach still does not solve all the problems. For example, how to remove a task in the middle of the range? Some solution can certainly be found. But be that as it may, any manipulation of ranges will inevitably affect other groups, and their maintenance and stability will turn into a real nightmare.

To avoid all these problems, the React developers decided to separate the two concepts of prioritization and grouping. And they proposed to express groups of tasks by relative numbers representing a bit mask.

const isTaskIncludedInBatch = (task & batchOfTasks) !== 0;

The type of bit mask representing a task is called Lane. And the bit mask representing a group of tasks is Lanes.

How Lanes Work

In the official release Lanes first appeared in October 2020 with version React 17.0.0. This was a fairly large refactoring that significantly affected the work of Fiber.

At the moment, the latest stable version of React is v19.0.0. Most of the work Lanes is encapsulated in the ReactFiberLane reconciler module.

In fact, Lane is a 32-bit number where each bit indicates the task's belonging to a certain lane.

/packages/react-reconciler/src/ReactFiberLane.js#L39
export const TotalLanes = 31;

export const NoLanes: Lanes = /*                        */ 0b0000000000000000000000000000000;
export const NoLane: Lane = /*                          */ 0b0000000000000000000000000000000;

export const SyncHydrationLane: Lane = /*               */ 0b0000000000000000000000000000001;
export const SyncLane: Lane = /*                        */ 0b0000000000000000000000000000010;
export const SyncLaneIndex: number = 1;

export const InputContinuousHydrationLane: Lane = /*    */ 0b0000000000000000000000000000100;
export const InputContinuousLane: Lane = /*             */ 0b0000000000000000000000000001000;

export const DefaultHydrationLane: Lane = /*            */ 0b0000000000000000000000000010000;
export const DefaultLane: Lane = /*                     */ 0b0000000000000000000000000100000;

export const SyncUpdateLanes: Lane =
SyncLane | InputContinuousLane | DefaultLane;

const TransitionHydrationLane: Lane = /*                */ 0b0000000000000000000000001000000;
const TransitionLanes: Lanes = /*                       */ 0b0000000001111111111111110000000;
const TransitionLane1: Lane = /*                        */ 0b0000000000000000000000010000000;
const TransitionLane2: Lane = /*                        */ 0b0000000000000000000000100000000;
const TransitionLane3: Lane = /*                        */ 0b0000000000000000000001000000000;
const TransitionLane4: Lane = /*                        */ 0b0000000000000000000010000000000;
const TransitionLane5: Lane = /*                        */ 0b0000000000000000000100000000000;
const TransitionLane6: Lane = /*                        */ 0b0000000000000000001000000000000;
const TransitionLane7: Lane = /*                        */ 0b0000000000000000010000000000000;
const TransitionLane8: Lane = /*                        */ 0b0000000000000000100000000000000;
const TransitionLane9: Lane = /*                        */ 0b0000000000000001000000000000000;
const TransitionLane10: Lane = /*                       */ 0b0000000000000010000000000000000;
const TransitionLane11: Lane = /*                       */ 0b0000000000000100000000000000000;
const TransitionLane12: Lane = /*                       */ 0b0000000000001000000000000000000;
const TransitionLane13: Lane = /*                       */ 0b0000000000010000000000000000000;
const TransitionLane14: Lane = /*                       */ 0b0000000000100000000000000000000;
const TransitionLane15: Lane = /*                       */ 0b0000000001000000000000000000000;

const RetryLanes: Lanes = /*                            */ 0b0000011110000000000000000000000;
const RetryLane1: Lane = /*                             */ 0b0000000010000000000000000000000;
const RetryLane2: Lane = /*                             */ 0b0000000100000000000000000000000;
const RetryLane3: Lane = /*                             */ 0b0000001000000000000000000000000;
const RetryLane4: Lane = /*                             */ 0b0000010000000000000000000000000;

export const SomeRetryLane: Lane = RetryLane1;

export const SelectiveHydrationLane: Lane = /*          */ 0b0000100000000000000000000000000;

const NonIdleLanes: Lanes = /*                          */ 0b0000111111111111111111111111111;

export const IdleHydrationLane: Lane = /*               */ 0b0001000000000000000000000000000;
export const IdleLane: Lane = /*                        */ 0b0010000000000000000000000000000;

export const OffscreenLane: Lane = /*                   */ 0b0100000000000000000000000000000;
export const DeferredLane: Lane = /*                    */ 0b1000000000000000000000000000000;

Conditionally, all lanes can be divided into synchronous and deferred.

Synchronous Lanes

Synchronous lanes include SyncLane, InputContinuousLane and DefaultLane. Tasks placed in these lanes have the highest priority and are executed synchronously in the current phase of the reconciler.

From the names, we can guess that different types of tasks may have different priorities even in the synchronous phase. The most important ones are:

Root unmounting, which leads to immediate clearing of the React state and initiates an asynchronous removal of the tree elements
Hot Reload, since JS modules must be immediately replaced with new ones
Any overrides in Dev Tools must always happen first
The useSyncExternalStore hook synchronously reads data from external storage, this must happen at the very beginning of the reconciliation
The useOptimistic hook guarantees synchronous optimistic state update
In the current version of React, there is no official component <Activity /> (formerly known as <Offscreen />), but it is present in the engine and may someday become available. This component has three modes: "hidden", "visible" and "manual". Unlike the first two, the manual mode assumes that the developer himself is responsible for hiding/showing the component and manually calls Activity.attach() and Activity.detach(). These two methods are also executed synchronously so that React can immediately queue work for mounting/unmounting the component.

All the above processes happen in the SyncLane.

Event Priorities

The essential dispatcher of reactions in React is events. More precisely, synthetic events. And among all potential events, there are more important and less important ones. Therefore, React separates them all into three conditional groups:

Discrete - events triggered directly by the user (for example, MouseEvent or KeyboardEvent) and at the same time all events in the sequence are intentional, for example "click". Such events are assigned priority DiscreteEventPriority and they will be executed in SyncLane. These events can interrupt background tasks, but cannot be grouped over time (each event happens here and now).

import { useState } from "react";
import { createRoot } from "react-dom/client";

function App() {
  const [count, setCount] = useState(0);
  const handleClick = () => {
    setCount(count + 1);
  };
  return <button onClick={handleClick}>Update state in the SyncLane</button>;
}

const root = createRoot(document.getElementById("root"));
root.render(<App />);

At the moment, the list of discrete events looks like this:

beforetoggle
cancel
click
close
contextmenu
copy
cut
auxclick
dblclick
dragend
dragstart
drop
focusin
focusout
input
invalid
keydown
keypress
keyup
mousedown
mouseup
paste
pause
play
pointercancel
pointerdown
pointerup
ratechange
reset
resize
seeked
submit
toggle
touchcancel
touchend
touchstart
volumechange
change
selectionchange
textInput
compositionstart
compositionend
compositionupdate
beforeblur
afterblur
beforeinput
blur
fullscreenchange
focus
hashchange
popstate
select
selectstart

Continuous - events triggered directly by the user, but the user cannot distinguish individual events in the sequence (for example, mouseover). Such events are assigned priority ContinuousEventPriority and they are executed in InputContinuousLane. These events can interrupt background tasks and can be grouped over time.

import { useState } from "react";
import { createRoot } from "react-dom/client";

function App() {
  const [count, setCount] = useState(0);
  const handleMouseOver = () => setCount(count + 1);

  return (
    <div onMouseOver={handleMouseOver}>
      Update state in the InputContinuousLane
    </div>
  );
}

const root = createRoot(document.getElementById("root"));
root.render(<App />);

The list of continuous events:

drag
dragenter
dragexit
dragleave
dragover
mousemove
mouseout
mouseover
pointermove
pointerout
pointerover
scroll
touchmove
wheel
mouseenter
mouseleave
pointerenter
pointerleave

Others - events that do not fall into the first two groups (except "message", their priority is determined dynamically depending on the current priority of the scheduler). Such events are assigned priority DefaultEventPriority and they are executed in DefaultLane accordingly. The absence of an event is also considered DefaultEventPriority.

import { createRoot } from "react-dom/client";

const root = createRoot(document.getElementById("root"));

root.render(
  <div>
    No events emitted. Common rendering uses the DefaultLane
  </div>
);

Deferred Lanes

As you might guess from the name, they can be executed asynchronously with a delay. They have lower priority compared to synchronous lanes and are executed in the background after all synchronous lanes have been processed. Tasks executed in deferred lanes are considered non-blocking.

TransitionLane

The most obvious way to put a deferred task is through startTransition.

import { startTransition, useEffect, useState } from "react";
import { createRoot } from "react-dom/client";

function App() {
  const [, setHigh] = useState(0);
  const [, setLow] = useState(0);

  useEffect(() => {
    startTransition(() => {
      // 2. TransitionLane will be proceeded in a background after a sync lane
      setLow((prevLow) => prevLow + 1);
    });

    // 1. DefaultLane will be done first
    setHigh((prevHigh) => prevHigh + 1);
  }, []);

  return null;
}

const root = createRoot(document.getElementById("root"));
root.render(<App />);

Tasks placed in TransitionLane can parallelize. For this, there are 15 lanes TransitionLane1..15. Unlike synchronous lanes, their effect is more effective to combine into packages than to parallelize.

import { startTransition, useEffect, useState } from "react";
import { createRoot } from "react-dom/client";

function App() {
  const [, setHigh] = useState(0);
  const [, setLow] = useState(0);

  useEffect(() => {
    // TransitionLane1
    startTransition(() => {
      setLow((prevLow) => prevLow + 1);
    });

    // TransitionLane2
    setTimeout(() => {
      startTransition(() => {
        setLow((prevLow) => prevLow + 1);
      });
    }, 0);

    // TransitionLane3
    setTimeout(() => {
      startTransition(() => {
        setLow((prevLow) => prevLow + 1);
      });
    }, 0);
    
    // DefaultLane
    setHigh((prevHigh) => prevHigh + 1);
  }, []);

  return null;
}

const root = createRoot(document.getElementById("root"));
root.render(<App />);

RetryLane

Another way to perform a deferred task is Suspense.

import { Suspense, use } from "react";
import { createRoot } from "react-dom/client";

const cache = new Map();

function fetchData() {
  if (!cache.has("data")) {
    cache.set("data", getData());
  }
  return cache.get("data");
}

async function getData() {
  // Add a fake delay to make waiting noticeable.
  await new Promise((resolve) => {
    setTimeout(resolve, 1_000);
  });

  return ["item1", "item2", "item3"];
}

function AsyncComponent() {
  const items = use(fetchData());

  return (
    <ul>
      {items.map((item) => (
        <li key={item}>{item}</li>
      ))}
    </ul>
  );
}

function App() {
  return (
    <>
      <h1>Retry lanes</h1>
      <Suspense fallback="Loading...">
        <AsyncComponent />
      </Suspense>
    </>
  );
}

const root = createRoot(document.getElementById("root"));
root.render(<App />);

In simple words, Suspense first renders the fallback component. Then, when one or more promises inside the Suspended component resolve, Fiber will try to re-render, putting the task in RetryLane. Like TransitionLane, RetryLane can parallelize and has four lanes RetryLane1..4.

function AsyncComponent() {
  const items = use(fetchData());
  const meta = use(fetchMeta());

  return (
    <ul>
      {items.map((item) => (
        <li key={item}>{item}</li>
      ))}
    </ul>
  );
}

function App() {
  return (
    <>
      <h1>Retry lanes</h1>
      <Suspense fallback="Loading...">
        <AsyncComponent />
      </Suspense>
    </>
  );
}

const root = createRoot(document.getElementById("root"));
root.render(<App />);

The same work happens with components SuspenseList and Activity. But they are not included in the latest, today's React release. So it is not worth discussing them in detail now.

IdleLane

The next by priority lane is IdleLane. The idea of IdleLane is to perform some tasks only when the engine is idle and not busy with other, more important tasks. This can be compared to the Idle period in the browser scheduler (I wrote more about this in the article Chromium. Web page rendering using Blink, CC and scheduler), but at the Fiber engine and React scheduler level.

At the moment, there is no React DOM API that could cause an update with idle priority, nor native DOM events with idle priority. Therefore, for now, this lane can only be used through internal methods of the engine, not available in the prod build of React.

OffscreenLane

Just above, when I was talking about synchronous lanes, I mentioned a so-called component Offscreen, which is now called Activity. Its idea is to determine whether a component is currently in the visible part of the page, or outside its boundaries. If the component is not visible on the screen, then the tasks it has are of low priority. Therefore, for such tasks, the lane OffscreenLane was allocated.

Unfortunately, this is still another component that has not yet entered the current React release. But it has all the chances to enter one of the next ones. We hope to see it soon.

DeferredLane

It's not hard to guess that the lane DeferredLane is intended for the useDeferredValue hook. However, it's not as simple as it might seem.

import { useDeferredValue } from "react";
import { createRoot } from "react-dom/client";

function App() {
  const text = useDeferredValue("Final");

  return <div>{text}</div>;
}

const root = createRoot(document.getElementById("root"));
root.render(<App />);

If the hook does not have a second argument - initialValue, it has nothing to compare the new value with when mounting and it will be executed synchronously in DefaultLane. However, if the hook has a previous value with which it can compare the current one, for example when the hook is mounted and updated again or if an initialValue is specified, we will see the following picture.

import { useDeferredValue } from "react";
import { createRoot } from "react-dom/client";

function App() {
  const text = useDeferredValue("Final", "Initial");

  return <div>{text}</div>;
}

const root = createRoot(document.getElementById("root"));
root.render(<App />);

The work was actually done in TransitionLane. If we had tried to execute the hook in the Offscreen component, we would have seen that it was executed in OffscreenLane. The reason is that DeferredLane is a technical intermediate lane. It is only for logical separation of deferred tasks from the others. This task does not have its own execution priority and is always mixed with other lanes depending on the situation.

Non-blocking Rendering

Let's now return to our original example and try to get rid of the interface blocking heavy operations.

const SearchList = ({ items, filter }) => {
  // Heavy filtering operation (simulation)
  const filteredItems = items.filter((item) =>
    item.toLowerCase().includes(filter.toLowerCase()),
  );

  return (
    <ul>
      {filteredItems.map((item, i) => (
        <li key={i}>{item}</li>
      ))}
    </ul>
  );
};

const App = () => {
  const [inputValue, setInputValue] = useState("");
  const deferredValue = useDeferredValue(inputValue);

  // Generate large list for demonstration
  const bigList = Array(10_000)
    .fill(null)
    .map((_, i) => `Item ${i + 1}`);

  const handleChange = (e) => {
    setInputValue(e.target.value);
  };

  return (
    <div>
      <input
        type="text"
        value={inputValue}
        onChange={handleChange}
        placeholder="Search..."
      />

      <SearchList items={bigList} filter={deferredValue} />
    </div>
  );
}

All we did in SearchList was to pass deferredValue instead of inputValue. This allowed us to put the task of calculating the array of elements in the deferred TransitionLane and unlock synchronous updates of the input element.

Of course, no miracles from React are expected. Heavy operation remains heavy. And React, being just a JavaScript library, is still executed in the main browser thread. The Lanes system is just a way to prioritize tasks. More important tasks are done first, less important ones are postponed. However, if a heavy deferred task is taken into work, it will still block the main thread.

Practical Recommendations for Using Lanes

Understanding the Lanes system in React can significantly help in optimizing application performance. Here are some practical recommendations:

Use useDeferredValue for heavy rendering operations. As we saw in the example with search, deferred value allows you to maintain responsiveness of the interface even when working with large amounts of data.
Apply startTransition for non-priority UI updates. When you need to perform an update that does not require immediate reaction (for example, switching tabs or loading additional content), wrap it in startTransition.
Separate synchronous and asynchronous parts of your application. Elements that require immediate reaction (input fields, buttons) should be updated synchronously, and heavy calculations and displaying large lists should be postponed.
Use Suspense for asynchronous data loading. This will allow React to automatically manage task priorities when loading data from the server.
Remember about component nesting. The more deeply nested the component, the more time it may take to update. Try to move heavy components closer to the root of the tree.

Future React Lanes

The Lanes system continues to evolve. In future versions of React, we can expect:

Official API for the Activity component, which will allow more flexible management of rendering priorities depending on component visibility.
Possible integration of Web Workers for performing heavy calculations in separate threads.
Further development of the API for more fine-grained task priority tuning.
Improvement of integration with profiling tools for more visual display of system priority work.

Conclusion

The Lanes system in React is a powerful tool for optimizing user experience. It does not make your application faster in absolute terms, but it allows more reasonable distribution of computing resources, giving priority to what is important for the user right now.

Proper use of useDeferredValue, startTransition and Suspense can significantly improve the perceived performance of your application, making it more responsive even when performing complex operations. This is especially important for modern web applications that often work with large amounts of data and complex interfaces.

In the end, understanding the internal structure of React and the principles of system priority work allows developers to create more efficient and user-friendly applications, which is the key goal of any frontend development.

My telegram channels:

EN - https://t.me/frontend_almanac
RU - https://t.me/frontend_almanac_ru

Русская версия: https://blog.frontend-almanac.ru/react-lanes

style.setProperty vs setAttribute

2024-11-18T07:59:06.498Z

Recently, I encountered an interesting question: which is faster, element.style.setProperty(property, value) or element.setAttribute('style', 'property: value')? At first glance, the answer seems obvious. Logic suggests that setProperty should store the value directly in the CSSOM, while setAttribute first sets the style attribute, which is then parsed into the CSSOM. Therefore, setProperty should be faster. But is it really that straightforward? Let's delve into it.

To begin, let's refresh some foundational concepts. We know that styles are described using the CSS language. After receiving a string representation of styles in CSS, the browser parses it and constructs a CSSOM object. The interface of this object is defined by the specification https://www.w3.org/TR/cssom-1. It adheres to the principles of cascading and inheritance outlined in https://www.w3.org/TR/css-cascade-4.

From the specifications mentioned above, we know that the fundamental unit of CSS is a property. Each property is assigned a value that is specific to that property. If a value is not explicitly specified, it is inherited from a parent style, or, if there is no parent, it will be set to the initial value.

The set of properties for an element is organized into CSSRule. There are different types of rules, with the most common type being the CSSStyleRule, which defines the properties of an element. This type of rule begins with a valid selector followed by curly braces containing a set of properties and values, formatted as <selector>: { ... }. Other types of rules exist as well, such as the CSSFontFaceRule, which describes the parameters for an imported font using @font-face { ... }, the CSSMediaRule, represented as @media { ... }, and others. You can find a complete list in the specification at https://www.w3.org/TR/cssom-1/#css-rules.

These rules are compiled into what is known as a CSSStyleSheet, which serves as an abstract representation of the <style> tag. In turn, style sheets are aggregated into a collection and associated with the document.

All of these levels of abstraction constitute the CSS Object Model (CSSOM). While the specification primarily describes the syntax of the model, in practice, it also includes the direct implementation of the CSS API used by browsers. Functions such as computed style, color encoding methods, mathematical operations, and many others are also part of CSSOM.

Setting Properties in Blink

Having covered the theory, let's take a closer look under the hood of the browser, specifically at the Blink rendering engine used by browsers like Chromium, Opera, WebView, and others. Blink is part of the Chromium repository and is not supplied independently. Therefore, we will be conducting our experiments using Chromium (version 132.0.6812.1 as of the time this article was written).

style.setProperty

Let's begin with the method style.setProperty.

element.style.setProperty("background-color", "red");

To understand what happens under the hood of Blink, it's essential to take a closer look at the inner workings of Blink itself.

/third_party/blink/renderer/core/css/abstract_property_set_css_style_declaration.cc#130

void AbstractPropertySetCSSStyleDeclaration::setProperty(
    const ExecutionContext* execution_context,
    const String& property_name,
    const String& value,
    const String& priority,
    ExceptionState& exception_state) {
  CSSPropertyID property_id =
      UnresolvedCSSPropertyID(execution_context, property_name);
  if (!IsValidCSSPropertyID(property_id) || !IsPropertyValid(property_id)) {
    return;
  }
  
  bool important = EqualIgnoringASCIICase(priority, "important");
  if (!important && !priority.empty()) {
    return;
  }
  
  const SecureContextMode mode = execution_context
                                     ? execution_context->GetSecureContextMode()
                                     : SecureContextMode::kInsecureContext;
  SetPropertyInternal(property_id, property_name, value, important, mode,
                      exception_state);
}

First, a basic validity check is performed on the property that has been passed in. Then, the style's priority is evaluated, and an internal method SetPropertyInternal is invoked.

/third_party/blink/renderer/core/css/abstract_property_set_css_style_declaration.cc#236

void AbstractPropertySetCSSStyleDeclaration::SetPropertyInternal(
    CSSPropertyID unresolved_property,
    const String& custom_property_name,
    StringView value,
    bool important,
    SecureContextMode secure_context_mode,
    ExceptionState&) {
  StyleAttributeMutationScope mutation_scope(this);
  WillMutate();
  
  MutableCSSPropertyValueSet::SetResult result;
  if (unresolved_property == CSSPropertyID::kVariable) {
    AtomicString atomic_name(custom_property_name);
    
    bool is_animation_tainted = IsKeyframeStyle();
    result = PropertySet().ParseAndSetCustomProperty(
        atomic_name, value, important, secure_context_mode, ContextStyleSheet(),
        is_animation_tainted);
  } else {
    result = PropertySet().ParseAndSetProperty(unresolved_property, value,
                                               important, secure_context_mode,
                                               ContextStyleSheet());
  }
  
  if (result == MutableCSSPropertyValueSet::kParseError ||
      result == MutableCSSPropertyValueSet::kUnchanged) {
    DidMutate(kNoChanges);
    return;
  }
  
  CSSPropertyID property_id = ResolveCSSPropertyID(unresolved_property);
  
  if (result == MutableCSSPropertyValueSet::kModifiedExisting &&
      CSSProperty::Get(property_id).SupportsIncrementalStyle()) {
    DidMutate(kIndependentPropertyChanged);
  } else {
    DidMutate(kPropertyChanged);
  }
  
  mutation_scope.EnqueueMutationRecord();
}

Within this internal method, a mutation process is initiated, the string value is parsed, and this value is assigned to the specified property. Following this, the changes are reflected in the CSSOM. Overall, the process is straightforward.

setAttribute

Now, Let's Examine setAttribute.

element.setAttribute("style", "background-color: red");

This operation goes beyond the CSSOM and directly affects elements and their attributes, resulting in modifications to the DOM. Within the DOM, there is a class called Attr that describes a single attribute of an element. There are several ways to set the value of an attribute.

/third_party/blink/renderer/core/dom/attr.cc#73

void Attr::setValue(const AtomicString& value,
                    ExceptionState& exception_state) {
  // Element::setAttribute will remove the attribute if value is null.
  DCHECK(!value.IsNull());
  if (element_) {
    element_->SetAttributeWithValidation(GetQualifiedName(), value,
                                         exception_state);
  } else {
    standalone_value_or_attached_local_name_ = value;
  }
}

This method allows us to assign a value to an existing attribute. In other words, we can do something like this.

element.style = "background-color: red";

This will lead to the invocation of the method SetAttributeWithValidation, which we will discuss shortly.

However, in our original case, we are not directly accessing the style attribute; instead, we are calling the setAttributemethod from the Element class.

/third_party/blink/renderer/core/dom/element.h#282

void setAttribute(const QualifiedName& name, const AtomicString& value) {
  SetAttributeWithoutValidation(name, value);
}

This method, in turn, calls another method: SetAttributeWithoutValidation.

So, what are the methods SetAttributeWithoutValidation and SetAttributeWithValidation?

/third_party/blink/renderer/core/dom/element.cc#10314

void Element::SetAttributeWithoutValidation(const QualifiedName& name,
                                            const AtomicString& value) {
  SynchronizeAttribute(name);
  SetAttributeInternal(FindAttributeIndex(name), name, value,
                       AttributeModificationReason::kDirectly);
}

void Element::SetAttributeWithValidation(const QualifiedName& name,
                                         const AtomicString& value,
                                         ExceptionState& exception_state) {
  SynchronizeAttribute(name);
  
  AtomicString trusted_value(TrustedTypesCheckFor(
      ExpectedTrustedTypeForAttribute(name), value, GetExecutionContext(),
      "Element", "setAttribute", exception_state));
  if (exception_state.HadException()) {
    return;
  }
  
  SetAttributeInternal(FindAttributeIndex(name), name, trusted_value,
                       AttributeModificationReason::kDirectly);
}

As we can see, both methods essentially perform the same function. They first synchronize the current value of the attribute to account for any pending mutations. After that, they proceed to set the new value. The only difference is that in the second case, the new value is validated against the specified attribute before it is set. In other words, the following is not allowed.

element.style = "invalid-prop: red"
// <div style></div>

Attempting to assign an invalid style to the style attribute will result in the attribute's value being removed.

However, there is nothing stopping us from doing this instead.

element.setAttribute("style", "invalid-prop: red")
// <div style="invalid-prop: red"></div>

In this case, the style will be set regardless of what we specified as the value.

This seems quite strange. Why not validate attribute values all the time? The answer is quite simple. The setAttribute method acts as a sort of backdoor for attributes. It is designed to operate not only with built-in attributes but also with arbitrary ones, such as data-*.

element.setAttribute("data-ship-id", "324");
element.setAttribute("data-weapons", "laserI laserII");
element.setAttribute("data-shields", "72%");
element.setAttribute("data-x", "414354");
element.setAttribute("data-y", "85160");
element.setAttribute("data-z", "31940");
element.setAttribute("onclick", "spaceships[this.dataset.shipId].blasted()");

The setAttribute method operates at the DOM element level, and its primary function is to assign a value to an attribute without any validations. A detailed algorithm is described in the DOM standard.

Which is Faster?

Based on the above information, we can speculate that style.setProperty should be faster since, unlike setAttribute, the engine doesn’t need to search for a reference to the attribute object in the attribute table and can directly proceed to set the value. On the other hand, the overhead of validating the value itself could be significant.

Test 1: One Property

To determine which method is actually faster, we will conduct an experiment. For this purpose, we will need an HTML page with a test element and a couple of buttons.

<div id="test-element"></div>
<button onclick="handleSetProperty()">style.setProperty</button>
<button onclick="handleSetAttribute()">setAttribute</button>

Additionally, a simple JavaScript script will be required.

const N = 100;

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

function createElement() {
  const el = document.getElementById("test-element");
  
  const newEl = document.createElement("div");
  newEl.setAttribute("id", "test-element");
  newEl.setAttribute("width", 100);
  newEl.setAttribute("height", 100);
  
  el.replaceWith(newEl);
  
  return newEl;
}

async function handleSetProperty() {
  const durations = [];

  for await (const i of new Array(N).fill(true).map((_, index) => index)) {
    const el = createElement();

    await sleep(300);

    const startTime = performance.now();
    el.style.setProperty("background-color", "red");
    const duration = performance.now() - startTime;

    durations.push(duration);

    await sleep(300);

    console.log(i);
  }

  console.log(durations);
}

async function handleSetAttribute() {
  const durations = [];

  for await (const i of new Array(N).fill(true).map((_, index) => index)) {
    const el = createElement();

    await sleep(300);

    const startTime = performance.now();
    el.setAttribute("style", "background-color: red");
    const duration = performance.now() - startTime;

    durations.push(duration);

    await sleep(300);

    console.log(i);
  }

  console.log(durations);
}

This script, upon clicking one of the buttons, will initiate a loop of 100 iterations that sets the value of the style for a test element. To ensure the integrity of the experiment, we will create a new test element during each iteration and insert pauses after creating the element and after setting the value. This approach aims to eliminate browser optimizations and guarantee the rendering of the element after each iteration. We will take measurements separately, following a hard refresh of the page.

After collecting the measurements from the 100 iterations, we will calculate the simple average to obtain the final result.

avgSetProperty     0.07400000274181366
avgSetAttribute    0.08999999761581420

In this experiment, style.setProperty clearly takes the lead. However, we only attempted to set a single CSS property.

Test 2: Two Properties

For objectivity, we will repeat the experiment with two properties simultaneously. To facilitate this, we will make slight adjustments to the test functions.

async function handleSetProperty() {
  const durations = [];

  for await (const i of new Array(N).fill(true).map((_, index) => index)) {
    const el = createElement();

    await sleep(300);

    const startTime = performance.now();
    el.style.setProperty("background-color", "red");
    el.style.setProperty("border", "1px solid blue");
    const duration = performance.now() - startTime;

    durations.push(duration);

    await sleep(300);

    console.log(i);
  }

  console.log(durations);
}

async function handleSetAttribute() {
  const durations = [];

  for await (const i of new Array(N).fill(true).map((_, index) => index)) {
    const el = createElement();

    await sleep(300);

    const startTime = performance.now();
    el.setAttribute("style", "background-color: red; border: 1px solid blue;");
    const duration = performance.now() - startTime;

    durations.push(duration);

    await sleep(300);

    console.log(i);
  }

  console.log(durations);
}

Upon running the loops again, we obtained the following result.

avgSetProperty     0.10900000214576722
avgSetAttribute    0.10399999618530273

The situation has changed. The average speed of both methods has approximately equalized. The setAttribute method is actually a little faster; however, this difference can be attributed to potential measurement inaccuracies. The reason for this is not even validation, as it is still insignificant at this point. In this case, another process comes into play: the mutation of the CSSStyleDeclaration object. This interface describes the structure of a set of styles, such as the body of the <style> tag. A similar object also stores the style for an individual element. I previously provided a code snippet for the method that sets a property value in CSSStyleDeclaration. Let's take another look at it.

/third_party/blink/renderer/core/css/abstract_property_set_css_style_declaration.cc#236

void AbstractPropertySetCSSStyleDeclaration::SetPropertyInternal(
    CSSPropertyID unresolved_property,
    const String& custom_property_name,
    StringView value,
    bool important,
    SecureContextMode secure_context_mode,
    ExceptionState&) {
  StyleAttributeMutationScope mutation_scope(this);
  WillMutate();

  MutableCSSPropertyValueSet::SetResult result;
  if (unresolved_property == CSSPropertyID::kVariable) {
    AtomicString atomic_name(custom_property_name);

    bool is_animation_tainted = IsKeyframeStyle();
    result = PropertySet().ParseAndSetCustomProperty(
        atomic_name, value, important, secure_context_mode, ContextStyleSheet(),
        is_animation_tainted);
  } else {
    result = PropertySet().ParseAndSetProperty(unresolved_property, value,
                                               important, secure_context_mode,
                                               ContextStyleSheet());
  }

  if (result == MutableCSSPropertyValueSet::kParseError ||
      result == MutableCSSPropertyValueSet::kUnchanged) {
    DidMutate(kNoChanges);
    return;
  }

  CSSPropertyID property_id = ResolveCSSPropertyID(unresolved_property);

  if (result == MutableCSSPropertyValueSet::kModifiedExisting &&
      CSSProperty::Get(property_id).SupportsIncrementalStyle()) {
    DidMutate(kIndependentPropertyChanged);
  } else {
    DidMutate(kPropertyChanged);
  }

  mutation_scope.EnqueueMutationRecord();
}

First, the object is locked. Then the property value is parsed and saved. After this, the lock is released.

Here is how setting the style as a whole looks when using a text string.

/third_party/blink/renderer/core/css/abstract_property_set_css_style_declaration.cc#54

void AbstractPropertySetCSSStyleDeclaration::setCSSText(
    const ExecutionContext* execution_context,
    const String& text,
    ExceptionState&) {
  StyleAttributeMutationScope mutation_scope(this);
  WillMutate();

  const SecureContextMode mode = execution_context
                                     ? execution_context->GetSecureContextMode()
                                     : SecureContextMode::kInsecureContext;
  PropertySet().ParseDeclarationList(text, mode, ContextStyleSheet());

  DidMutate(kPropertyChanged);

  mutation_scope.EnqueueMutationRecord();
}

The same object is locked. Next, the entire text string is parsed and broken down into properties. The values are then saved, and the object is unlocked.

Thus, by calling style.setProperty twice, we initiate the lock-parse-unlock process two times. In contrast, setAttributecan parse the entire style in a single operation.

I must emphasize one particular point regarding style parsing optimization.

/third_party/blink/renderer/core/css/parser/css_parser_impl.cc#255

 static ImmutableCSSPropertyValueSet* CreateCSSPropertyValueSet(
    HeapVector<CSSPropertyValue, 64>& parsed_properties,
    CSSParserMode mode,
    const Document* document) {
  if (mode != kHTMLQuirksMode &&
      (parsed_properties.size() < 2 ||
       (parsed_properties.size() == 2 &&
        parsed_properties[0].Id() != parsed_properties[1].Id()))) {
    // Fast path for the situations where we can trivially detect that there can
    // be no collision between properties, and don't need to reorder, make
    // bitsets, or similar.
    ImmutableCSSPropertyValueSet* result =
        ImmutableCSSPropertyValueSet::Create(parsed_properties, mode);
    parsed_properties.clear();
    return result;
  }
  
  ...
}

The parser, after processing a string, produces an array of properties. However, this array may contain duplicate properties. To create a set of unique properties, it is necessary to iterate over the array again and gather the unique ones. However, if the original array contains only two properties, checking for uniqueness can be done simply with an if statement by comparing them by their IDs. It may seem trivial, but it's quite satisfying.

Test 3: Multiple Properties

Let’s conduct another test. This time, we will use a larger number of properties — say, seven. Why seven specifically? This number is chosen for a reason, which I will explain shortly.

async function handleSetProperty() {
  const durations = [];

  for await (const i of new Array(N).fill(true).map((_, index) => index)) {
    const el = createElement();

    await sleep(300);

    const startTime = performance.now();
    el.style.setProperty("background-color", "red");
    el.style.setProperty("border", "1px solid blue");
    el.style.setProperty("position", "relative");
    el.style.setProperty("display", "flex");
    el.style.setProperty("align-items", "center");
    el.style.setProperty("text-align", "center");
    el.style.setProperty("text-transform", "uppercase");
    const duration = performance.now() - startTime;

    durations.push(duration);

    await sleep(300);

    console.log(i);
  }

  console.log(durations);
}

async function handleSetAttribute() {
  const durations = [];

  for await (const i of new Array(N).fill(true).map((_, index) => index)) {
    const el = createElement();

    await sleep(300);

    const startTime = performance.now();
    el.setAttribute(
      "style",
      "background-color: red; border: 1px solid blue; position: relative; display: flex; align-items: center; text-align: center; text-transform: uppercase;",
    );
    const duration = performance.now() - startTime;

    durations.push(duration);

    await sleep(300);

    console.log(i);
  }

  console.log(durations);
}

The results of this test are quite logical.

avgSetProperty     0.17899999499320984
avgSetAttribute    0.12500000596046448

This time, setAttribute achieved a clear victory in speed for the reasons mentioned above.

Test 4: Multiple Numeric Values

You may have noticed that in the previous test, all properties had string values. The reason for this is that numeric values coming from JavaScript do not require additional parsing from strings. This allows for further optimization and some savings in processing.

Unfortunately, there are not many properties that can handle numeric values in this way. Most of the properties we are familiar with that can accept numeric values are designed to work with various units of measurement, perform different mathematical operations, etc. As a result, it is necessary to convert their numeric values into other formats in any case. Therefore, developers have limited the set of properties that can accept numeric values. Currently, there are only seven such properties: opacity, fill-opacity, flood-opacity, stop-opacity, stroke-opacity, shape-image-threshold, and -webkit-box-flex.

Let’s repeat our previous experiment, but this time focusing solely on numeric properties. This is precisely why I selected only seven properties last time, allowing us to effectively compare the results.

async function handleSetProperty() {
  const durations = [];

  for await (const i of new Array(N).fill(true).map((_, index) => index)) {
    const el = createElement();

    await sleep(300);

    const startTime = performance.now();
    el.style.setProperty("opacity", 0.5);
    el.style.setProperty("fill-opacity", 0.5);
    el.style.setProperty("flood-opacity", 0.5);
    el.style.setProperty("stop-opacity", 0.5);
    el.style.setProperty("stroke-opacity", 0.5);
    el.style.setProperty("shape-image-threshold", 0.5);
    el.style.setProperty("-webkit-box-flex", 1);

    const duration = performance.now() - startTime;

    durations.push(duration);

    await sleep(300);

    console.log(i);
  }

  console.log(durations);
}

async function handleSetAttribute() {
  const durations = [];

  for await (const i of new Array(N).fill(true).map((_, index) => index)) {
    const el = createElement();

    await sleep(300);

    const startTime = performance.now();
    el.setAttribute(
      "style",
      "opacity: 0.5; fill-opacity: 0.5; flood-opacity: 0.5; stop-opacity: 0.5; stroke-opacity: 0.5; shape-image-threshold: 0.5; -webkit-box-flex: 1;",
    );
    const duration = performance.now() - startTime;

    durations.push(duration);

    await sleep(300);

    console.log(i);
  }

  console.log(durations);
}

And now for the results.

avgSetProperty     0.17099999666213989
avgSetAttribute    0.09600000023841858

The setAttribute method remains faster. Ultimately, the overhead of converting a string to a number does not compare to the performance cost of locking, unlocking, and writing a value. Nevertheless, in both cases, the results turned out to be slightly better than in Test 3.

Conclusion

Let’s summarize everything discussed above.

The style.setProperty method demonstrates better performance when setting a single property. However, when two or more properties are set simultaneously, setAttribute is faster.
The setAttribute method does not validate values, which can be both an advantage and a disadvantage. If it is important for us to ensure that only valid values are set, we can use the setter element.style = "<style>". However, if we need to set a custom attribute on an element or an intentionally incorrect value, setAttribute is indispensable.
There are seven properties that are allowed to accept numeric values from JavaScript scripts. Setting the values of these properties will be slightly faster due to the elimination of the string-to-number conversion operation.

My telegram channels:

EN - https://t.me/frontend_almanac
RU - https://t.me/frontend_almanac_ru

Русская версия: https://blog.frontend-almanac.ru/style-setproperty-vs-setattribute

V8. Working with Strings. Expanding Vocabulary

2024-08-20T07:43:01.667Z

What is a String

To better understand what happens under the hood of V8, it is useful to recall some theory first.

The ECMA-262 specification states:

The String type is the set of all ordered sequences of zero or more 16-bit unsigned integer values (“elements”) up to a maximum length of 2**53 - 1 elements.

The String type is a set of all ordered sequences of zero or more 16-bit unsigned integers (“elements”) with a maximum length of 2**53 - 1 elements.

In practice, it is necessary to store additional information along with strings in machine memory to be able to determine the end of the string in the general heap. There are two approaches for this purpose. The first is an array of characters: a structure that represents a sequence of elements and a separate field for the length of this sequence. The second is the null-terminator method, where a special character indicating the end of the string is placed at the end of the sequence of elements. Depending on the system, the terminator character can be the byte 0xFF or, for example, an ASCII code character. However, the byte 0x00 is the most commonly used. Strings with this terminating element are referred to as null-terminated strings. Both methods have their own advantages and disadvantages, which is why in the modern world, both methods are often combined, and strings in memory can simultaneously be null-terminated and store their length. This approach is used, for instance, in the C++ language starting with version 11.

In addition to the general definition of a string, the ECMA-262 specification has several other requirements alongside the other data types in the JavaScript language. I wrote in detail about types and their representation within the V8 engine in my article "Deep JS: In Memory of Types and Data." In that article, we learned that all types have their own hidden class, which stores all necessary attributes, service information, and encapsulates the logic of working with that type. It is obvious that for working with strings, the standard C++ library std::string is insufficient, and they are transformed into an internal class v8::String.

Types of Strings

To meet all the specification requirements and due to various optimizations, strings within V8 are divided into different types.

One-byte / Two-byte

Despite the specification directly defining all strings as sequences of 16-bit elements, this is quite wasteful from an optimization standpoint. After all, not all characters require 2 bytes for representation. The standard ASCII table contains 128 elements, including Arabic numerals, Latin alphabet letters in uppercase and lowercase without diacritical marks, basic punctuation, mathematical symbols, and control characters. This entire table implies coding with only 8 bits, and the set of characters is widely used in practice. Therefore, the V8 developers decided to encode strings that contain only 8-bit characters separately from the standard 16-bit ones. This allows for significant memory savings.

Internalized / Externalized Strings

Besides bit-depth, strings differ in their storage location. After being converted into an internal structure, the string gets placed into the so-called StringTable, which we will discuss a bit later. For now, note that there are three such tables. The StringTable itself stores strings within a single Isolate (essentially, within a single browser tab). Additionally, the engine allows strings to be stored outside the heap and even outside the engine itself, in external storage. Pointers to such strings are placed in a separate table called the ExternalStringTable. Furthermore, there is another table — the StringForwardingTable — for the purposes of garbage collection. Yes, strings, like objects, participate in garbage collection, and since they are stored in separate tables, they require specific mechanisms for this process. We will discuss this in detail a bit later.

Strings by purpose

The JavaScript language is quite flexible. During code execution, strings can be transformed multiple times and participate in related processes. For better performance, several functional types are allocated to them. These include: SeqString, ConsString, ThinString, and SlicedString and ExternalString. We will discuss each type in detail later. For now, let's summarize everything mentioned above.

This is the general classification of string types in V8. Besides the main types, there are also several derived types. For example, SeqString and ExternalString can be placed in a common shared heap, where their types may be SharedSeq<one|two>ByteString and SharedExternal<one|two>ByteString, respectively. Additionally, ExternalString can be uncachable and have additional types like UncachableExternal<one|two>ByteString and even SharedUncachableExternal<one|two>ByteString.

AST

Before a string takes its final form in the depths of V8, the engine must first read and interpret it. This is done using the same mechanism that interprets all other syntactic units of the language. Specifically, this involves constructing an abstract syntax tree (AST), which I discussed in the article Deep JS. Scopes of darkness or where variables live.

Upon receiving a string node through a string literal or some other means, V8 creates an instance of the AstRawString class. If the string is a concatenation of two or more other strings, it creates an AstConsString. These classes are designed to store strings outside V8's heap, in the so-called AstValueFactory. Later, these strings will be assigned a type and will be internalized, i.e., moved into V8's heap.

The length of the string

The size of each string in memory depends on its length. The longer the string, the more memory it occupies. But are there any limitations on the maximum string size imposed by the engine? The specification explicitly states that a string cannot exceed 2**53 - 1 elements. However, in practice, this number can be different. After all, a maximum one-byte string would weigh in at 8,192 TB (8 PB), while a two-byte string would correspondingly be 4,096 TB (4 PB). Clearly, no personal computer has that much RAM, which is why JavaScript engines have their own limits that are significantly stricter than the requirements of the specification. Specifically in V8 (the version of V8 at the time of writing this article is 12.8.325), the maximum string length depends on the system architecture.

/include/v8-primitive.h#126

static constexpr int kMaxLength =
    internal::kApiSystemPointerSize == 4 ? (1 << 28) - 16 : (1 << 29) - 24;

For 32-bit systems, this number is 2**28 - 16, and for 64-bit systems, it's slightly higher: 2**29 - 24. These limitations prevent a one-byte string from occupying more than 256 MB in 32-bit systems, and a one-byte string from occupying more than 512 MB. In 64-bit systems, the maximum values are no more than 512 MB for one-byte strings and 1024 MB for two-byte strings. If a string exceeds the length limit, the engine will return an Invalid string length error.

const length = (1 << 29) - 24;
const longString = '"' + new Array(length - 2).join('x');

String.prototype.link(longString); // RangeError: Invalid string length

To be objective, it is also important to note that the maximum heap size plays an indirect role, as it is not a constant and can be adjusted by the system or engine configuration.

// d8 --max-heap-size=128

const length = (1 << 27) + 24; // 129 MB
const longString = '"' + new Array(length - 2).join('x');

String.prototype.link(longString);

// Fatal JavaScript out of memory: Reached heap limit

StringTable

During the execution of a JavaScript program, it can manipulate a large number of both strings and variables that reference them. As we have seen, each string can consume a significant amount of memory. Moreover, strings within a JS program can be cloned, modified, concatenated, and transformed in various ways multiple times. As a result, duplicates of string values can end up in memory. Storing multiple copies of the same sequence of characters would be extremely wasteful. Therefore, in the world of system programming, the practice of storing string values in a separate structure that ensures there is no duplication of values, and that all string variables reference this structure, has long been actively applied. In Java and .NET, for example, such a structure is called a "StringPool", and in JavaScript, it is called a StringTable.

The essence of this is that once a string is included in the AST, a hash key is generated for it based on its type and value. The generated key is saved in the string object, and it is then checked against a special table of strings located in the heap. If such a key exists in the table, the corresponding JS variable will receive a reference to the existing string object. Otherwise, a new string object will be created, and the key will be placed in the table. This process is called internalization.

InternalizedString

Just above, I mentioned that in the internal representation of V8, there are many types of strings. Internalized strings, in their most basic form, receive the type InternalizedString, which indicates that the string is located in the StringTable.

As usual, let's take a look at the structure of the string inside the engine by compiling V8 in debug mode and running it with the flag --allow-natives-syntax.

d8> %DebugPrint("FrontendAlmanac")

DebugPrint: 0x28db000d9b99: [String] in OldSpace: #FrontendAlmanac
0x28db000003d5: [Map] in ReadOnlySpace
 - map: 0x28db000004c5 <MetaMap (0x28db0000007d <null>)>
 - type: INTERNALIZED_ONE_BYTE_STRING_TYPE
 - instance size: variable
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - stable_map
 - non-extensible
 - back pointer: 0x28db00000061 <undefined>
 - prototype_validity cell: 0
 - instance descriptors (own) #0: 0x28db00000701 <DescriptorArray[0]>
 - prototype: 0x28db0000007d <null>
 - constructor: 0x28db0000007d <null>
 - dependent code: 0x28db000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

The first thing we see here is the type INTERNALIZED_ONE_BYTE_STRING_TYPE, which means that the string is one-byte and placed in the StringTable. Let's try to create another string literal with the same value.

d8> const string2 = "FrontendAlmanac";
d8> %DebugPrint(string2);

DebugPrint: 0x28db000d9b99: [String] in OldSpace: #FrontendAlmanac
0x28db000003d5: [Map] in ReadOnlySpace
 - map: 0x28db000004c5 <MetaMap (0x28db0000007d <null>)>
 - type: INTERNALIZED_ONE_BYTE_STRING_TYPE
 - instance size: variable
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - stable_map
 - non-extensible
 - back pointer: 0x28db00000061 <undefined>
 - prototype_validity cell: 0
 - instance descriptors (own) #0: 0x28db00000701 <DescriptorArray[0]>
 - prototype: 0x28db0000007d <null>
 - constructor: 0x28db0000007d <null>
 - dependent code: 0x28db000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

Notice that the constant string2 refers to the exact same string instance at the address 0x28db000d9b99.

We can observe a similar situation in the Chrome browser.

// Замкнем значения в функции
function V8Snapshot() {
  this.string1 = "FrontendAlmanac";
  this.string2 = "FrontendAlmanac";
}

const v8Snapshot = new V8Snapshot();

Both V8Snapshot properties refer to the same address @61559. The contents of the entire StringTable can be seen right there in the snapshot in the (string) object.

Here, we can find our string and see which variables refer to it.

You have probably noticed that in addition to our string, there are over 4k other values in the table. The thing is, V8 also stores its internal strings here, including keywords, different names of system methods and functions, and even texts of JavaScript scripts.

SeqString

The concept of InternalizedString appeared relatively recently, in 2018, as part of the TurboFan optimizing compiler. Before this, plain strings had the type SeqString. Technically, InternalizedString differs from SeqString in its internal structure. Specifically, the classes SeqOneByteString and SeqTwoByteString contain a pointer to a character array chars and a number of methods that can interact with it. The implementation of the SeqString class looks literally as follows:

/src/objects/string.h#733

// The SeqString abstract class captures sequential string values.
class SeqString : public String {
 public:
  // Truncate the string in-place if possible and return the result.
  // In case of new_length == 0, the empty string is returned without
  // truncating the original string.
  V8_WARN_UNUSED_RESULT static Handle<String> Truncate(Isolate* isolate,
                                                       Handle<SeqString> string,
                                                       int new_length);
                                                       
  struct DataAndPaddingSizes {
    const int data_size;
    const int padding_size;
    bool operator==(const DataAndPaddingSizes& other) const {
      return data_size == other.data_size && padding_size == other.padding_size;
    }
  };
  DataAndPaddingSizes GetDataAndPaddingSizes() const;
  
  // Zero out only the padding bytes of this string.
  void ClearPadding();
  
  EXPORT_DECL_VERIFIER(SeqString)
};

One of its descendants, SeqOneByteString, looks like this:

/src/objects/string.h#763

// The OneByteString class captures sequential one-byte string objects.
// Each character in the OneByteString is an one-byte character.
V8_OBJECT class SeqOneByteString : public SeqString {
 public:
  static const bool kHasOneByteEncoding = true;
  using Char = uint8_t;
  
  V8_INLINE static constexpr int32_t DataSizeFor(int32_t length);
  V8_INLINE static constexpr int32_t SizeFor(int32_t length);
  
  // Dispatched behavior. The non SharedStringAccessGuardIfNeeded method is also
  // defined for convenience and it will check that the access guard is not
  // needed.
  inline uint8_t Get(int index) const;
  inline uint8_t Get(int index,
                     const SharedStringAccessGuardIfNeeded& access_guard) const;
  inline void SeqOneByteStringSet(int index, uint16_t value);
  inline void SeqOneByteStringSetChars(int index, const uint8_t* string,
                                       int length);
                                       
  // Get the address of the characters in this string.
  inline Address GetCharsAddress() const;
  
  // Get a pointer to the characters of the string. May only be called when a
  // SharedStringAccessGuard is not needed (i.e. on the main thread or on
  // read-only strings).
  inline uint8_t* GetChars(const DisallowGarbageCollection& no_gc);
  
  // Get a pointer to the characters of the string.
  inline uint8_t* GetChars(const DisallowGarbageCollection& no_gc,
                           const SharedStringAccessGuardIfNeeded& access_guard);
                           
  DataAndPaddingSizes GetDataAndPaddingSizes() const;
  
  // Initializes padding bytes. Potentially zeros tail of the payload too!
  inline void clear_padding_destructively(int length);
  
  // Maximal memory usage for a single sequential one-byte string.
  static const int kMaxCharsSize = kMaxLength;
  
  inline int AllocatedSize() const;
  
  // A SeqOneByteString have different maps depending on whether it is shared.
  static inline bool IsCompatibleMap(Tagged<Map> map, ReadOnlyRoots roots);
  
  class BodyDescriptor;
  
 private:
  friend struct OffsetsForDebug;
  friend class CodeStubAssembler;
  friend class ToDirectStringAssembler;
  friend class IntlBuiltinsAssembler;
  friend class StringBuiltinsAssembler;
  friend class StringFromCharCodeAssembler;
  friend class maglev::MaglevAssembler;
  friend class compiler::AccessBuilder;
  friend class TorqueGeneratedSeqOneByteStringAsserts;
  
  FLEXIBLE_ARRAY_MEMBER(Char, chars);
} V8_OBJECT_END;

For comparison, the InternalizedString class looks like this:

/src/objects/string.h#758

V8_OBJECT class InternalizedString : public String{

  // TODO(neis): Possibly move some stuff from String here.
} V8_OBJECT_END;

As you can see, there is no implementation here at all, as the concept of InternalizedString was introduced merely for the sake of terminology. In fact, all the logic related to memory allocation, encoding, decoding, comparing, and modifying strings is handled in the base class String. Characters are stored not as an array but directly as a sequence of 32-bit or 64-bit character codes in memory. The class itself only has a system pointer to the beginning of the corresponding memory area. This structure is referred to as "FlatContent," and the strings are thus called flat strings.

V8_OBJECT class String : public Name {
  ...
 private:
  union {
    const uint8_t* onebyte_start;
    const base::uc16* twobyte_start;
  };
  ...
}

So, what is SeqString in practice?

d8> const seqString = [
  "F", "r", "o", "n", "t", "e", "n", "d",
  "A", "l", "m", "a", "n", "a", "c"
].join("");
d8> 
d8> %DebugPrint(seqString);

DebugPrint: 0x2353001c94e1: [String]: "FrontendAlmanac"
0x235300000105: [Map] in ReadOnlySpace
 - map: 0x2353000004c5 <MetaMap (0x23530000007d <null>)>
 - type: SEQ_ONE_BYTE_STRING_TYPE
 - instance size: variable
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - stable_map
 - non-extensible
 - back pointer: 0x235300000061 <undefined>
 - prototype_validity cell: 0
 - instance descriptors (own) #0: 0x235300000701 <DescriptorArray[0]>
 - prototype: 0x23530000007d <null>
 - constructor: 0x23530000007d <null>
 - dependent code: 0x2353000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

In the example above, the string was created by combining elements of an array. Since the array had to be created regardless during this operation, and the resulting string cannot be checked in the StringTable until it has been combined, the variable is assigned the type SeqString.

Let’s modify the previous example a bit.

function V8Snapshot() {
  this.string1 = "FrontendAlmanac";
  this.string2 = [
    "F", "r", "o", "n", "t", "e", "n", "d",
    "A", "l", "m", "a", "n", "a", "c"
  ].join("");
}

const v8Snapshot = new V8Snapshot();

How will the string table look in this case?

Since string1 and string2 are two different objects with different types of strings, each of them has its own address. Moreover, each of them will have its own unique hash key. Therefore, in the table, we can see two identical values with different keys. In other words, there are duplicate strings. Generally, all such duplicates can be seen by applying the Duplicated strings filter in the snapshot.

Furthermore, if we attempt to create several SeqString objects with the same value, their duplicates also will not appear in the table.

function V8Snapshot() {
  this.string1 = "FrontendAlmanac";
  this.string2 = [
    "F", "r", "o", "n", "t", "e", "n", "d",
    "A", "l", "m", "a", "n", "a", "c"
  ].join("");
  this.string3 = [
    "F", "r", "o", "n", "t", "e", "n", "d",
    "A", "l", "m", "a", "n", "a", "c"
  ].join("");
}

const v8Snapshot = new V8Snapshot();

ConsString

Let's consider another example.

d8> const consString = "Frontend" + "Almanac";
d8> %DebugPrint(consString);

DebugPrint: 0xf0001c952d: [String]: c"FrontendAlmanac"
0xf000000155: [Map] in ReadOnlySpace
 - map: 0x00f0000004c5 <MetaMap (0x00f00000007d <null>)>
 - type: CONS_ONE_BYTE_STRING_TYPE
 - instance size: 20
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - non-extensible
 - back pointer: 0x00f000000061 <undefined>
 - prototype_validity cell: 0
 - instance descriptors (own) #0: 0x00f000000701 <DescriptorArray[0]>
 - prototype: 0x00f00000007d <null>
 - constructor: 0x00f00000007d <null>
 - dependent code: 0x00f0000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

The variable consString is formed by concatenating two string literals. Such strings are given the type ConsString.

/src/objects/string.h#916

V8_OBJECT class ConsString : public String {
 public:
  inline Tagged<String> first() const;
  inline void set_first(Tagged<String> value,
                        WriteBarrierMode mode = UPDATE_WRITE_BARRIER);
  
  inline Tagged<String> second() const;
  inline void set_second(Tagged<String> value,
                         WriteBarrierMode mode = UPDATE_WRITE_BARRIER);
  
  // Doesn't check that the result is a string, even in debug mode.  This is
  // useful during GC where the mark bits confuse the checks.
  inline Tagged<Object> unchecked_first() const;
  
  // Doesn't check that the result is a string, even in debug mode.  This is
  // useful during GC where the mark bits confuse the checks.
  inline Tagged<Object> unchecked_second() const;
  
  V8_INLINE bool IsFlat() const;
  
  // Dispatched behavior.
  V8_EXPORT_PRIVATE uint16_t
  Get(int index, const SharedStringAccessGuardIfNeeded& access_guard) const;
  
  // Minimum length for a cons string.
  static const int kMinLength = 13;
  
  DECL_VERIFIER(ConsString)
  
 private:
  friend struct ObjectTraits<ConsString>;
  friend struct OffsetsForDebug;
  friend class V8HeapExplorer;
  friend class CodeStubAssembler;
  friend class ToDirectStringAssembler;
  friend class StringBuiltinsAssembler;
  friend class maglev::MaglevAssembler;
  friend class compiler::AccessBuilder;
  friend class TorqueGeneratedConsStringAsserts;
  
  friend Tagged<String> String::GetUnderlying() const;
  
  TaggedMember<String> first_;
  TaggedMember<String> second_;
} V8_OBJECT_END;

The ConsString class has two pointers to other strings, which can in turn be of any type, including ConsString. As a result, this type can form a binary tree of ConsString nodes, where the leaves are not ConsString. The final value of such a string is obtained by concatenating the leaves of the tree from left to right, from the deepest node to the first one.

function V8Snapshot() {
  this.string1 = "FrontendAlmanac";
  this.string2 = "Frontend" + "Almanac";
  this.string3 = "Frontend" + "Almanac";
}

const v8Snapshot = new V8Snapshot();

Just like with SeqString, each concatenated string has its own instance of the class and, accordingly, its own hash key. These strings can also be duplicated in the string table. However, in the table, we can also find the internalized leaves of this concatenation.

It is important to make a disclaimer. Not every concatenation operation results in the creation of a ConsString.

d8> const string = "a" + "b";
d8> %DebugPrint(string);

DebugPrint: 0x1d48001c9ec5: [String]: "ab"
0x1d4800000105: [Map] in ReadOnlySpace
 - map: 0x1d48000004c5 <MetaMap (0x1d480000007d <null>)>
 - type: SEQ_ONE_BYTE_STRING_TYPE
 - instance size: variable
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - stable_map
 - non-extensible
 - back pointer: 0x1d4800000061 <undefined>
 - prototype_validity cell: 0
 - instance descriptors (own) #0: 0x1d4800000701 <DescriptorArray[0]>
 - prototype: 0x1d480000007d <null>
 - constructor: 0x1d480000007d <null>
 - dependent code: 0x1d48000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

In the example above, the string is represented by the type SeqString. The fact is that the procedures for reading and writing to the ConsString structure are not free. While the structure itself is considered efficient in terms of memory optimization, all the advantages become evident only with relatively long strings. In the case of short strings, the overhead of maintaining a binary tree nullifies these advantages. Therefore, the V8 developers empirically determined a critical string length below which the ConsString structure is inefficient. This number is 13.

/src/objects/string.h#940

// Minimum length for a cons string.
static const int kMinLength = 13;

SlicedString

d8> const parentString = " FrontendAlmanac FrontendAlmanac ";
d8> const slicedString1 = parentString.substring(1, 16);
d8> const slicedString2 = parentString.slice(1, 16);
d8> const slicedString3 = parentString.trim();
d8> 
d8> %DebugPrint(slicedString1);

DebugPrint: 0x312b001c9509: [String]: "FrontendAlmanac"
0x312b000001a5: [Map] in ReadOnlySpace
 - map: 0x312b000004c5 <MetaMap (0x312b0000007d <null>)>
 - type: SLICED_ONE_BYTE_STRING_TYPE
 - instance size: 20
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - stable_map
 - non-extensible
 - back pointer: 0x312b00000061 <undefined>
 - prototype_validity cell: 0
 - instance descriptors (own) #0: 0x312b00000701 <DescriptorArray[0]>
 - prototype: 0x312b0000007d <null>
 - constructor: 0x312b0000007d <null>
 - dependent code: 0x312b000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

This type is assigned to strings formed as a result of being a substring of another string. Such operations include substring(), slice() and trimming methods trim(), trimStart(), and trimEnd().

The SlicedString class stores only a pointer to the parent string, along with the offset and length of the sequence within the parent string. This significantly reduces memory usage and improves performance when working with such strings. However, the same rule applies here as with ConsString: the length of the substring must not be less than 13 characters. Otherwise, this optimization loses its value, as SlicedString requires unpacking the parent string and adding the offset to the starting address of the sequence.

Another important feature is that SlicedString cannot be nested.

function V8Snapshot() {
  this.parentString = " FrontendAlmanac FrontendAlmanac ";
  this.slicedString1 = this.parentString.trim();
  this.slicedString2 = this.slicedString1.substring(0, 15);
}

const v8Snapshot = new V8Snapshot();

In the example above, we attempt to create a SlicedString from another SlicedString. However, slicedString1 cannot be the parent string because it is itself a SlicedString.

Therefore, the parent string for both properties will be "parentString".

ThinString

There are instances when it is necessary to internalize a string, but for some reason, it cannot be done immediately. In such cases, a new string object is created and internalized, while the original string is converted into a ThinString type, which essentially serves as a reference to its internalized version. ThinString is very similar to ConsString, but it only contains a single reference.

d8> const string = "Frontend" + "Almanac"; // create ConsString
d8> const obj = {};
d8> 
d8> obj[string]; // convert to ThinString
d8> 
d8> %DebugPrint(string);

DebugPrint: 0x335f001c947d: [String]: >"FrontendAlmanac"
0x335f00000425: [Map] in ReadOnlySpace
 - map: 0x335f000004c5 <MetaMap (0x335f0000007d <null>)>
 - type: THIN_ONE_BYTE_STRING_TYPE
 - instance size: 16
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - stable_map
 - non-extensible
 - back pointer: 0x335f00000061 <undefined>
 - prototype_validity cell: 0
 - instance descriptors (own) #0: 0x335f00000701 <DescriptorArray[0]>
 - prototype: 0x335f0000007d <null>
 - constructor: 0x335f0000007d <null>
 - dependent code: 0x335f000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

In the example above, we first create a ConsString. We then use this string as a key for an object. To find the key in the object's properties array, the string needs to be flat; however, at this point, it is represented as a binary tree with two nodes. In this situation, the engine is forced to compute a flat value from the ConsString, create a new string object, intern it, and convert the original string into a ThinString. This particular case was mentioned in an article about string cleansing on Habr, although it did not explain why this occurs.

Now, let's take a look at DevTools. We won't be able to see the ThinString here, but we can observe that the property string is represented as InternalizedString. This is because ThinString, I reiterate, is merely a reference to the internalized version of the string.

ExternalString

Another type of string is the ExternalString. The V8 engine provides the capability to create and store strings outside the engine itself. To facilitate this, the ExternalString type and the corresponding API were introduced. References to these strings are stored in a separate table called the ExternalStringTable in the heap. Typically, such strings are created by the engine consumer for their specific needs. For instance, browsers might store external resources in this way. Additionally, the consumer can fully control the lifecycle of these resources, with one caveat: the consumer must ensure that such strings are not deallocated while the ExternalString object is alive in the V8 heap.

The screenshot above shows one of these strings created by the browser. However, we can also create our own. To do this, we can use the internal API method externalizeString (V8 must be started with the --allow-natives-syntax flag).

//> d8 --allow-natives-syntax --expose-externalize-string
d8> const string = "FrontendAlmanac";
d8> 
d8> externalizeString(string);
d8> 
d8> %DebugPrint(string);

DebugPrint: 0x7d6000da08d: [String] in OldSpace: #FrontendAlmanac
0x7d600000335: [Map] in ReadOnlySpace
 - map: 0x07d6000004c5 <MetaMap (0x07d60000007d <null>)>
 - type: EXTERNAL_INTERNALIZED_ONE_BYTE_STRING_TYPE
 - instance size: 20
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - stable_map
 - non-extensible
 - back pointer: 0x07d600000061 <undefined>
 - prototype_validity cell: 0
 - instance descriptors (own) #0: 0x07d600000701 <DescriptorArray[0]>
 - prototype: 0x07d60000007d <null>
 - constructor: 0x07d60000007d <null>
 - dependent code: 0x07d6000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

Garbage Collection

Strings, like any other variables, participate in the garbage collection process. I've covered this topic in detail in my article Garbage Collection in V8, so I won't go into it here. More interestingly, the StringTable itself also participates in this process. To be precise, any transformations and deletions of strings in the StringTable occur during Full GC. For this, a temporary table called the StringForwardingTable is used, into which only relevant strings are placed during garbage collection. After this, the reference to the StringTable is updated to point to the new table.

Conclusion

So, we have familiarized ourselves with the organization of strings within the V8 engine. We have learned more about the string table and the different types of strings.

Here are some key points and conclusions.

Strings can be one-byte or two-byte. Two-byte strings require approximately twice as much memory, as each character in such a string is encoded with two bytes, regardless of whether it is an ASCII character or not. Therefore, if you have a choice of which string to use, a one-byte string is preferable in most cases.

const myMap = {
  "Frontend Almanac": undefined, // one-byte key,
  "Frontend Альманах": undefined, // two-byte key
}

Despite the specified number 2**53 - 1 in the specification, the actual length of strings on real systems is much lower. On 32-bit systems, V8 allows storing strings no longer than 2**28 - 16 characters, whereas on 64-bit systems, it is no more than 2**29 - 24 characters.

Seq, Cons, and Sliced strings can be duplicated in the string table.

const string1 = "FrontendAlmanac"; // creates internalized string
const string2 = "FrontendAlmanac"; // doesn't create new string
const string3 = "Frontend" + "Almanac"; // creates duplicated string

SlicedStrings cannot be nested. They always refer to the original internalized string. The parent string remains alive as long as at least one of its child SlicedStrings exists.

let parentString = "FrontendAlmanac"; // parent string
let slicedString1 = parentString.slice(1); // refers to the parentString
let slicedString2 = slicedString1.slice(1); // also refers to the parentString
let slicedString3 = slicedString2.slice(1); // and this one too

slicedString1 = undefind;
slicedString2 = undefind;
// parentString still not garbage collected
// as the slicedString3 is stil alive

If a string needs to be internalized but cannot be done "in place" — for example, if it is a Cons or Sliced string — the engine will calculate the flat value, create a new internalized string object, and convert the reference to this internalized version.

const string = "Frontend" + "Almanac"; // ConsString

const obj = {};
obj[string]; // ThinString

// string is not ConsString anymore, now it's ThinString and refers to
// a flat internalized valued in the StringTable

The previous example can be used to eliminate duplicate strings in the StringTable, as suggested in the article about string cleansing.

const string1 = "FrontendAlmanac";
const string2 = "Frontend" + "Almanac"; // creates duplicate
const string3 = "Frontend" + "Almanac"; // creates duplicate

const obj = {};
obj[string2]; // ThinSting
obj[string3]; // ThinString

// Now the string2 and string3 are not ConsString anymoer and they refer
// to their internalized version, in this case to the string1,
// which is already in the StringTable.

I have described only a few cases of working with strings. The article's format is not sufficient to cover all possible features and special cases. Therefore, I invite everyone to share their experiences and ask questions in the comments on my Telegram channel.

My telegram channels:

EN - https://t.me/frontend_almanac
RU - https://t.me/frontend_almanac_ru

Русская версия: https://blog.frontend-almanac.ru/v8-strings

React. Nodes update and memoization

2024-06-12T11:59:03.630Z

During the development of modern web applications, performance often becomes one of the key aspects that concern both developers and users. Users expect lightning-fast responsiveness, and developers strive to create applications that work quickly and efficiently.

One powerful tool that enables high performance in React applications is memoization. Memoization helps significantly reduce the amount of computations and, consequently, interface updates, which positively impacts the overall speed and responsiveness of the application.

In this article, we will delve "under the hood" of the React engine and see how node updates occur. At the same time, we will also explore the basic principles of memoization and its application in different types of components.

What is memoization?

Let's start with the theory. Formally, memoization can be defined as an optimization technique used to increase the performance of programs by storing the results of function calls and returning the saved result for subsequent calls with the same arguments.

In the context of React, memoization is especially useful for preventing unnecessary redraws and improving the performance of applications. In other words, it helps avoid unnecessary updates of components, making the application more reactive and efficient. Another equally important property of memoization is reducing the number of expensive computations. Instead of performing them on every component render, you can "remember the result" and recalculate it only in case of changes in the corresponding input parameters.

Where exactly is the memoized result stored?

To answer this question, we need to introduce the concept of React Fiber. I extensively described this structure in the article In-Depth React: Reconciliation, Renders, Fiber, Virtual Tree. In short, Fiber is an abstract entity in the React engine that describes any processed React node, whether it's a component, hook, or host root. Fiber has properties like pendingProps, memoizedProps, and memoizedState, among others. It is in these properties that the memoized result is stored. How exactly? Let's find out.

Memoized Components

Although the principles of memoization in React are the same for all entities, the implementation details may vary depending on the type of Fiber. To understand the process, we need to go through each type separately. Let's start with components, which are the "oldest" structure in React.

Since the early versions of React, we have been used to distinguishing components into class and functional components. In reality, there are many more component types inside the engine. The component type corresponds to the Fiber type and is specified in the Fiber.tag property. In the mentioned article, I provided a full list of types for React version 18.2, which included a total of 28 types. In version 18.3.1, the list has slightly changed, now totaling 26 types.

export const FunctionComponent = 0;
export const ClassComponent = 1;
export const IndeterminateComponent = 2; // Before we know whether it is function or class
export const HostRoot = 3; // Root of a host tree. Could be nested inside another node.
export const HostPortal = 4; // A subtree. Could be an entry point to a different renderer.
export const HostComponent = 5;
export const HostText = 6;
export const Fragment = 7;
export const Mode = 8;
export const ContextConsumer = 9;
export const ContextProvider = 10;
export const ForwardRef = 11;
export const Profiler = 12;
export const SuspenseComponent = 13;
export const MemoComponent = 14;
export const SimpleMemoComponent = 15;
export const LazyComponent = 16;
export const IncompleteClassComponent = 17;
export const DehydratedFragment = 18;
export const SuspenseListComponent = 19;
export const ScopeComponent = 21;
export const OffscreenComponent = 22;
export const LegacyHiddenComponent = 23;
export const CacheComponent = 24;
export const TracingMarkerComponent = 25;

To understand the memoization processes, we only need three items from this list:

export const FunctionComponent = 0;
export const ClassComponent = 1;
export const MemoComponent = 14;

When does memoization occur?

Before delving into the Fiber types directly, it is worth understanding at which specific moment the memoization process is triggered. In the previous article, I outlined four processing phases for a node. The first phase, begin, determines the Fiber type that will initiate the necessary lifecycle. Nodes that have not yet been mounted have types like IndeterminateComponent, LazyComponent, or IncompleteClassComponent. For such Fibers, the mounting process will be initiated. In other cases, the reconciler will attempt to update the existing node. To be more specific, the decision tree is processed by the reconciler's beginWork function.

/packages/react-reconciler/src/ReactFiberBeginWork.new.js#L3699

function beginWork(
  current: Fiber | null,
  workInProgress: Fiber,
  renderLanes: Lanes,
): Fiber | null {
  ...
  
  switch (workInProgress.tag) {
    case IndeterminateComponent: {
      return mountIndeterminateComponent(
        current,
        workInProgress,
        workInProgress.type,
        renderLanes,
      );
    }
    case LazyComponent: {
      const elementType = workInProgress.elementType;
      return mountLazyComponent(
        current,
        workInProgress,
        elementType,
        renderLanes,
      );
    }
    case FunctionComponent: {
      const Component = workInProgress.type;
      const unresolvedProps = workInProgress.pendingProps;
      const resolvedProps =
        workInProgress.elementType === Component
          ? unresolvedProps
          : resolveDefaultProps(Component, unresolvedProps);
      return updateFunctionComponent(
        current,
        workInProgress,
        Component,
        resolvedProps,
        renderLanes,
      );
    }
    case ClassComponent: {
      const Component = workInProgress.type;
      const unresolvedProps = workInProgress.pendingProps;
      const resolvedProps =
        workInProgress.elementType === Component
          ? unresolvedProps
          : resolveDefaultProps(Component, unresolvedProps);
      return updateClassComponent(
        current,
        workInProgress,
        Component,
        resolvedProps,
        renderLanes,
      );
    }
    case HostRoot:
      return updateHostRoot(current, workInProgress, renderLanes);
    case HostComponent:
      return updateHostComponent(current, workInProgress, renderLanes);
    case HostText:
      return updateHostText(current, workInProgress);
    case SuspenseComponent:
      return updateSuspenseComponent(current, workInProgress, renderLanes);
    case HostPortal:
      return updatePortalComponent(current, workInProgress, renderLanes);
    case ForwardRef: {
      const type = workInProgress.type;
      const unresolvedProps = workInProgress.pendingProps;
      const resolvedProps =
        workInProgress.elementType === type
          ? unresolvedProps
          : resolveDefaultProps(type, unresolvedProps);
      return updateForwardRef(
        current,
        workInProgress,
        type,
        resolvedProps,
        renderLanes,
      );
    }
    case Fragment:
      return updateFragment(current, workInProgress, renderLanes);
    case Mode:
      return updateMode(current, workInProgress, renderLanes);
    case Profiler:
      return updateProfiler(current, workInProgress, renderLanes);
    case ContextProvider:
      return updateContextProvider(current, workInProgress, renderLanes);
    case ContextConsumer:
      return updateContextConsumer(current, workInProgress, renderLanes);
    case MemoComponent: {
      const type = workInProgress.type;
      const unresolvedProps = workInProgress.pendingProps;
      // Resolve outer props first, then resolve inner props.
      let resolvedProps = resolveDefaultProps(type, unresolvedProps);
      resolvedProps = resolveDefaultProps(type.type, resolvedProps);
      return updateMemoComponent(
        current,
        workInProgress,
        type,
        resolvedProps,
        renderLanes,
      );
    }
    case SimpleMemoComponent: {
      return updateSimpleMemoComponent(
        current,
        workInProgress,
        workInProgress.type,
        workInProgress.pendingProps,
        renderLanes,
      );
    }
    case IncompleteClassComponent: {
      const Component = workInProgress.type;
      const unresolvedProps = workInProgress.pendingProps;
      const resolvedProps =
        workInProgress.elementType === Component
          ? unresolvedProps
          : resolveDefaultProps(Component, unresolvedProps);
      return mountIncompleteClassComponent(
        current,
        workInProgress,
        Component,
        resolvedProps,
        renderLanes,
      );
    }
    case SuspenseListComponent: {
      return updateSuspenseListComponent(current, workInProgress, renderLanes);
    }
    case ScopeComponent: {
      if (enableScopeAPI) {
        return updateScopeComponent(current, workInProgress, renderLanes);
      }
      break;
    }
    case OffscreenComponent: {
      return updateOffscreenComponent(current, workInProgress, renderLanes);
    }
    case LegacyHiddenComponent: {
      if (enableLegacyHidden) {
        return updateLegacyHiddenComponent(
          current,
          workInProgress,
          renderLanes,
        );
      }
      break;
    }
    case CacheComponent: {
      if (enableCache) {
        return updateCacheComponent(current, workInProgress, renderLanes);
      }
      break;
    }
    case TracingMarkerComponent: {
      if (enableTransitionTracing) {
        return updateTracingMarkerComponent(
          current,
          workInProgress,
          renderLanes,
        );
      }
      break;
    }
  }
  
  ...
}

From the memoization perspective, whether a component is mounted or updated, there is not a significant difference. Ultimately, the corresponding component update methods will be called regardless. The only distinction lies in whether the previous property values, state, or dependencies are passed into these methods. I will leave the process of transforming mountable types into updatable ones for future publications and suggest moving directly to the specific node update methods.

ClassComponent

The name indicates that this type is assigned to class components. Just in case, let's recall how a class component is created.

class MyComponent extends React.Component<{ prop1: string }> {
  render() {
    return (
      <div>
        {this.props.prop1}
      </div>
    );
  }
}

In the provided beginWork, the update of class components begins as follows.

const Component = workInProgress.type;
const unresolvedProps = workInProgress.pendingProps;
const resolvedProps =
  workInProgress.elementType === Component
    ? unresolvedProps
    : resolveDefaultProps(Component, unresolvedProps);
return updateClassComponent(
  current,
  workInProgress,
  Component,
  resolvedProps,
  renderLanes,
);

The first thing that catches the eye here is the constant resolvedProps. Despite the 5 lines of code, this constant simply takes the Fiber.pendingProps property, which is nothing but an object with the new component properties. To make it clear, I will also provide the code of the resolveDefaultProps function.

/packages/react-reconciler/src/ReactFiberLazyComponent.new.js#L12

export function resolveDefaultProps(Component: any, baseProps: Object): Object {
  if (Component && Component.defaultProps) {
    // Resolve default props. Taken from ReactElement
    const props = assign({}, baseProps);
    const defaultProps = Component.defaultProps;
    for (const propName in defaultProps) {
      if (props[propName] === undefined) {
        props[propName] = defaultProps[propName];
      }
    }
    return props;
  }
  return baseProps;
}

In more human terms, this function simply assigns default values to properties if they were specified when creating the component.

class MyComponent extends React.Component<{ color?: string }> {
  static defaultProps = {
    color: 'blue',
  };

  render() {
    return (
      <div>
        {this.props.color}
      </div>
    );
  }
}

<MyComponent />              // <div>blue</div>
<MyComponent color="red" />  // <div>red</div>

The update mechanism itself is moved to the updateClassComponent function. I will provide its code in a shortened form, as part of the functionality deals with processing the context provider and some service operations for dev mode.

/packages/react-reconciler/src/ReactFiberBeginWork.new.js#L1062

function updateClassComponent(
  current: Fiber | null,
  workInProgress: Fiber,
  Component: any,
  nextProps: any,
  renderLanes: Lanes,
) {
  ...
  const instance = workInProgress.stateNode;
  let shouldUpdate;
  if (instance === null) {
    resetSuspendedCurrentOnMountInLegacyMode(current, workInProgress);
    
    // In the initial pass we might need to construct the instance.
    constructClassInstance(workInProgress, Component, nextProps);
    mountClassInstance(workInProgress, Component, nextProps, renderLanes);
    shouldUpdate = true;
  } else if (current === null) {
    // In a resume, we'll already have an instance we can reuse.
    shouldUpdate = resumeMountClassInstance(
      workInProgress,
      Component,
      nextProps,
      renderLanes,
    );
  } else {
    shouldUpdate = updateClassInstance(
      current,
      workInProgress,
      Component,
      nextProps,
      renderLanes,
    );
  }
  const nextUnitOfWork = finishClassComponent(
    current,
    workInProgress,
    Component,
    shouldUpdate,
    hasContext,
    renderLanes,
  );
  ...
  return nextUnitOfWork;
}

The first two "if" statements here are responsible for the process of mounting a new component. As mentioned earlier, we will not delve into these processes separately because ultimately the cycle will come to the update function where all the memoization work will take place. Specifically, it happens in the updateClassInstance function, which I will present in its entirety.

/packages/react-reconciler/src/ReactFiberClassComponent.new.js#L1123

// Invokes the update life-cycles and returns false if it shouldn't rerender.
function updateClassInstance(
  current: Fiber,
  workInProgress: Fiber,
  ctor: any,
  newProps: any,
  renderLanes: Lanes,
): boolean {
  const instance = workInProgress.stateNode;
  
  cloneUpdateQueue(current, workInProgress);
  
  const unresolvedOldProps = workInProgress.memoizedProps;
  const oldProps =
    workInProgress.type === workInProgress.elementType
      ? unresolvedOldProps
      : resolveDefaultProps(workInProgress.type, unresolvedOldProps);
  instance.props = oldProps;
  const unresolvedNewProps = workInProgress.pendingProps;
  
  const oldContext = instance.context;
  const contextType = ctor.contextType;
  let nextContext = emptyContextObject;
  if (typeof contextType === 'object' && contextType !== null) {
    nextContext = readContext(contextType);
  } else if (!disableLegacyContext) {
    const nextUnmaskedContext = getUnmaskedContext(workInProgress, ctor, true);
    nextContext = getMaskedContext(workInProgress, nextUnmaskedContext);
  }
  
  const getDerivedStateFromProps = ctor.getDerivedStateFromProps;
  const hasNewLifecycles =
    typeof getDerivedStateFromProps === 'function' ||
    typeof instance.getSnapshotBeforeUpdate === 'function';
    
  // Note: During these life-cycles, instance.props/instance.state are what
  // ever the previously attempted to render - not the "current". However,
  // during componentDidUpdate we pass the "current" props.
  
  // In order to support react-lifecycles-compat polyfilled components,
  // Unsafe lifecycles should not be invoked for components using the new APIs.
  if (
    !hasNewLifecycles &&
    (typeof instance.UNSAFE_componentWillReceiveProps === 'function' ||
      typeof instance.componentWillReceiveProps === 'function')
  ) {
    if (
      unresolvedOldProps !== unresolvedNewProps ||
      oldContext !== nextContext
    ) {
      callComponentWillReceiveProps(
        workInProgress,
        instance,
        newProps,
        nextContext,
      );
    }
  }
  
  resetHasForceUpdateBeforeProcessing();
  
  const oldState = workInProgress.memoizedState;
  let newState = (instance.state = oldState);
  processUpdateQueue(workInProgress, newProps, instance, renderLanes);
  newState = workInProgress.memoizedState;
  
  if (
    unresolvedOldProps === unresolvedNewProps &&
    oldState === newState &&
    !hasContextChanged() &&
    !checkHasForceUpdateAfterProcessing() &&
    !(
      enableLazyContextPropagation &&
      current !== null &&
      current.dependencies !== null &&
      checkIfContextChanged(current.dependencies)
    )
  ) {
    // If an update was already in progress, we should schedule an Update
    // effect even though we're bailing out, so that cWU/cDU are called.
    if (typeof instance.componentDidUpdate === 'function') {
      if (
        unresolvedOldProps !== current.memoizedProps ||
        oldState !== current.memoizedState
      ) {
        workInProgress.flags |= Update;
      }
    }
    if (typeof instance.getSnapshotBeforeUpdate === 'function') {
      if (
        unresolvedOldProps !== current.memoizedProps ||
        oldState !== current.memoizedState
      ) {
        workInProgress.flags |= Snapshot;
      }
    }
    return false;
  }
  
  if (typeof getDerivedStateFromProps === 'function') {
    applyDerivedStateFromProps(
      workInProgress,
      ctor,
      getDerivedStateFromProps,
      newProps,
    );
    newState = workInProgress.memoizedState;
  }
  
  const shouldUpdate =
    checkHasForceUpdateAfterProcessing() ||
    checkShouldComponentUpdate(
      workInProgress,
      ctor,
      oldProps,
      newProps,
      oldState,
      newState,
      nextContext,
    ) ||
    // TODO: In some cases, we'll end up checking if context has changed twice,
    // both before and after `shouldComponentUpdate` has been called. Not ideal,
    // but I'm loath to refactor this function. This only happens for memoized
    // components so it's not that common.
    (enableLazyContextPropagation &&
      current !== null &&
      current.dependencies !== null &&
      checkIfContextChanged(current.dependencies));
      
  if (shouldUpdate) {
    // In order to support react-lifecycles-compat polyfilled components,
    // Unsafe lifecycles should not be invoked for components using the new APIs.
    if (
      !hasNewLifecycles &&
      (typeof instance.UNSAFE_componentWillUpdate === 'function' ||
        typeof instance.componentWillUpdate === 'function')
    ) {
      if (typeof instance.componentWillUpdate === 'function') {
        instance.componentWillUpdate(newProps, newState, nextContext);
      }
      if (typeof instance.UNSAFE_componentWillUpdate === 'function') {
        instance.UNSAFE_componentWillUpdate(newProps, newState, nextContext);
      }
    }
    if (typeof instance.componentDidUpdate === 'function') {
      workInProgress.flags |= Update;
    }
    if (typeof instance.getSnapshotBeforeUpdate === 'function') {
      workInProgress.flags |= Snapshot;
    }
  } else {
    // If an update was already in progress, we should schedule an Update
    // effect even though we're bailing out, so that cWU/cDU are called.
    if (typeof instance.componentDidUpdate === 'function') {
      if (
        unresolvedOldProps !== current.memoizedProps ||
        oldState !== current.memoizedState
      ) {
        workInProgress.flags |= Update;
      }
    }
    if (typeof instance.getSnapshotBeforeUpdate === 'function') {
      if (
        unresolvedOldProps !== current.memoizedProps ||
        oldState !== current.memoizedState
      ) {
        workInProgress.flags |= Snapshot;
      }
    }
    
    // If shouldComponentUpdate returned false, we should still update the
    // memoized props/state to indicate that this work can be reused.
    workInProgress.memoizedProps = newProps;
    workInProgress.memoizedState = newState;
  }
  
  // Update the existing instance's state, props, and context pointers even
  // if shouldComponentUpdate returns false.
  instance.props = newProps;
  instance.state = newState;
  instance.context = nextContext;
  
  return shouldUpdate;
}

It may look quite cumbersome, but that's how it is. This is where all the lifecycle magic of class components happens. Let's go through it step by step.

const unresolvedOldProps = workInProgress.memoizedProps;
const oldProps =
  workInProgress.type === workInProgress.elementType
    ? unresolvedOldProps
    : resolveDefaultProps(workInProgress.type, unresolvedOldProps);
instance.props = oldProps;
const unresolvedNewProps = workInProgress.pendingProps;

We have already seen what this is about. The essence of this code is to obtain two constants: unresolvedOldProps, which is immediately assigned to this.props of the component instance, and unresolvedNewProps. These constants will be involved in lifecycle methods and memoization, among other things.

const oldContext = instance.context;
const contextType = ctor.contextType;
let nextContext = emptyContextObject;
if (typeof contextType === 'object' && contextType !== null) {
  nextContext = readContext(contextType);
} else if (!disableLegacyContext) {
  const nextUnmaskedContext = getUnmaskedContext(workInProgress, ctor, true);
  nextContext = getMaskedContext(workInProgress, nextUnmaskedContext);
}

The next block is responsible for resolving the attached context of the component. We won't delve into this part in detail here, but variables like oldContext and nextContext participate in lifecycle methods alongside unresolvedOldProps and unresolvedNewProps, so it is worth noting them.

const getDerivedStateFromProps = ctor.getDerivedStateFromProps;
const hasNewLifecycles =
  typeof getDerivedStateFromProps === 'function' ||
  typeof instance.getSnapshotBeforeUpdate === 'function';
  
// Note: During these life-cycles, instance.props/instance.state are what
// ever the previously attempted to render - not the "current". However,
// during componentDidUpdate we pass the "current" props.

// In order to support react-lifecycles-compat polyfilled components,
// Unsafe lifecycles should not be invoked for components using the new APIs.
if (
  !hasNewLifecycles &&
  (typeof instance.UNSAFE_componentWillReceiveProps === 'function' ||
    typeof instance.componentWillReceiveProps === 'function')
) {
  if (
    unresolvedOldProps !== unresolvedNewProps ||
    oldContext !== nextContext
  ) {
    callComponentWillReceiveProps(
      workInProgress,
      instance,
      newProps,
      nextContext,
    );
  }
}

Another block that I cannot overlook is the one before proceeding to the next stages of the component's lifecycle. It is necessary to first execute the componentWillReceiveProps(nextProps) method if it has been defined in the component. An interesting point here is that this method will only be called if the component does not use the new API, i.e., if it does not have the methods getDerivedStateFromProps(props, state) and getSnapshotBeforeUpdate(prevProps, prevState).

const oldState = workInProgress.memoizedState;
let newState = (instance.state = oldState);
processUpdateQueue(workInProgress, newProps, instance, renderLanes);
newState = workInProgress.memoizedState;

Lastly, the fourth block to consider is the variables oldState and newState, which also play a role in the component's lifecycle. Let's dive a bit deeper into this. While oldState is straightforward and retrieved from Fiber.memoizedState, newState requires further explanation.

By default, newState is assigned the value of the current oldState. Next, the updateQueue loop is executed, triggered by the call to processUpdateQueue. I won't provide the code for this function here as it is quite extensive and variable, which would only distract us from the article's main topic. The key point is to understand that this function eventually generates a new State and writes it to workInProgress.memoizedState.

/packages/react-reconciler/src/ReactFiberClassUpdateQueue.new.js#L458

export function processUpdateQueue<State>(
  ...
  // These values may change as we process the queue.
  if (firstBaseUpdate !== null) {
    ...
    workInProgress.memoizedState = newState;
  }
}

After that, we obtain our variable newState in our update function.

This concludes the gathering of essential information about the component, and the actual updating process begins.

if (
  unresolvedOldProps === unresolvedNewProps &&
  oldState === newState &&
  !hasContextChanged() &&
  !checkHasForceUpdateAfterProcessing() &&
  !(
    enableLazyContextPropagation &&
    current !== null &&
    current.dependencies !== null &&
    checkIfContextChanged(current.dependencies)
  )
) {
  // If an update was already in progress, we should schedule an Update
  // effect even though we're bailing out, so that cWU/cDU are called.
  if (typeof instance.componentDidUpdate === 'function') {
    if (
      unresolvedOldProps !== current.memoizedProps ||
      oldState !== current.memoizedState
    ) {
      workInProgress.flags |= Update;
    }
  }
  if (typeof instance.getSnapshotBeforeUpdate === 'function') {
    if (
      unresolvedOldProps !== current.memoizedProps ||
      oldState !== current.memoizedState
    ) {
      workInProgress.flags |= Snapshot;
    }
  }
  return false;
}

No, this is not an update yet, as it may have initially appeared. Before proceeding with the update, the reconciler excludes unnecessary processing for optimization purposes. In this case, if the references to the component's properties and its state have not changed and forceUpdate() has not been called, there is no point in continuing the process, and the entire function stops.

if (typeof getDerivedStateFromProps === 'function') {
  applyDerivedStateFromProps(
    workInProgress,
    ctor,
    getDerivedStateFromProps,
    newProps,
  );
  newState = workInProgress.memoizedState;
}

Now, if something in the component's state has indeed changed, we can move on to its update. The first step is to call getDerivedStateFromProps(props, state) because it modifies the component's state and, consequently, the newState variable in the update function.

const shouldUpdate =
  checkHasForceUpdateAfterProcessing() ||
  checkShouldComponentUpdate(
    workInProgress,
    ctor,
    oldProps,
    newProps,
    oldState,
    newState,
    nextContext,
  ) ||
  // TODO: In some cases, we'll end up checking if context has changed twice,
  // both before and after `shouldComponentUpdate` has been called. Not ideal,
  // but I'm loath to refactor this function. This only happens for memoized
  // components so it's not that common.
  (enableLazyContextPropagation &&
    current !== null &&
    current.dependencies !== null &&
    checkIfContextChanged(current.dependencies));

Finally, all constants and variables have been gathered, and now a decision can be made regarding the further progression through the lifecycle, specifically, whether the component will be re-rendered. A component should only be re-rendered in two cases: if the values of properties, state, or context differ from the previous ones, or if forceUpdate() has been called. The last one is determined by the checkHasForceUpdateAfterProcessing() function, while the comparison of values occurs within the checkShouldComponentUpdate() function. Let's delve into this function in more detail.

/packages/react-reconciler/src/ReactFiberClassComponent.new.js#L305

function checkShouldComponentUpdate(
  workInProgress,
  ctor,
  oldProps,
  newProps,
  oldState,
  newState,
  nextContext,
) {
  const instance = workInProgress.stateNode;
  if (typeof instance.shouldComponentUpdate === 'function') {
    let shouldUpdate = instance.shouldComponentUpdate(
      newProps,
      newState,
      nextContext,
    );
    ...
    return shouldUpdate;
  }
  
  if (ctor.prototype && ctor.prototype.isPureReactComponent) {
    return (
      !shallowEqual(oldProps, newProps) || !shallowEqual(oldState, newState)
    );
  }
  
  return true;
}

If we remove the auxiliary dev-mode code from the function, it surprisingly turns out to be quite simple. The function encompasses just three scenarios:

The component has a shouldComponentUpdate() method. In this case, the decision of whether the component should be re-rendered is entirely left to the developer.
n the case of a PureComponent, a shallow comparison of properties and state is conducted (we will discuss this in more detail shortly).
In all other cases, the component will be re-rendered anyway.

if (shouldUpdate) {
  // In order to support react-lifecycles-compat polyfilled components,
  // Unsafe lifecycles should not be invoked for components using the new APIs.
  if (
    !hasNewLifecycles &&
    (typeof instance.UNSAFE_componentWillUpdate === 'function' ||
      typeof instance.componentWillUpdate === 'function')
  ) {
    if (typeof instance.componentWillUpdate === 'function') {
      instance.componentWillUpdate(newProps, newState, nextContext);
    }
    if (typeof instance.UNSAFE_componentWillUpdate === 'function') {
      instance.UNSAFE_componentWillUpdate(newProps, newState, nextContext);
    }
  }
  if (typeof instance.componentDidUpdate === 'function') {
    workInProgress.flags |= Update;
  }
  if (typeof instance.getSnapshotBeforeUpdate === 'function') {
    workInProgress.flags |= Snapshot;
  }
} else {
  // If an update was already in progress, we should schedule an Update
  // effect even though we're bailing out, so that cWU/cDU are called.
  if (typeof instance.componentDidUpdate === 'function') {
    if (
      unresolvedOldProps !== current.memoizedProps ||
      oldState !== current.memoizedState
    ) {
      workInProgress.flags |= Update;
    }
  }
  if (typeof instance.getSnapshotBeforeUpdate === 'function') {
    if (
      unresolvedOldProps !== current.memoizedProps ||
      oldState !== current.memoizedState
    ) {
      workInProgress.flags |= Snapshot;
    }
  }
  
  // If shouldComponentUpdate returned false, we should still update the
  // memoized props/state to indicate that this work can be reused.
  workInProgress.memoizedProps = newProps;
  workInProgress.memoizedState = newState;
}

The final, well, almost final stage is the execution of the remaining lifecycle methods. In the event that the component needs to be re-rendered, the following methods will be executed:

componentWillUpdate (only if the new API is not used)
UNSAFE_componentWillUpdate (only if the new API is not used)
componentDidUpdate
getSnapshotBeforeUpdate

Otherwise, these methods will not be called, only the necessary utility flags will be set, and the properties and state will be stored in memoizedProps and memoizedState, respectively.

// Update the existing instance's state, props, and context pointers even
// if shouldComponentUpdate returns false.
instance.props = newProps;
instance.state = newState;
instance.context = nextContext;

return shouldUpdate;

And finally, the last stage. The new properties, state, and context values are assigned to the class instance, after which the function completes.

Shallow Comparison

The concept of shallow comparison has already been mentioned above. Let's delve into it in more detail. We talked about how this comparison occurs when implementing a PureComponent. Just to recap, let's remember what a PureComponent is. Let's use the example mentioned earlier and make slight modifications to it.

class MyComponent extends React.PureComponent<{ color?: string }> {
  static defaultProps = {
    color: 'blue',
  };
  
  render() {
    return (
      <div>
        {this.props.color}
      </div>
    );
  }
}

As you can see, the only difference is in which parent class we inherit our class component from (in the original version, we inherited from React.Component). It is in such a component that shallow comparison will be applied.

So, what exactly is shallow comparison? Perhaps the best answer to this question would be the code of the shallowEqual function itself, which we have seen before.

/packages/shared/shallowEqual.js#L13

/**
 * Performs equality by iterating through keys on an object and returning false
 * when any key has values which are not strictly equal between the arguments.
 * Returns true when the values of all keys are strictly equal.
 */
function shallowEqual(objA: mixed, objB: mixed): boolean {
  if (is(objA, objB)) {
    return true;
  }
  
  if (
    typeof objA !== 'object' ||
    objA === null ||
    typeof objB !== 'object' ||
    objB === null
  ) {
    return false;
  }
  
  const keysA = Object.keys(objA);
  const keysB = Object.keys(objB);
  
  if (keysA.length !== keysB.length) {
    return false;
  }
  
  // Test for A's keys different from B.
  for (let i = 0; i < keysA.length; i++) {
    const currentKey = keysA[i];
    if (
      !hasOwnProperty.call(objB, currentKey) ||
      !is(objA[currentKey], objB[currentKey])
    ) {
      return false;
    }
  }
  
  return true;
}

This utility function consists of two main parts:

Comparing variables objA and objB.
If the variables are equal or have equal references to the objects they represent, a comparison is made for each property of these objects.

The actual comparison is performed by another utility called is().

/packages/shared/objectIs.js#L10

/**
 * inlined Object.is polyfill to avoid requiring consumers ship their own
 * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is
 */
function is(x: any, y: any) {
  return (
    (x === y && (x !== 0 || 1 / x === 1 / y)) || (x !== x && y !== y) // eslint-disable-line no-self-compare
  );
}

const objectIs: (x: any, y: any) => boolean =
  typeof Object.is === 'function' ? Object.is : is;

This utility is nothing but a function from the Web API - Object.is(). If the browser does not support this Web API method, a built-in polyfill is used.

In sort, two values are the same if one of the following holds:

both undefined
both null
both true or both false
both strings of the same length with the same characters in the same order
both the same object (meaning both values reference the same object in memory)
both BigInts with the same numeric value
both symbols that reference the same symbol value
both numbers and

both +0
both -0
both NaN
or both non-zero, not NaN, and have the same value

FunctionComponent

Let's switch to functional components now that we've covered class components.

const Component = workInProgress.type;
const unresolvedProps = workInProgress.pendingProps;
const resolvedProps =
  workInProgress.elementType === Component
    ? unresolvedProps
    : resolveDefaultProps(Component, unresolvedProps);
return updateFunctionComponent(
  current,
  workInProgress,
  Component,
  resolvedProps,
  renderLanes,
);

At the very beginning of the begin phase of updating a functional component, there is no difference compared to updating a class component, except for the update function itself.

/packages/react-reconciler/src/ReactFiberBeginWork.new.js#L965

function updateFunctionComponent(
  current,
  workInProgress,
  Component,
  nextProps: any,
  renderLanes,
) {
  ...
  
  nextChildren = renderWithHooks(
    current,
    workInProgress,
    Component,
    nextProps,
    context,
    renderLanes,
  );
  hasId = checkDidRenderIdHook();

  ...
    
  if (current !== null && !didReceiveUpdate) {
    bailoutHooks(current, workInProgress, renderLanes);
    return bailoutOnAlreadyFinishedWork(current, workInProgress, renderLanes);
  }
  
  if (getIsHydrating() && hasId) {
    pushMaterializedTreeId(workInProgress);
  }
  
  ...
  
  reconcileChildren(current, workInProgress, nextChildren, renderLanes);
  return workInProgress.child;
}

Specifically, what matters here is the launch of a separate flow called renderWithHooks, which is characteristic of functional components. Let's take a look at what's going on there.

/packages/react-reconciler/src/ReactFiberHooks.new.js#L374

export function renderWithHooks<Props, SecondArg>(
  current: Fiber | null,
  workInProgress: Fiber,
  Component: (p: Props, arg: SecondArg) => any,
  props: Props,
  secondArg: SecondArg,
  nextRenderLanes: Lanes,
): any {
  renderLanes = nextRenderLanes;
  currentlyRenderingFiber = workInProgress;
  
  ...
  
  workInProgress.memoizedState = null;
  workInProgress.updateQueue = null;
  workInProgress.lanes = NoLanes;
  
  // The following should have already been reset
  // currentHook = null;
  // workInProgressHook = null;
  
  // didScheduleRenderPhaseUpdate = false;
  // localIdCounter = 0;
  
  // TODO Warn if no hooks are used at all during mount, then some are used during update.
  // Currently we will identify the update render as a mount because memoizedState === null.
  // This is tricky because it's valid for certain types of components (e.g. React.lazy)
  
  // Using memoizedState to differentiate between mount/update only works if at least one stateful hook is used.
  // Non-stateful hooks (e.g. context) don't get added to memoizedState,
  // so memoizedState would be null during updates and mounts.
  ReactCurrentDispatcher.current =
    current === null || current.memoizedState === null
      ? HooksDispatcherOnMount
      : HooksDispatcherOnUpdate;
      
  let children = Component(props, secondArg);
  
  // Check if there was a render phase update
  if (didScheduleRenderPhaseUpdateDuringThisPass) {
    // Keep rendering in a loop for as long as render phase updates continue to
    // be scheduled. Use a counter to prevent infinite loops.
    let numberOfReRenders: number = 0;
    do {
      didScheduleRenderPhaseUpdateDuringThisPass = false;
      localIdCounter = 0;
      
      if (numberOfReRenders >= RE_RENDER_LIMIT) {
        throw new Error(
          'Too many re-renders. React limits the number of renders to prevent ' +
            'an infinite loop.',
        );
      }
      
      numberOfReRenders += 1;
      
      // Start over from the beginning of the list
      currentHook = null;
      workInProgressHook = null;
      
      workInProgress.updateQueue = null;
      
      ReactCurrentDispatcher.current = __DEV__
        ? HooksDispatcherOnRerenderInDEV
        : HooksDispatcherOnRerender;
        
      children = Component(props, secondArg);
    } while (didScheduleRenderPhaseUpdateDuringThisPass);
  }
  
  // We can assume the previous dispatcher is always this one, since we set it
  // at the beginning of the render phase and there's no re-entrance.
  ReactCurrentDispatcher.current = ContextOnlyDispatcher;
  
  // This check uses currentHook so that it works the same in DEV and prod bundles.
  // hookTypesDev could catch more cases (e.g. context) but only in DEV bundles.
  const didRenderTooFewHooks =
    currentHook !== null && currentHook.next !== null;
    
  renderLanes = NoLanes;
  currentlyRenderingFiber = (null: any);
  
  currentHook = null;
  workInProgressHook = null;
  
  didScheduleRenderPhaseUpdate = false;
  // This is reset by checkDidRenderIdHook
  // localIdCounter = 0;
  
  if (didRenderTooFewHooks) {
    throw new Error(
      'Rendered fewer hooks than expected. This may be caused by an accidental ' +
        'early return statement.',
    );
  }
  
  if (enableLazyContextPropagation) {
    if (current !== null) {
      if (!checkIfWorkInProgressReceivedUpdate()) {
        // If there were no changes to props or state, we need to check if there
        // was a context change. We didn't already do this because there's no
        // 1:1 correspondence between dependencies and hooks. Although, because
        // there almost always is in the common case (`readContext` is an
        // internal API), we could compare in there. OTOH, we only hit this case
        // if everything else bails out, so on the whole it might be better to
        // keep the comparison out of the common path.
        const currentDependencies = current.dependencies;
        if (
          currentDependencies !== null &&
          checkIfContextChanged(currentDependencies)
        ) {
          markWorkInProgressReceivedUpdate();
        }
      }
    }
  }
  return children;
}

The function may seem big and complex, but essentially, it does only two things. First, it defines the hook dispatcher, which will be responsible for the further execution of these hooks. Formally, in React, there are only 4 such dispatchers:

ContextOnlyDispatcher
HooksDispatcherOnMount
HooksDispatcherOnUpdate
HooksDispatcherOnRender

In reality, the ContextOnlyDispatcher does not implement anything; it serves as a kind of default dispatcher and remains in place until the engine identifies a more relevant dispatcher for the current component.

Among the remaining three dispatchers, HooksDispatcherOnUpdate and HooksDispatcherOnRender practically do not differ, both leading to the same implementations of update hooks (updateMemo, updateCallback, etc.). The separation of these two different dispatchers is purely logical, in case React developers ever need to create different versions of hooks for different phases. As for HooksDispatcherOnMount, it leads to separate implementations of mount hooks (mountMemo, mountCallback, etc.).

We will discuss hooks and their providers a little later. For now, let's just note that each hook has two versions: mount and update. At this stage, it is important to determine which version of the hooks the engine will execute. This is done as follows.

ReactCurrentDispatcher.current =
    current === null || current.memoizedState === null
      ? HooksDispatcherOnMount
      : HooksDispatcherOnUpdate;

Where current is a reference to Fiber.alternate. If it is equal to null, it means the component has not been created yet. Similarly, if Fiber.alternate.memoizedState is empty, then the hooks have not been executed in this component yet. In both cases, the HooksDispatcherOnMount dispatcher will be applied. Otherwise, it will be HooksDispatcherOnUpdate.

The second thing the function does is create a component using let children = Component(props, secondArg) and repeats this process in a loop until all scheduled updates are completed in the current phase. And yes, this is where the Too many re-renders. React limits the number of renders to prevent an infinite loop. exception is thrown if the number of updates exceeds 25 iterations.

HooksDispatcherOnMount

The dispatcher code looks like this

/packages/react-reconciler/src/ReactFiberHooks.new.js#L2427

const HooksDispatcherOnMount: Dispatcher = {
  readContext,
  
  useCallback: mountCallback,
  useContext: readContext,
  useEffect: mountEffect,
  useImperativeHandle: mountImperativeHandle,
  useLayoutEffect: mountLayoutEffect,
  useInsertionEffect: mountInsertionEffect,
  useMemo: mountMemo,
  useReducer: mountReducer,
  useRef: mountRef,
  useState: mountState,
  useDebugValue: mountDebugValue,
  useDeferredValue: mountDeferredValue,
  useTransition: mountTransition,
  useMutableSource: mountMutableSource,
  useSyncExternalStore: mountSyncExternalStore,
  useId: mountId,
  
  unstable_isNewReconciler: enableNewReconciler,
};
if (enableCache) {
  (HooksDispatcherOnMount: Dispatcher).getCacheSignal = getCacheSignal;
  (HooksDispatcherOnMount: Dispatcher).getCacheForType = getCacheForType;
  (HooksDispatcherOnMount: Dispatcher).useCacheRefresh = mountRefresh;
}

We will not consider all mount functions of hooks, it is more important to understand the essence of these functions. Let's see this on the example of mountMemo.

/packages/react-reconciler/src/ReactFiberHooks.new.js#L1899

function mountMemo<T>(
  nextCreate: () => T,
  deps: Array<mixed> | void | null,
): T {
  const hook = mountWorkInProgressHook();
  const nextDeps = deps === undefined ? null : deps;
  const nextValue = nextCreate();
  hook.memoizedState = [nextValue, nextDeps];
  return nextValue;
}

As you can see, the hook code is embarrassingly simple. First, a reference to Fiber is defined. Then, the value is computed, which occurs in the custom callback nextCreate. Next, the computed value and the array of dependencies are saved in Fiber.memoizedState. Here it is, memoization!

HooksDispatcherOnUpdate

Now let's peek into the HooksDispatcherOnUpdate dispatcher.

/packages/react-reconciler/src/ReactFiberHooks.new.js#L2454

const HooksDispatcherOnUpdate: Dispatcher = {
  readContext,
  
  useCallback: updateCallback,
  useContext: readContext,
  useEffect: updateEffect,
  useImperativeHandle: updateImperativeHandle,
  useInsertionEffect: updateInsertionEffect,
  useLayoutEffect: updateLayoutEffect,
  useMemo: updateMemo,
  useReducer: updateReducer,
  useRef: updateRef,
  useState: updateState,
  useDebugValue: updateDebugValue,
  useDeferredValue: updateDeferredValue,
  useTransition: updateTransition,
  useMutableSource: updateMutableSource,
  useSyncExternalStore: updateSyncExternalStore,
  useId: updateId,
  
  unstable_isNewReconciler: enableNewReconciler,
};
if (enableCache) {
  (HooksDispatcherOnUpdate: Dispatcher).getCacheSignal = getCacheSignal;
  (HooksDispatcherOnUpdate: Dispatcher).getCacheForType = getCacheForType;
  (HooksDispatcherOnUpdate: Dispatcher).useCacheRefresh = updateRefresh;
}

As I mentioned earlier, this dispatcher differs from the previous one in that it leads to the update versions of the same hooks. Since in the previous example we looked at mountMemo, this time let's look at updateMemo.

/packages/react-reconciler/src/ReactFiberHooks.new.js#L1910

function updateMemo<T>(
  nextCreate: () => T,
  deps: Array<mixed> | void | null,
): T {
  const hook = updateWorkInProgressHook();
  const nextDeps = deps === undefined ? null : deps;
  const prevState = hook.memoizedState;
  if (prevState !== null) {
    // Assume these are defined. If they're not, areHookInputsEqual will warn.
    if (nextDeps !== null) {
      const prevDeps: Array<mixed> | null = prevState[1];
      if (areHookInputsEqual(nextDeps, prevDeps)) {
        return prevState[0];
      }
    }
  }
  const nextValue = nextCreate();
  hook.memoizedState = [nextValue, nextDeps];
  return nextValue;
}

Here we already have the memory effect that was initiated during the mounting phase. Now, before starting the computations, the hook will take the previous dependencies from Fiber.memoizedState[1] and compare them with the current ones using the function areHookInputsEqual(nextDeps, prevDeps).

/packages/react-reconciler/src/ReactFiberHooks.new.js#L327

function areHookInputsEqual(
  nextDeps: Array<mixed>,
  prevDeps: Array<mixed> | null,
) {
  ...
  
  if (prevDeps === null) {
    if (__DEV__) {
      console.error(
        '%s received a final argument during this render, but not during ' +
          'the previous render. Even though the final argument is optional, ' +
          'its type cannot change between renders.',
        currentHookNameInDev,
      );
    }
    return false;
  }
  
  ...
  
  for (let i = 0; i < prevDeps.length && i < nextDeps.length; i++) {
    if (is(nextDeps[i], prevDeps[i])) {
      continue;
    }
    return false;
  }
  return true;
}

Which, in turn, performs a shallow comparison of dependencies using the same Object.is function.

MemoComponent

It's time to talk about the third type of node that interests us - MemoComponent. Such a node can be created using React.memo.

const MyComponent = React.memo<{ color?: string }>(({ color }) => {
  return <div>{color}</div>;
});

This type of component will only rerender if the properties passed to it have changed. It looks like this:

const type = workInProgress.type;
const unresolvedProps = workInProgress.pendingProps;
// Resolve outer props first, then resolve inner props.
let resolvedProps = resolveDefaultProps(type, unresolvedProps);

resolvedProps = resolveDefaultProps(type.type, resolvedProps);
return updateMemoComponent(
  current,
  workInProgress,
  type,
  resolvedProps,
  renderLanes,
);

The update function for these components is called updateMemoComponent. The function is quite long, I will only provide the part of it that we need within the scope of this article.

/packages/react-reconciler/src/ReactFiberBeginWork.new.js#L452

function updateMemoComponent(
  current: Fiber | null,
  workInProgress: Fiber,
  Component: any,
  nextProps: any,
  renderLanes: Lanes,
): null | Fiber {
  ...
  
  const currentChild = ((current.child: any): Fiber); // This is always exactly one child
  const hasScheduledUpdateOrContext = checkScheduledUpdateOrContext(
    current,
    renderLanes,
  );
  if (!hasScheduledUpdateOrContext) {
    // This will be the props with resolved defaultProps,
    // unlike current.memoizedProps which will be the unresolved ones.
    const prevProps = currentChild.memoizedProps;
    // Default to shallow comparison
    let compare = Component.compare;
    compare = compare !== null ? compare : shallowEqual;
    if (compare(prevProps, nextProps) && current.ref === workInProgress.ref) {
      return bailoutOnAlreadyFinishedWork(current, workInProgress, renderLanes);
    }
  }
  // React DevTools reads this flag.
  workInProgress.flags |= PerformedWork;
  const newChild = createWorkInProgress(currentChild, nextProps);
  newChild.ref = workInProgress.ref;
  newChild.return = workInProgress;
  workInProgress.child = newChild;
  return newChild;
}

The essence of this code boils down to calling the comparison function compare(prevProps, nextProps), where compare can be either a custom function (the second argument of React.memo) or the default shallowEqual, which we have already seen earlier.

Conclusion

In this article, we took a peek under the hood of the React engine and examined the mechanisms of mounting and updating nodes. One of the most important mechanisms in React involved in these processes is memoization. We discussed it using examples of three types of Fibers: ClassComponent, FunctionComponent, and MemoComponent.

Now that we have a better understanding of these processes, it's time to draw some conclusions.

Whether it's a class, function, or a hook's dependencies, React uses the same approach as a comparison function - the Object.is() Web API method or its polyfill.
Each hook has two implementation versions, mount and update. The update version is usually more complex because it needs to compare dependencies. Developers cannot influence the specific version of the hook used by the engine. The mount version only runs during the first component mount.

Since React compares each dependency separately when processing a hook, it is not advisable to add unnecessary dependencies. Additionally, dependencies are stored in memory, so having a large number of them can impact resource consumption. In other words,

const value = useMemo(() => {
  return a + b
}, [a, b]);

this code will be slightly more performant than the following

const value = useMemo(() => {
  return a + b
}, [a, b, c]);

Similarly,

const SOME_CONST = "some value";

const MyComponent = ({ a, b }) => {
  // this hook is more performant
  const value1 = useMemo(() => {
    return a + SOME_CONST
  }, [a]);

  // than this one
  const value2 = useMemo(() => {
    return b + SOME_CONST
  }, [b, SOME_CONST]);  

  return null;
}

For the same reason, it is essential to adequately assess the need for memoization in general. For example,

const isEqual = useMemo(() => {
  return a === b
}, [a, b]);

It won't provide any performance boost. On the contrary, the engine will have to compare prevDeps.a === currDeps.a and prevDeps.b === currDeps.b each time. Moreover, an additional function will be introduced in the code, which will consume its own resources.

The previous point applies to React.memo as well. Developers should understand whether the effect of memoization will outweigh the overhead of maintaining it.

My telegram channels:

EN - https://t.me/frontend_almanac
RU - https://t.me/frontend_almanac_ru

Русская версия: https://blog.frontend-almanac.ru/react-memoization

JavaScript Optimisation. Inline Caches

2024-04-23T17:50:26.635Z

I think it is not a secret for anyone that all popular JavaScript engines have a similar code execution pipeline. It looks something like this. The interpreter quickly compiles JavaScript code into bytecode "on the fly". The resulting bytecode starts executing and is processed in parallel by the optimizer. The optimizer needs time for this processing, but in the end, highly optimized code can be obtained, which will work much faster. In the V8 engine, Ignition acts as the interpreter, and Turbofan acts as the optimizer. In the Chakra engine, which is used in Edge, instead of one optimizer, there are two - SimpleJIT and FullJIT. In JSC (Safari), there are three Baseline, DFG, and FTL optimizers. The specific implementation may vary in different engines, but the basic scheme is generally the same.

Today, we will talk about one of the many optimization mechanisms called Inline Caches.

So, let's take a very ordinary function and try to understand how it will work at runtime.

function getX(obj) {
  return obj.x;
}

Our function is rather primitive. It is a simple getter that takes an object as an argument and returns the value of the x property of that object. From the perspective of a JavaScript developer, the function looks absolutely atomic. However, let's dive under the hood of the engine and see what it represents in its compiled form.

For experiments, as usual, we will use the most popular JS engine V8 (as of the time of writing this article, version 12.6.72). For full debugging, in addition to the body of the function itself, we need to call it with a real argument. Also, let's add output of information about the object, which will be needed a bit later.

function getX(obj) {
  %DebugPrint(obj);
  return obj.x;
}

getX({ x: 1 });

I would like to remind that %DebugPrint is a built-in function in V8. In order to use it in the code, you need to run the d8 runtime with the --allow-natives-syntax flag. Additionally, let's print the bytecode of the executable script to the console (using the --print-bytecode flag).

%> d8 --print-bytecode --allow-natives-syntax index.js 
...
// байткод функции getX
[generated bytecode for function: getX (0x0b75000d9c29 <SharedFunctionInfo getX>)]
Bytecode length: 10
Parameter count 2
Register count 0
Frame size 0
         0x28c500002194 @    0 : 65 af 01 03 01    CallRuntime [DebugPrint], a0-a0
         0x28c500002199 @    5 : 2d 03 00 00       GetNamedProperty a0, [0], [0]
         0x28c50000219d @    9 : ab                Return
Constant pool (size = 1)
0xb75000d9dcd: [FixedArray] in OldSpace
 - map: 0x0b7500000565 <Map(FIXED_ARRAY_TYPE)>
 - length: 1
           0: 0x0b7500002b91 <String[1]: #x>
Handler Table (size = 0)
Source Position Table (size = 0)
// Далее информация о переданном объекте
DebugPrint: 0xb75001c9475: [JS_OBJECT_TYPE]
 - map: 0x0b75000d9d81 <Map[16](HOLEY_ELEMENTS)> [FastProperties]
 - prototype: 0x0b75000c4b11 <Object map = 0xb75000c414d>
 - elements: 0x0b75000006cd <FixedArray[0]> [HOLEY_ELEMENTS]
 - properties: 0x0b75000006cd <FixedArray[0]>
 - All own properties (excluding elements): {
    0xb7500002b91: [String] in ReadOnlySpace: #x: 1 (const data field 0), location: in-object
 }
0xb75000d9d81: [Map] in OldSpace
 - map: 0x0b75000c3c29 <MetaMap (0x0b75000c3c79 <NativeContext[285]>)>
 - type: JS_OBJECT_TYPE
 - instance size: 16
 - inobject properties: 1
 - unused property fields: 0
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - stable_map
 - back pointer: 0x0b75000d9d59 <Map[16](HOLEY_ELEMENTS)>
 - prototype_validity cell: 0x0b7500000a31 <Cell value= 1>
 - instance descriptors (own) #1: 0x0b75001c9485 <DescriptorArray[1]>
 - prototype: 0x0b75000c4b11 <Object map = 0xb75000c414d>
 - constructor: 0x0b75000c4655 <JSFunction Object (sfi = 0xb7500335385)>
 - dependent code: 0x0b75000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

So, essentially, the compiled bytecode of the getX function looks as follows.

0x28c500002194 @    0 : 65 af 01 03 01    CallRuntime [DebugPrint], a0-a0
0x28c500002199 @    5 : 2d 03 00 00       GetNamedProperty a0, [0], [0]
0x28c50000219d @    9 : ab                Return

The first line is a call to the %DebugPrint function. It is purely auxiliary and does not affect the executable code; we can safely omit it. The next instruction is GetNamedProperty. Its purpose is to retrieve the value of the specified property from the passed object. The instruction takes three parameters as input. The first one is a reference to the object. In our case, the reference to the object is stored in a0, the first argument of the getX function. The second and third parameters are the address of the hidden class and the offset of the property in the descriptor array.

Object's Shape

In the article Object Structure in JavaScript Engines, I explained in detail what hidden classes, descriptor arrays, and how objects in JavaScript are structured. I won’t retell the whole article but will highlight only the essential facts. Every object has one or several hidden classes. Hidden classes are an internal engine mechanism inaccessible to JavaScript developers, at least without using special built-in engine methods. A hidden class represents the so-called shape of an object and all the necessary information about the object's properties. The object itself only stores property values and a reference to the hidden class. If two objects have the same shape, they will have a reference to the same hidden class.

const obj1 = { x: 1 }
const obj2 = { x: 2 }

//          {}     <- empty map
//          |
//        { x }    <- common map
//       /    \
// <obj1>      <obj2>

As properties are added to the object, its hidden class tree grows.

const obj1 = {}
obj1.x = 1;
obj1.y = 2;
obj1.z = 3;

// {} -> { x } -> { x, y } -> { x, y, z } -> <obj1>

Let's go back to the function we started with. Let's assume we passed it an object of the following type.

function getX(obj) {
  return obj.x;
}

getX({ y: 1, x: 2, z: 3 });

In order to access the value of property x, the interpreter needs to know: a) the address of the object's last hidden class; b) the offset of this property in the descriptors array.

d8> const obj = { y: 1, x: 2, z: 3};
d8>
d8> %DebugPrint(obj);
DebugPrint: 0x2034001c9435: [JS_OBJECT_TYPE]
 - map: 0x2034000d9cf9 <Map[24](HOLEY_ELEMENTS)> [FastProperties]
 - prototype: 0x2034000c4b11 <Object map = 0x2034000c414d>
 - elements: 0x2034000006cd <FixedArray[0]> [HOLEY_ELEMENTS]
 - properties: 0x2034000006cd <FixedArray[0]>
 - All own properties (excluding elements): {
    0x203400002ba1: [String] in ReadOnlySpace: #y: 1 (const data field 0), location: in-object
    0x203400002b91: [String] in ReadOnlySpace: #x: 2 (const data field 1), location: in-object
    0x203400002bb1: [String] in ReadOnlySpace: #z: 3 (const data field 2), location: in-object
 }
0x2034000d9cf9: [Map] in OldSpace
 - map: 0x2034000c3c29 <MetaMap (0x2034000c3c79 <NativeContext[285]>)>
 - type: JS_OBJECT_TYPE
 - instance size: 24
 - inobject properties: 3
 - unused property fields: 0
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - stable_map
 - back pointer: 0x2034000d9cd1 <Map[24](HOLEY_ELEMENTS)>
 - prototype_validity cell: 0x203400000a31 <Cell value= 1>
 - instance descriptors (own) #3: 0x2034001c9491 <DescriptorArray[3]>
 - prototype: 0x2034000c4b11 <Object map = 0x2034000c414d>
 - constructor: 0x2034000c4655 <JSFunction Object (sfi = 0x203400335385)>
 - dependent code: 0x2034000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

In the example above, the hidden class is located at the address 0x2034000d9cd1 (back pointer).

d8> %DebugPrintPtr(0x2034000d9cd1)
DebugPrint: 0x2034000d9cd1: [Map] in OldSpace
 - map: 0x2034000c3c29 <MetaMap (0x2034000c3c79 <NativeContext[285]>)>
 - type: JS_OBJECT_TYPE
 - instance size: 24
 - inobject properties: 3
 - unused property fields: 1
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - back pointer: 0x2034000d9c89 <Map[24](HOLEY_ELEMENTS)>
 - prototype_validity cell: 0x203400000a31 <Cell value= 1>
 - instance descriptors #2: 0x2034001c9491 <DescriptorArray[3]>
 - transitions #1: 0x2034000d9cf9 <Map[24](HOLEY_ELEMENTS)>
     0x203400002bb1: [String] in ReadOnlySpace: #z: (transition to (const data field, attrs: [WEC]) @ Any) -> 0x2034000d9cf9 <Map[24](HOLEY_ELEMENTS)>
 - prototype: 0x2034000c4b11 <Object map = 0x2034000c414d>
 - constructor: 0x2034000c4655 <JSFunction Object (sfi = 0x203400335385)>
 - dependent code: 0x2034000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0
0x2034000c3c29: [MetaMap] in OldSpace
 - map: 0x2034000c3c29 <MetaMap (0x2034000c3c79 <NativeContext[285]>)>
 - type: MAP_TYPE
 - instance size: 40
 - native_context: 0x2034000c3c79 <NativeContext[285]>

From there, we can access the descriptors array at the address 0x2034001c9491 (instance descriptors).

d8> %DebugPrintPtr(0x2034001c9491)
DebugPrint: 0x2034001c9491: [DescriptorArray]
 - map: 0x20340000062d <Map(DESCRIPTOR_ARRAY_TYPE)>
 - enum_cache: 3
   - keys: 0x2034000daaa9 <FixedArray[3]>
   - indices: 0x2034000daabd <FixedArray[3]>
 - nof slack descriptors: 0
 - nof descriptors: 3
 - raw gc state: mc epoch 0, marked 0, delta 0
  [0]: 0x203400002ba1: [String] in ReadOnlySpace: #y (const data field 0:s, p: 2, attrs: [WEC]) @ Any
  [1]: 0x203400002b91: [String] in ReadOnlySpace: #x (const data field 1:s, p: 1, attrs: [WEC]) @ Any
  [2]: 0x203400002bb1: [String] in ReadOnlySpace: #z (const data field 2:s, p: 0, attrs: [WEC]) @ Any
0x20340000062d: [Map] in ReadOnlySpace
 - map: 0x2034000004c5 <MetaMap (0x20340000007d <null>)>
 - type: DESCRIPTOR_ARRAY_TYPE
 - instance size: variable
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - stable_map
 - non-extensible
 - back pointer: 0x203400000061 <undefined>
 - prototype_validity cell: 0
 - instance descriptors (own) #0: 0x203400000701 <DescriptorArray[0]>
 - prototype: 0x20340000007d <null>
 - constructor: 0x20340000007d <null>
 - dependent code: 0x2034000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

The interpreter can then locate the desired property by its name and retrieve the offset, which in this case is 1.

Thus, the interpreter's path will look something like this.

Our case is quite straightforward. Here, the values of the properties are stored inside the object itself, which makes access to them pretty fast. However, the determination of the property's position in the array of descriptors will still be proportional to the number of properties themselves. Furthermore, in the article Object Structure in JavaScript Engines, I mentioned that values are not always stored in such a "fast" manner. In some cases, the storage type may be changed to a slower "dictionary."

Inline Cache

Of course, in isolated cases for a JS engine, this does not pose significant difficulties, and the time it takes to access property values is hardly noticeable to the naked eye. But what if our case is not isolated? Let's say we need to execute a function hundreds or thousands of times in a loop? The total time of operation becomes critically important here. Given that the function actually performs the same operations, JavaScript authors have proposed optimizing the property search process to avoid executing it every time. All that is required for this is to store the object's hidden class address and the "offset" of the desired property.

Let's go back to the beginning of the article and the GetNamedProperty instruction, which has three parameters. We have already determined that the first parameter is a reference to the object. The second parameter is the hidden class address. The third parameter is the found "offset" of the property. Once these parameters are defined, the function can memorize them and not perform the search procedure again during the next execution. This caching is called Inline Cache (IC).

TurboFan

However, it is worth considering that parameter memoization also requires memory and some CPU time. This makes the mechanism efficient only during intensive function execution (so-called hot function). The intensity of function execution depends on the quantity and frequency of its calls. The optimizer is responsible for assessing this intensity. In the case of V8, TurboFan acts as the optimizer. First of all, the optimizer constructs a graph from the AST and bytecode and sends it to the "inlining" phase, where metrics for calls, loads, and cache storage are gathered. Next, if a function is suitable for inline caching, it is queued for optimization. Once the queue is full, the optimizer must identify the hottest function and perform caching on it. Then move on to the next one and so on. By the way, unlike its predecessor Crankshaft, which took functions one by one starting from the first. In general, this topic is quite extensive and deserves a separate article; there is no point in discussing all the details and peculiarities of TurboFan's heuristics now. It's better to move on to examples.

IC Types

To analyze the IC operation, you need to enable logging in the runtime environment. For d8, you can do this by specifying the --log-ic flag.

%> d8 --log-ic

function getX(obj) {
  return obj.x;
}

for (let i = 0; i < 10; i++) {
  getX({ x: i });
}

As I have mentioned before, TurboFan starts to cache object properties only in "hot" functions. To make our function "hot," we need to run it multiple times in a loop. In my simple script in the d8 environment, it required a minimum of 10 iterations. In practice, in different conditions and with other functions present, this number may vary and is likely to be higher. The resulting log can now be analyzed using the System Analyzer.

Grouped by type: 1#
>100.00%	1	LoadIC
Grouped by category: 1#
>100.00%	1	Load
Grouped by functionName: 1#
>100.00%	1	~getX
Grouped by script: 1#
>100.00%	1	Script(3): index.js
Grouped by sourcePosition: 1#
>100.00%	1	index.js:3:14
Grouped by code: 1#
>100.00%	1	Code(JS~)
Grouped by state: 1#
>100.00%	1	0 → 1
Grouped by key: 1#
>100.00%	1	x
Grouped by map: 1#
>100.00%	1	Map(0x3cd2000d9e61)
Grouped by reason: 1#
>100.00%	1

In the IC List, we see the notation of the type LoadIC, which indicates accessing an object property from the cache. Here we have the function itself functionName: ~getX, the address of the hidden class Map(0x3cd2000d9e61), and the property name key: x. However, the most interesting part is state: 0 -> 1.

There are several types of IC. The complete list looks as follows:

/src/common/globals.h#1481

// State for inline cache call sites. Aliased as IC::State.
enum class InlineCacheState {
  // No feedback will be collected.
  NO_FEEDBACK,
  // Has never been executed.
  UNINITIALIZED,
  // Has been executed and only one receiver type has been seen.
  MONOMORPHIC,
  // Check failed due to prototype (or map deprecation).
  RECOMPUTE_HANDLER,
  // Multiple receiver types have been seen.
  POLYMORPHIC,
  // Many DOM receiver types have been seen for the same accessor.
  MEGADOM,
  // Many receiver types have been seen.
  MEGAMORPHIC,
  // A generic handler is installed and no extra typefeedback is recorded.
  GENERIC,
};

In the system analyzer, these types are denoted by symbols

0: UNINITIALIZED
X: NO_FEEDBACK
1: MONOMORPHIC
^: RECOMPUTE_HANDLER
P: POLYMORPHIC
N: MEGAMORPHIC
D: MEGADOM
G: GENERIC

For example, the type X (NO_FEEDBACK) indicates that the optimizer has not yet gathered sufficient statistics to optimize the function. In our case, seeing state: 0 -> 1 means that the function has transitioned to the state of "monomorphic IC".

Monomorphic

As mentioned before, in practice, the same function can take an object as an argument. The shape of this object in a specific function call may differ from the previous one, which complicates the optimizer's task. The least trouble arises when we pass only objects of the same shape to the function, as in our last example.

function getX(obj) {
  return obj.x; // Monomorphic IC
}

for (let i = 0; i < 10; i++) {
  getX({ x: i }); // all objects have the same shape
}

In such cases, the optimizer simply needs to remember the address of the hidden class and the offset property. This type of IC is called monomorphic.

Polymorphic

Now, let's try to add a function call with object of a different shape.

function getX(obj) {
  return obj.x; // Polymorphic IC
}

for (let i = 0; i < 10; i++) {
  getX({ x: i, y: 0 });
  getX({ y: 0, x: i });
}

In the "IC List" now, we can see:

50.00%        1    0 → 1
50.00%        1    1 → P

A function in runtime can receive multiple different forms of an object. Access to property x will vary for each form. Each form has its own hidden class address and its own offset of this property. In this case, the optimizer allocates two slots for each form of the object, where it saves the necessary parameters.

Such structure can be conceptually represented as an array of parameter sets.

[
  [Map1, offset1],
  [Map2, offset2],
  ...
]

This type of IC is called polymorphic. Polymorphic IC has a limit on the number of permissible forms.

/src/wasm/wasm-constants.h#192

// Maximum number of call targets tracked per call.
constexpr int kMaxPolymorphism = 4;

By default, a polymorphic type can have from 2 to 4 forms per function. However, this parameter can be adjusted with the flag --max-valid-polymorphic-map-count.

Megamorphic

If the number of object forms exceeds what Polymorphic can handle, the type changes to megamorphic.

function getX(obj) {
  return obj.x; // Megamorphic IC
}

for (let i = 0; i < 10; i++) {
  getX({ x: i });
  getX({ prop1: 0, x: i });
  getX({ prop1: 0, prop2: 1, x: i });
  getX({ prop1: 0, prop2: 1, prop3: 2, x: i });
  getX({ prop1: 0, prop2: 1, prop3: 2, prop4: 3, x: i });
}

The result of the IC List:

40.00%        2    P → P
20.00%        1    0 → 1
20.00%        1    1 → P
20.00%        1    P → N

In this case, the search for the required set of parameters negates the saving of CPU time and, therefore, does not make sense. That is why the optimizer simply caches the MegamorphicSymbol symbol. For subsequent function calls, this will mean that the cached parameters are not available here and will have to be taken in the usual way. There is also no point in further optimizing the function and collecting its metrics.

Conclusion

You have probably noticed that there is an additional type called MEGADOM in the IC types list. This type is used for caching the DOM tree nodes. The thing is, the inline caching mechanism is not limited to functions and objects only. It is actively used in many other places, including outside V8. Covering all the information about caching at once is physically impossible. Since today we are talking about JavaScript objects, we will not discuss the MegaDom type in this article.

Let's conduct a couple of tests and see how effective Turbofan optimization works in V8. The experiment will be conducted in the Node.js environment (the latest stable version at the time of writing this article is v20.12.2).

Experimental code:

const N = 1000;

//===

function getXMonomorphic(obj) {
  let sum = 0;

  for (let i = 0; i < N; i++) {
    sum += obj.x;
  }

  return sum;
}

console.time('Monomorphic');

for (let i = 0; i < N; i++) {
  getXMonomorphic({ x: i });
  getXMonomorphic({ x: i });
  getXMonomorphic({ x: i });
  getXMonomorphic({ x: i });
  getXMonomorphic({ x: i });
}

console.timeLog('Monomorphic');

//===

function getXPolymorphic(obj) {
  let sum = 0;

  for (let i = 0; i < N; i++) {
    sum += obj.x;
  }

  return sum;
}

console.time('Polymorphic');

for (let i = 0; i < N; i++) {
  getXPolymorphic({ x: i, y: 0 });
  getXPolymorphic({ y: 0, x: i });
  getXPolymorphic({ x: i, y: 0 });
  getXPolymorphic({ y: 0, x: i });
  getXPolymorphic({ x: i, y: 0 });
}

console.timeEnd('Polymorphic');

//===

function getXMegamorphic(obj) {
  let sum = 0;

  for (let i = 0; i < N; i++) {
    sum += obj.x;
  }

  return sum;
}

//===

console.time('Megamorphic');

for (let i = 0; i < N; i++) {
  getXMegamorphic({ x: i });
  getXMegamorphic({ prop1: 0, x: i });
  getXMegamorphic({ prop1: 0, prop2: 1, x: i });
  getXMegamorphic({ prop1: 0, prop2: 1, prop3: 2, x: i });
  getXMegamorphic({ prop1: 0, prop2: 1, prop3: 2, prop4: 3, x: i });
}

console.timeLog('Megamorphic');

To begin with, let's run the script with optimization turned off and observe the "clean" performance of the functions.

%> node --no-opt test.js
Monomorphic: 68.55ms
Polymorphic: 69.939ms
Megamorphic: 85.045ms

For the sake of the experiment's integrity, I repeated the tests several times. The performance between monomorphic and polymorphic objects is approximately the same. Polymorphic objects can sometimes even be faster. This is not so much related to the workings of V8 itself as it is to system resources. However, the speed of megamorphic objects is slightly lower due to the formation of a hidden class tree at this stage, making access to the properties of these objects inherently more complex than in the first two cases.

Now let's run the same script with optimization enabled:

%> node test.js
Monomorphic: 9.313ms
Polymorphic: 9.673ms
Megamorphic: 29.104ms

The speed of monomorphic and polymorphic functions has increased by about 7 times. Similar to the previous case, the difference between these two types is insignificant, and in repeated tests, polymorphic functions are sometimes even faster. However, the speed of the megamorphic function has increased by only 3 times. Generally, based on the theory described above, megamorphic functions were not supposed to show an increase in speed through optimization. However, it is not that simple. Firstly, they do have a side effect from optimization since such functions are excluded from the process of further metric collection. This is a small but still an advantage over the other types. Secondly, the optimization of JS work is not limited to inline caching of object property access. There are several other types of optimizations that we did not consider in this article.

Moreover, in 2023, Google released the Chromium M117 version, which included the new optimizer Maglev. It was integrated as a middleware between Ignition (interpreter) and Turbofan (optimizer). Now the optimization process has acquired a three-tiers architecture and looks like Ignition -> Maglev -> Turbofan. Maglev contributes to function optimization, particularly working with function arguments. We will discuss this in more detail another time. For now, we can conclude that megamorphic functions are approximately twice as slow as monomorphic and polymorphic ones.

My telegram channels:

EN - https://t.me/frontend_almanac
RU - https://t.me/frontend_almanac_ru

Русская версия: https://blog.frontend-almanac.ru/js-optimisation-ic

Object Structure in JavaScript Engines

2024-03-31T20:02:57.218Z

From a developer's perspective, objects in JavaScript are quite flexible and understandable. We can add, remove, and modify object properties on our own. However, few people think about how objects are stored in memory and processed by JS engines. Can a developer's actions, directly or indirectly, impact performance and memory consumption? Let's try to delve into all of this in this article.

Object and its properties

Before delving into the internal structures of the object, let's quickly review the basics and recall what an object actually is. The ECMA-262 specification in section 6.1.7 The Object Type defines an object rather primitively, simply as a set of properties. Object properties are represented as a "key-value" structure, where the key is the property name, and the value is a set of attributes. All object properties can be conventionally divided into two types: data properties and accessor properties.

Data properties

Properties which have the following attributes:

[[Value]] - the value of the property
[[Writable]] - boolean, by default set to false - if false, the [[Value]] cannot be changed
[[Enumerable]] - boolean, by default set to false - if true, the property can be iterated through using "for-in"
[[Configurable]] - boolean, by default set to false - if false, the property cannot be deleted, its type cannot be changed from Data property to Accessor property (or vice versa), no attributes except for [[Value]] and setting [[Writable]] can be set to false

Accessor properties

Properties which have the following attributes:

[[Get]] - a function that returns the value of the object
[[Set]] - a function called when an attempt to assign a value to the property is made
[[Enumerable]] - identical to Data property
[[Configurable]] - identical to Data property.

Hidden Classes

According to the specification, in addition to the values themselves, each object property should store information about its attributes.

const obj1 = { a: 1, b: 2 };

The simple object mentioned above, in the context of a JavaScript engine, should look something like this.

{
  a: {
    [[Value]]: 1,
    [[Writable]]: true,
    [[Enumerable]]: true,
    [[Configurable]]: true,
  },
  b: {
    [[Value]]: 2,
    [[Writable]]: true,
    [[Enumerable]]: true,
    [[Configurable]]: true,
  }
}

Now, let's imagine that we have two objects with similar structures.

const obj1 = { a: 1, b: 2 };
const obj2 = { a: 3, b: 4 };

Based on the above, we need to store information about each of the four properties of these two objects. It sounds somewhat wasteful in terms of memory consumption. Furthermore, it is evident that the configuration of these properties is the same, except for the property name and its [[Value]].

The popular JS engines solve this problem using so-called hidden classes. This concept is often encountered in various publications and documentation. However, it intersects somewhat with the concept of JavaScript classes, so engine developers have adopted their own definitions. For example, in V8, hidden classes are referred to as Maps (which also intersects with the concept of JavaScript Maps). In the Chakra engine used in the Internet Explorer browser, the term Types is applied. Safari developers, in their JavaScriptCore engine, use the notion of Structures. In the SpiderMonkey engine for Mozilla, hidden classes are called Shapes. Actually, this term is quite popular and often appears in publications because it is unique and can hardly be confused with anything else in JavaScript.

In general, there are many interesting publications about hidden classes in the network. In particular, I recommend taking a look at Mathias Bynens' post, one of the developers of V8 and Chrome DevTools.

So, the essence of hidden classes lies in extracting meta-information and object properties into separate, reusable objects and binding such a class to the real object by reference.

In this concept, the example above can be represented as follows. Later, we will see how real Maps look in the V8 engine, but for now, I will illustrate it in a hypothetical way.

Map1 {
  a: {
    [[Writable]]: true,
    [[Enumerable]]: true,
    [[Configurable]]: true,
  },
  b: {
    [[Writable]]: true,
    [[Enumerable]]: true,
    [[Configurable]]: true,
  }
}

ob1 {
  map: Map1,
  values: { a: 1, a: 2 }
}

ob2 {
  map: Map1,
  values: { a: 3, a: 4 }
}

Hidden Classes Inheritance

The concept of hidden classes looks good in the case of objects with the same shape. However, what to do if the second object has a different structure? In the following example, the two objects are not structurally identical to each other, but have an intersection.

const obj1 = { a: 1, b: 2 };
const obj2 = { a: 3, b: 4, c: 5 };

According to the logic described above, two classes with different shapes should appear in memory. However, this leads back to the issue of attribute duplication. To avoid this, it is accepted to inherit hidden classes from each other.

Map1 {
  a: {
    [[Writable]]: true,
    [[Enumerable]]: true,
    [[Configurable]]: true,
  },
  b: {
    [[Writable]]: true,
    [[Enumerable]]: true,
    [[Configurable]]: true,
  }
}

Map2 {
  back_pointer: Map1,
  с: {
    [[Writable]]: true,
    [[Enumerable]]: true,
    [[Configurable]]: true,
  }
}

ob1 {
  map: Map1,
  values: { a: 1, b: 2 }
}

ob2 {
  map: Map2,
  values: { a: 3, b: 4, c: 5 }
}

Here we see that the class Map2 describes only one property and a reference to an object with a more "specific" shape.

It is also worth mentioning that the shape of the hidden class is influenced not only by the set of properties but also by their order. In other words, the following objects will have different shapes of hidden classes.

Map1 {
  a: {
    [[Writable]]: true,
    [[Enumerable]]: true,
    [[Configurable]]: true,
  },
  b: {
    [[Writable]]: true,
    [[Enumerable]]: true,
    [[Configurable]]: true,
  }
}

Map2 {
  b: {
    [[Writable]]: true,
    [[Enumerable]]: true,
    [[Configurable]]: true,
  },
  a: {
    [[Writable]]: true,
    [[Enumerable]]: true,
    [[Configurable]]: true,
  }
}

ob1 {
  map: Map1,
  values: { a: 1, b: 2 }
}

ob2 {
  map: Map2,
  values: { b: 3, a: 4 }
}

If we change the shape of the object after initialization, this also leads to the creation of a new hidden subclass.

const ob1 = { a: 1, b: 2 };
obj1.c = 3;

const obj2 = { a: 4, b: 5, c: 6 };

This example results in the following structure of hidden classes.

Map1 {
  a: {
    [[Writable]]: true,
    [[Enumerable]]: true,
    [[Configurable]]: true,
  },
  b: {
    [[Writable]]: true,
    [[Enumerable]]: true,
    [[Configurable]]: true,
  }
}

Map2 {
  back_pointer: Map1,
  с: {
    [[Writable]]: true,
    [[Enumerable]]: true,
    [[Configurable]]: true,
  }
}

Map3 {
  back_pointer: Map1,
  с: {
    [[Writable]]: true,
    [[Enumerable]]: true,
    [[Configurable]]: true,
  }
}

ob1 {
  map: Map2,
  values: { a: 1, b: 2, c: 3 }
}

ob2 {
  map: Map3,
  values: { a: 4, b: 5, c: 6 }
}

Hidden Classes in Practice

A bit earlier, I referred to Mathias Binnen's post on object shapes. However, many years have passed since then. For the sake of the experiment's purity, I decided to check the practical situation in the real V8 engine.

Let's conduct an experiment using the example provided in Mathias's article.

To do this, we will need the V8's built-in internal method - %DebugPrint. Just a reminder, in order to use the engine's built-in methods, it needs to be launched with the --allow-natives-syntax flag. To see detailed information about JS objects, the engine must be compiled in debug mode.

d8> const a = {};
d8> a.x = 6;
d8> const b = { x: 6 };
d8>
d8> %DebugPrint(a);
DebugPrint: 0x1d47001c9425: [JS_OBJECT_TYPE]
 - map: 0x1d47000da9a9 <Map[28](HOLEY_ELEMENTS)> [FastProperties]
 - prototype: 0x1d47000c4b11 <Object map = 0x1d47000c414d>
 - elements: 0x1d47000006cd <FixedArray[0]> [HOLEY_ELEMENTS]
 - properties: 0x1d47000006cd <FixedArray[0]>
 - All own properties (excluding elements): {
    0x1d4700002b91: [String] in ReadOnlySpace: #x: 6 (const data field 0), location: in-object
 }
0x1d47000da9a9: [Map] in OldSpace
 - map: 0x1d47000c3c29 <MetaMap (0x1d47000c3c79 <NativeContext[285]>)>
 - type: JS_OBJECT_TYPE
 - instance size: 28
 - inobject properties: 4
 - unused property fields: 3
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - stable_map
 - back pointer: 0x1d47000c4945 <Map[28](HOLEY_ELEMENTS)>
 - prototype_validity cell: 0x1d47000da9f1 <Cell value= 0>
 - instance descriptors (own) #1: 0x1d47001cb111 <DescriptorArray[1]>
 - prototype: 0x1d47000c4b11 <Object map = 0x1d47000c414d>
 - constructor: 0x1d47000c4655 <JSFunction Object (sfi = 0x1d4700335385)>
 - dependent code: 0x1d47000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

We see an object a located at the address 0x1d47001c9425. The object is associated with a hidden class at the address 0x1d47000da9a9. Inside the object itself, the value #x: 6 is stored. The property attributes are located in the associated hidden class under the field instance descriptors. Just in case, let's take a look at the array of descriptors at the specified address.

d8> %DebugPrintPtr(0x1d47001cb111)
DebugPrint: 0x1d47001cb111: [DescriptorArray]
 - map: 0x1d470000062d <Map(DESCRIPTOR_ARRAY_TYPE)>
 - enum_cache: 1
   - keys: 0x1d47000dacad <FixedArray[1]>
   - indices: 0x1d47000dacb9 <FixedArray[1]>
 - nof slack descriptors: 0
 - nof descriptors: 1
 - raw gc state: mc epoch 0, marked 0, delta 0
  [0]: 0x1d4700002b91: [String] in ReadOnlySpace: #x (const data field 0:s, p: 0, attrs: [WEC]) @ Any
0x1d470000062d: [Map] in ReadOnlySpace
 - map: 0x1d47000004c5 <MetaMap (0x1d470000007d <null>)>
 - type: DESCRIPTOR_ARRAY_TYPE
 - instance size: variable
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - stable_map
 - non-extensible
 - back pointer: 0x1d4700000061 <undefined>
 - prototype_validity cell: 0
 - instance descriptors (own) #0: 0x1d4700000701 <DescriptorArray[0]>
 - prototype: 0x1d470000007d <null>
 - constructor: 0x1d470000007d <null>
 - dependent code: 0x1d47000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

32190781763857

The array of descriptors contains an element #x, which holds all the necessary information about the object property.

Now let's take a look at the back pointer link with the address 0x1d47000c4945.

d8> %DebugPrintPtr(0x1d47000c4945)
DebugPrint: 0x1d47000c4945: [Map] in OldSpace
 - map: 0x1d47000c3c29 <MetaMap (0x1d47000c3c79 <NativeContext[285]>)>
 - type: JS_OBJECT_TYPE
 - instance size: 28
 - inobject properties: 4
 - unused property fields: 4
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - back pointer: 0x1d4700000061 <undefined>
 - prototype_validity cell: 0x1d4700000a31 <Cell value= 1>
 - instance descriptors (own) #0: 0x1d4700000701 <DescriptorArray[0]>
 - transitions #1: 0x1d47000da9d1 <TransitionArray[6]>Transition array #1:
     0x1d4700002b91: [String] in ReadOnlySpace: #x: (transition to (const data field, attrs: [WEC]) @ Any) -> 0x1d47000da9a9 <Map[28](HOLEY_ELEMENTS)>

 - prototype: 0x1d47000c4b11 <Object map = 0x1d47000c414d>
 - constructor: 0x1d47000c4655 <JSFunction Object (sfi = 0x1d4700335385)>
 - dependent code: 0x1d47000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0
0x1d47000c3c29: [MetaMap] in OldSpace
 - map: 0x1d47000c3c29 <MetaMap (0x1d47000c3c79 <NativeContext[285]>)>
 - type: MAP_TYPE
 - instance size: 40
 - native_context: 0x1d47000c3c79 <NativeContext[285]>

32190780688709

This hidden class represents an empty object. Its array of descriptors is empty, and the back pointer reference is not defined.

Now let's take a look at object b.

d8> %DebugPrint(b)    
DebugPrint: 0x1d47001cb169: [JS_OBJECT_TYPE]
 - map: 0x1d47000dab39 <Map[16](HOLEY_ELEMENTS)> [FastProperties]
 - prototype: 0x1d47000c4b11 <Object map = 0x1d47000c414d>
 - elements: 0x1d47000006cd <FixedArray[0]> [HOLEY_ELEMENTS]
 - properties: 0x1d47000006cd <FixedArray[0]>
 - All own properties (excluding elements): {
    0x1d4700002b91: [String] in ReadOnlySpace: #x: 6 (const data field 0), location: in-object
 }
0x1d47000dab39: [Map] in OldSpace
 - map: 0x1d47000c3c29 <MetaMap (0x1d47000c3c79 <NativeContext[285]>)>
 - type: JS_OBJECT_TYPE
 - instance size: 16
 - inobject properties: 1
 - unused property fields: 0
 - elements kind: HOLEY_ELEMENTS
 - enum length: 1
 - stable_map
 - back pointer: 0x1d47000dab11 <Map[16](HOLEY_ELEMENTS)>
 - prototype_validity cell: 0x1d4700000a31 <Cell value= 1>
 - instance descriptors (own) #1: 0x1d47001cb179 <DescriptorArray[1]>
 - prototype: 0x1d47000c4b11 <Object map = 0x1d47000c414d>
 - constructor: 0x1d47000c4655 <JSFunction Object (sfi = 0x1d4700335385)>
 - dependent code: 0x1d47000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

{x: 6}

The value of the property is also stored within the object itself, while the attributes of the property are stored in an array of descriptors of the hidden class. However, I would like to point out that the back pointer reference here is not empty either, although it should not be present in the parent class diagram provided. Let's take a look at the class through this reference.

d8> %DebugPrintPtr(0x1d47000dab11)
DebugPrint: 0x1d47000dab11: [Map] in OldSpace
 - map: 0x1d47000c3c29 <MetaMap (0x1d47000c3c79 <NativeContext[285]>)>
 - type: JS_OBJECT_TYPE
 - instance size: 16
 - inobject properties: 1
 - unused property fields: 1
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - back pointer: 0x1d4700000061 <undefined>
 - prototype_validity cell: 0x1d4700000a31 <Cell value= 1>
 - instance descriptors (own) #0: 0x1d4700000701 <DescriptorArray[0]>
 - transitions #1: 0x1d47000dab39 <Map[16](HOLEY_ELEMENTS)>
     0x1d4700002b91: [String] in ReadOnlySpace: #x: (transition to (const data field, attrs: [WEC]) @ Any) -> 0x1d47000dab39 <Map[16](HOLEY_ELEMENTS)>
 - prototype: 0x1d47000c4b11 <Object map = 0x1d47000c414d>
 - constructor: 0x1d47000c4655 <JSFunction Object (sfi = 0x1d4700335385)>
 - dependent code: 0x1d47000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0
0x1d47000c3c29: [MetaMap] in OldSpace
 - map: 0x1d47000c3c29 <MetaMap (0x1d47000c3c79 <NativeContext[285]>)>
 - type: MAP_TYPE
 - instance size: 40
 - native_context: 0x1d47000c3c79 <NativeContext[285]>

32190780779281

The class looks exactly like the hidden class of an empty object above, but with a different address. This means that it is, in fact, a duplicate of the previous class. Therefore, the actual structure of this example looks as follows.

This is the first deviation from the theory. To understand the need for another hidden class for an empty object, we will need an object with multiple properties. Let's assume that the original object initially has several properties. It will not be very convenient to explore such an object through a command line, so let's use Chrome DevTools. For convenience, we will enclose the object within the function context.

function V8Snapshot() {
  this.obj1 = { a: 1, b: 2, c: 3, d: 4, e: 5, f: 6 };
}

const v8Snapshot1 = new V8Snapshot();

The memory snapshot shows 6 inherited classes for this object, which equals the number of object properties. This is the second deviation from the theory, according to which it was assumed that the object initially has a single hidden class, the shape of which contains the properties with which it was initialized. The reason for this lies in the fact that in practice we operate not with a single object, but with several, perhaps even tens, hundreds, or thousands. In such circumstances, searching for and restructuring class trees can be quite expensive. So we have come to another concept of JS engines.

Transitions

Let's add another object with a similar shape to the example above.

function V8Snapshot() {
  this.obj1 = { a: 1, b: 2, c: 3, d: 4, e: 5, f: 6 };
  this.obj2 = { a: 1, b: 2, d: 3, c: 4, e: 5, f: 6 };
}

const v8Snapshot1 = new V8Snapshot();

At first glance, the shape of the second object is very similar, but the properties c and d have a different order.

In the descriptor arrays, these properties will have different indexes. The class with the address @101187 has two descendants.

For better clarity, let's run the script log through the V8 System Analyzer.

It is clearly visible here that the original form { a, b, c, d, e, f } extends at the point c. However, the interpreter does not recognize this until it starts initializing the second object. In order to create a new class tree, the engine would have to search for a class in the heap that matches the form, break it down into parts, create new classes, and reassign them to all created objects. To avoid this, the developers of V8 decided to divide the class into a set of minimal forms right away, starting with an empty class during the first object initialization.

{}
{ a }
{ a, b }
{ a, b, c }
{ a, b, c, d }
{ a, b, c, d, e }
{ a, b, c, d, e, f }

The process of creating a new hidden class with the addition or modification of any property is called a transition. In our case, the first object will have 6 transitions initially (+a, +b, +c, etc.).

This approach allows for the following: a) easily find a suitable initial form for the new object, b) there is no need to rebuild anything, just create a new class with a reference to the appropriate minimal form.

              {}
              { a }
              { a, b }

{ a, b, c }            { a, b, d }
{ a, b, c, d }         { a, b, d, c }
{ a, b, c, d, e }      { a, b, d, c, e }
{ a, b, c, d, e, f }   { a, b, d, c, e, f }

In-object and External Properties.

Let's consider the following example:

d8> const obj1 = { a: 1 };
d8> obj1.b = 2;
d8>
d8> %DebugPrint(obj1);
DebugPrint: 0x2387001c942d: [JS_OBJECT_TYPE]
 - map: 0x2387000dabb1 <Map[16](HOLEY_ELEMENTS)> [FastProperties]
 - prototype: 0x2387000c4b11 <Object map = 0x2387000c414d>
 - elements: 0x2387000006cd <FixedArray[0]> [HOLEY_ELEMENTS]
 - properties: 0x2387001cb521 <PropertyArray[3]>
 - All own properties (excluding elements): {
    0x238700002a21: [String] in ReadOnlySpace: #a: 1 (const data field 0), location: in-object
    0x238700002a31: [String] in ReadOnlySpace: #b: 2 (const data field 1), location: properties[0]
 }
0x2387000dabb1: [Map] in OldSpace
 - map: 0x2387000c3c29 <MetaMap (0x2387000c3c79 <NativeContext[285]>)>
 - type: JS_OBJECT_TYPE
 - instance size: 16
 - inobject properties: 1
 - unused property fields: 2
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - stable_map
 - back pointer: 0x2387000d9ca1 <Map[16](HOLEY_ELEMENTS)>
 - prototype_validity cell: 0x2387000dabd9 <Cell value= 0>
 - instance descriptors (own) #2: 0x2387001cb4f9 <DescriptorArray[2]>
 - prototype: 0x2387000c4b11 <Object map = 0x2387000c414d>
 - constructor: 0x2387000c4655 <JSFunction Object (sfi = 0x238700335385)>
 - dependent code: 0x2387000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0
 
 {a: 1, b: 2}

Upon closer inspection of the set of values of this object, we can see that the property a is marked as in-object, while the property b is marked as an element of the properties array.

- All own properties (excluding elements): {
    ... #a: 1 (const data field 0), location: in-object
    ... #b: 2 (const data field 1), location: properties[0]
 }

This example demonstrates that some properties are stored directly inside the object itself ("in-object"), while others are stored in an external storage of properties. This is related to the fact that according to the ECMA-262 specification, JavaScript objects do not have a fixed size. By adding or removing properties from an object, its size changes. This raises the question: how much memory should be allocated for the object? Furthermore, how can we expand the already allocated memory for the object? Developers of V8 addressed these issues as follows.

In-object Properties

At the moment of the object's primary initialization, the object literal has already been parsed, and the AST tree contains information about the properties indicated at the initialization moment. This set of properties is placed directly inside the object, allowing them to be accessed quickly and with minimal overhead. These properties are referred to as in-object.

Let's take another look at the class of an empty object.

d8> const obj1 = {}
d8>
d8> %DebugPrint(obj1);
DebugPrint: 0x2d56001c9ed1: [JS_OBJECT_TYPE]
 - map: 0x2d56000c4945 <Map[28](HOLEY_ELEMENTS)> [FastProperties]
 - prototype: 0x2d56000c4b11 <Object map = 0x2d56000c414d>
 - elements: 0x2d56000006cd <FixedArray[0]> [HOLEY_ELEMENTS]
 - properties: 0x2d56000006cd <FixedArray[0]>
 - All own properties (excluding elements): {}
0x2d56000c4945: [Map] in OldSpace
 - map: 0x2d56000c3c29 <MetaMap (0x2d56000c3c79 <NativeContext[285]>)>
 - type: JS_OBJECT_TYPE
 - instance size: 28
 - inobject properties: 4
 - unused property fields: 4
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - back pointer: 0x2d5600000061 <undefined>
 - prototype_validity cell: 0x2d5600000a31 <Cell value= 1>
 - instance descriptors (own) #0: 0x2d5600000701 <DescriptorArray[0]>
 - prototype: 0x2d56000c4b11 <Object map = 0x2d56000c414d>
 - constructor: 0x2d56000c4655 <JSFunction Object (sfi = 0x2d5600335385)>
 - dependent code: 0x2d56000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

I would like to draw your attention to the parameter inobject properties. Here it is set to 4, even though the object does not have any properties yet. The thing is, empty objects by default have several slots for in-object properties. In V8, the number of such slots is 4.

d8> obj1.a = 1;
d8> obj1.b = 2;
d8> obj1.c = 3;
d8> obj1.d = 4;
d8> obj1.e = 5;
d8> obj1.f = 6;
d8>
d8> %DebugPrint(obj1);
DebugPrint: 0x2d56001c9ed1: [JS_OBJECT_TYPE]
 - map: 0x2d56000db291 <Map[28](HOLEY_ELEMENTS)> [FastProperties]
 - prototype: 0x2d56000c4b11 <Object map = 0x2d56000c414d>
 - elements: 0x2d56000006cd <FixedArray[0]> [HOLEY_ELEMENTS]
 - properties: 0x2d56001cc1a9 <PropertyArray[3]>
 - All own properties (excluding elements): {
    0x2d5600002a21: [String] in ReadOnlySpace: #a: 1 (const data field 0), location: in-object
    0x2d5600002a31: [String] in ReadOnlySpace: #b: 2 (const data field 1), location: in-object
    0x2d5600002a41: [String] in ReadOnlySpace: #c: 3 (const data field 2), location: in-object
    0x2d5600002a51: [String] in ReadOnlySpace: #d: 4 (const data field 3), location: in-object
    0x2d5600002a61: [String] in ReadOnlySpace: #e: 5 (const data field 4), location: properties[0]
    0x2d5600002a71: [String] in ReadOnlySpace: #f: 6 (const data field 5), location: properties[1]
 }
0x2d56000db291: [Map] in OldSpace
 - map: 0x2d56000c3c29 <MetaMap (0x2d56000c3c79 <NativeContext[285]>)>
 - type: JS_OBJECT_TYPE
 - instance size: 28
 - inobject properties: 4
 - unused property fields: 1
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - stable_map
 - back pointer: 0x2d56000db169 <Map[28](HOLEY_ELEMENTS)>
 - prototype_validity cell: 0x2d56000dace9 <Cell value= 0>
 - instance descriptors (own) #6: 0x2d56001cc1f5 <DescriptorArray[6]>
 - prototype: 0x2d56000c4b11 <Object map = 0x2d56000c414d>
 - constructor: 0x2d56000c4655 <JSFunction Object (sfi = 0x2d5600335385)>
 - dependent code: 0x2d56000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

This means that the first 4 properties added to an empty object will be placed in these slots as in-object properties.

External Properties

Properties that were added after initialization can no longer be placed inside the object since memory for the object is already allocated. To avoid wasting resources on reallocating the entire object, the engine places such properties in an external storage, in this case, in an external array of properties, a reference to which already exists inside the object. These properties are called external or normal (this exact term can often be found in publications by V8 developers). Access to such properties is slightly slower, as it requires resolving the reference to the storage and obtaining the property by index. However, this is much more efficient than reallocating the entire object.

Fast and Slow Properties

The external property from the example above, as we have just discussed, is stored in an external property array directly linked to our object. The data format in this array is identical to the format of internal properties. In other words, only property values are stored there, while metadata about them is placed in the descriptors array, which also contains information about internal properties. Essentially, external properties differ from internal ones only in the location where they are stored. Both can be considered fast properties in a broad sense. However, I would like to remind you that JavaScript is a dynamic and flexible programming language. A developer has the ability to add, remove, and modify object properties as desired. Active changes to the set of properties can lead to significant processor time costs. To optimize this process, V8 supports the so-called "slow" properties. The essence of slow properties lies in using a different type of external storage. Instead of an array of values, properties are placed in a separate dictionary object together with all their attributes. Access to both the values and attributes of such properties is done by their name, which serves as the key to the dictionary.

d8> delete obj1.a;
d8>
d8> %DebugPrint(obj1)
DebugPrint: 0x2387001c942d: [JS_OBJECT_TYPE]
 - map: 0x2387000d6071 <Map[12](HOLEY_ELEMENTS)> [DictionaryProperties]
 - prototype: 0x2387000c4b11 <Object map = 0x2387000c414d>
 - elements: 0x2387000006cd <FixedArray[0]> [HOLEY_ELEMENTS]
 - properties: 0x2387001cc1d9 <NameDictionary[30]>
 - All own properties (excluding elements): {
   b: 2 (data, dict_index: 2, attrs: [WEC])
 }
0x2387000d6071: [Map] in OldSpace
 - map: 0x2387000c3c29 <MetaMap (0x2387000c3c79 <NativeContext[285]>)>
 - type: JS_OBJECT_TYPE
 - instance size: 12
 - inobject properties: 0
 - unused property fields: 0
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - dictionary_map
 - may_have_interesting_properties
 - back pointer: 0x238700000061 <undefined>
 - prototype_validity cell: 0x238700000a31 <Cell value= 1>
 - instance descriptors (own) #0: 0x238700000701 <DescriptorArray[0]>
 - prototype: 0x2387000c4b11 <Object map = 0x2387000c414d>
 - constructor: 0x2387000c4655 <JSFunction Object (sfi = 0x238700335385)>
 - dependent code: 0x2387000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

{b: 2}

We have deleted the property obj1.a. Despite the fact that the property was internal, we completely changed the shape of the hidden class. To be precise, we have shrunk it, which is different from the typical shape extension. This means that the tree of shpaes has become shorter; hence, the descriptors and value arrays must also be reconstructed. All these operations require certain time resources. In order to avoid this, the engine changes the way object properties are stored to a slower method using an object dictionary. In this example, the dictionary (NameDictionary) is located at address 0x2387001cc1d9.

d8> %DebugPrintPtr(0x2387001cc1d9)
DebugPrint: 0x2387001cc1d9: [NameDictionary]
 - FixedArray length: 30
 - elements: 1
 - deleted: 1
 - capacity: 8
 - elements: {
              7: b -> 2 (data, dict_index: 2, attrs: [WEC])
 }
0x238700000ba1: [Map] in ReadOnlySpace
 - map: 0x2387000004c5 <MetaMap (0x23870000007d <null>)>
 - type: NAME_DICTIONARY_TYPE
 - instance size: variable
 - elements kind: HOLEY_ELEMENTS
 - enum length: invalid
 - stable_map
 - back pointer: 0x238700000061 <undefined>
 - prototype_validity cell: 0
 - instance descriptors (own) #0: 0x238700000701 <DescriptorArray[0]>
 - prototype: 0x23870000007d <null>
 - constructor: 0x23870000007d <null>
 - dependent code: 0x2387000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

39062729441753

Arrays

According to the 23.1 Array Objects section of the specification, an array is an object whose keys are integers from 0 to 2**32 - 2. On the one hand, it seems that from the perspective of hidden classes, an array is no different from a regular object. However, in practice, arrays can be quite large. What if there are thousands of elements in an array? Will a separate hidden class be created for each element? Let's see what the hidden class of an array actually looks like.

d8> arr = [];
d8> arr[0] = 1;
d8> arr[1] = 2;
d8>
d8> %DebugPrint(arr); 
DebugPrint: 0x24001c9421: [JSArray]
 - map: 0x0024000ce6b1 <Map[16](PACKED_SMI_ELEMENTS)> [FastProperties]
 - prototype: 0x0024000ce925 <JSArray[0]>
 - elements: 0x0024001cb125 <FixedArray[17]> [PACKED_SMI_ELEMENTS]
 - length: 2
 - properties: 0x0024000006cd <FixedArray[0]>
 - All own properties (excluding elements): {
    0x2400000d41: [String] in ReadOnlySpace: #length: 0x00240030f6f9 <AccessorInfo name= 0x002400000d41 <String[6]: #length>, data= 0x002400000061 <undefined>> (const accessor descriptor), location: descriptor
 }
 - elements: 0x0024001cb125 <FixedArray[17]> {
           0: 1
           1: 2
        2-16: 0x0024000006e9 <the_hole_value>
 }
0x24000ce6b1: [Map] in OldSpace
 - map: 0x0024000c3c29 <MetaMap (0x0024000c3c79 <NativeContext[285]>)>
 - type: JS_ARRAY_TYPE
 - instance size: 16
 - inobject properties: 0
 - unused property fields: 0
 - elements kind: PACKED_SMI_ELEMENTS
 - enum length: invalid
 - back pointer: 0x002400000061 <undefined>
 - prototype_validity cell: 0x002400000a31 <Cell value= 1>
 - instance descriptors #1: 0x0024000cef3d <DescriptorArray[1]>
 - transitions #1: 0x0024000cef59 <TransitionArray[4]>Transition array #1:
     0x002400000e05 <Symbol: (elements_transition_symbol)>: (transition to HOLEY_SMI_ELEMENTS) -> 0x0024000cef71 <Map[16](HOLEY_SMI_ELEMENTS)>

 - prototype: 0x0024000ce925 <JSArray[0]>
 - constructor: 0x0024000ce61d <JSFunction Array (sfi = 0x2400335da5)>
 - dependent code: 0x0024000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

[1, 2]

As we can see, in the hidden class of this object, the back pointer reference is empty, indicating the absence of a parent class, even though we have added two elements. The thing is, the hidden class of any array always has a uniform shape of JS_ARRAY_TYPE. This is a special hidden class that only has one property in its descriptors - length. The array elements, on the other hand, are arranged inside the object in a FixedArray structure. In reality, hidden array classes can still be inherited, as the elements themselves can have different data types, and keys, depending on the number, can be stored in different ways for optimization of access to them. In this article, I will not delve into all the possible transitions within arrays in detail, as this is a topic for a separate article. However, it is worth noting that various non-standard manipulations with array keys can lead to the creation of a class tree for all or some of the elements.

d8> const arr = [];
d8> arr[-1] = 1;
d8> arr[2**32 - 1] = 2;
d8>
d8> %DebugPrint(arr)
DebugPrint: 0xe0b001c98c9: [JSArray]
 - map: 0x0e0b000dacc1 <Map[16](PACKED_SMI_ELEMENTS)> [FastProperties]
 - prototype: 0x0e0b000ce925 <JSArray[0]>
 - elements: 0x0e0b000006cd <FixedArray[0]> [PACKED_SMI_ELEMENTS]
 - length: 0
 - properties: 0x0e0b001cb5f1 <PropertyArray[3]>
 - All own properties (excluding elements): {
    0xe0b00000d41: [String] in ReadOnlySpace: #length: 0x0e0b0030f6f9 <AccessorInfo name= 0x0e0b00000d41 <String[6]: #length>, data= 0x0e0b00000061 <undefined>> (const accessor descriptor), location: descriptor
    0xe0b000dab35: [String] in OldSpace: #-1: 1 (const data field 0), location: properties[0]
    0xe0b000daca9: [String] in OldSpace: #4294967295: 2 (const data field 1), location: properties[1]
 }
0xe0b000dacc1: [Map] in OldSpace
 - map: 0x0e0b000c3c29 <MetaMap (0x0e0b000c3c79 <NativeContext[285]>)>
 - type: JS_ARRAY_TYPE
 - instance size: 16
 - inobject properties: 0
 - unused property fields: 1
 - elements kind: PACKED_SMI_ELEMENTS
 - enum length: invalid
 - stable_map
 - back pointer: 0x0e0b000dab45 <Map[16](PACKED_SMI_ELEMENTS)>
 - prototype_validity cell: 0x0e0b000dab95 <Cell value= 0>
 - instance descriptors (own) #3: 0x0e0b001cb651 <DescriptorArray[3]>
 - prototype: 0x0e0b000ce925 <JSArray[0]>
 - constructor: 0x0e0b000ce61d <JSFunction Array (sfi = 0xe0b00335da5)>
 - dependent code: 0x0e0b000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

[]

In the example above, both elements -1 and 2**32 - 1 are not within the range of possible array indexes [0 .. 2**32 - 2] and were declared as regular object properties with corresponding shapes and hidden class tree generation.

Another exceptional situation may occur when attempting to change the index attributes. For elements to be stored in a fast store, all indexes must have the same configuration. Trying to change the attributes of any of the indexes will not result in the creation of a separate property, but will lead to a change in the storage type to slow, in which not only values but also attributes of each index will be stored. Essentially, the same rule is applied here as with slow object properties.

d8> const arr = [1];
d8> Object.defineProperty(arr, '0', { value: 2, writable:  false });      
d8> arr.push(3);
d8>
d8> %DebugPrint(arr);
DebugPrint: 0x29ee001c9425: [JSArray]
 - map: 0x29ee000dad05 <Map[16](DICTIONARY_ELEMENTS)> [FastProperties]
 - prototype: 0x29ee000ce925 <JSArray[0]>
 - elements: 0x29ee001cb391 <NumberDictionary[16]> [DICTIONARY_ELEMENTS]
 - length: 2
 - properties: 0x29ee000006cd <FixedArray[0]>
 - All own properties (excluding elements): {
    0x29ee00000d41: [String] in ReadOnlySpace: #length: 0x29ee0030f6f9 <AccessorInfo name= 0x29ee00000d41 <String[6]: #length>, data= 0x29ee00000061 <undefined>> (const accessor descriptor), location: descriptor
 }
 - elements: 0x29ee001cb391 <NumberDictionary[16]> {
   - requires_slow_elements
   0: 2 (data, dict_index: 0, attrs: [_EC])
   1: 3 (data, dict_index: 0, attrs: [WEC])
 }
0x29ee000dad05: [Map] in OldSpace
 - map: 0x29ee000c3c29 <MetaMap (0x29ee000c3c79 <NativeContext[285]>)>
 - type: JS_ARRAY_TYPE
 - instance size: 16
 - inobject properties: 0
 - unused property fields: 0
 - elements kind: DICTIONARY_ELEMENTS
 - enum length: invalid
 - stable_map
 - back pointer: 0x29ee000cf071 <Map[16](HOLEY_ELEMENTS)>
 - prototype_validity cell: 0x29ee00000a31 <Cell value= 1>
 - instance descriptors (own) #1: 0x29ee000cef3d <DescriptorArray[1]>
 - prototype: 0x29ee000ce925 <JSArray[0]>
 - constructor: 0x29ee000ce61d <JSFunction Array (sfi = 0x29ee00335da5)>
 - dependent code: 0x29ee000006dd <Other heap object (WEAK_ARRAY_LIST_TYPE)>
 - construction counter: 0

[2, 3]

Conclusion

In this article, we have delved deeper into the methods of storing object properties, concepts of hidden classes, object shapes, object descriptors, internal and external properties, as well as fast and slow methods of storing them. Let us now briefly recap the main terms and conclusions.

Every object in JavaScript has its main internal class and a hidden class that describes its shape.
Hidden classes inherit from each other and are organized into class trees. The shape of an object { a: 1 } will be the parent for the shape of an object { a: 1, b: 2 }.
The order of properties matters. Objects { a: 1, b: 2 } and { b: 2, a: 1 } will have two different shapes.
A subclass holds a reference to the superclass and information about what has changed (transition).
In the class tree of each object, the number of levels is not less than the number of properties in the object.
The fastest properties of an object will be those declared at initialization. In the following example, access to the property obj1.a will be faster than to obj2.a.

const obj1 = { a: undefined };
obj1.a = 1; // <- "a" - in-object property

const obj2 = {};
obj2.a = 1; // <- "a" - external property

Atypical changes in the object's structure, such as property removal, can lead to a change in the storage type of properties to a slower one. In the following example, obj1 will change its type to NamedDictionary, and accessing its properties will be significantly slower than accessing the properties of obj2.

const obj1 = { a: 1, b: 2 };
delete obj1.a; // cheanges a storage type to NameDictionary 

const obj2 = { a: 1, b: 2 };
obj2.a = undefined; // a storage type is not changed

If an object has external properties but the internal ones are less 4, such an object can be slightly optimized, as an empty object by default has several slots for in-object properties.

const obj1 = { a: 1 };
obj1.b = 2;
obj1.c = 3;
obj1.d = 4;
obj1.e = 5;
obj1.f = 6;

%DebugPrint(obj1);
...
- All own properties (excluding elements): {
    ...#a: 1 (const data field 0), location: in-object
    ...#b: 2 (const data field 1), location: properties[0]
    ...#c: 3 (const data field 2), location: properties[1]
    ...#d: 4 (const data field 3), location: properties[2]
    ...#e: 5 (const data field 4), location: properties[3]
    ...#f: 6 (const data field 5), location: properties[4]
 }

const obj2 = Object.fromEntries(Object.entries(obj1));

%DebugPrint(obj2);
...
 - All own properties (excluding elements): {
    ...#a: 1 (const data field 0), location: in-object
    ...#b: 2 (const data field 1), location: in-object
    ...#c: 3 (const data field 2), location: in-object
    ...#d: 4 (const data field 3), location: in-object
    ...#e: 5 (const data field 4), location: properties[0]
    ...#f: 6 (const data field 5), location: properties[1]
 }

An array is a regular class whose structure looks like { length: [W__] }. The elements of the array are stored in special structures, and references to these structures are placed inside the object. Adding or removing elements from the array does not lead to an increase in the class tree.

const arr = [];
arr[0] = 1; // new element of the array doesn't extends the shapes tree

const obj = {};
obj1[0] = 1; // each new property extends the shapes tree

The use of atypical keys in an array, such as non-numeric keys or keys outside the range [0 .. 2**32 - 2], leads to the creation of new shapes in the class tree.

const arr = [];
arr[-1] = 1;
arr[2**32 - 1] = 2;
// Leads to the shapes tree generation
// { length } => { length, [-1] } => { length, [-1], [2**32 - 1] }

Attempting to modify an array element's attribute will result in a switch to a slower storage type.

const arr = [1, 2, 3];
// { elements: {
//   #0: 1,
//   #1: 2,
//   #2: 3
// }}

Object.defineProperty(arr, '0', { writable: false };
// { elements: {
//   #0: { value: 1, attrs: [_EC] }, 
//   #1: { value: 2, attrs: [WEC] },
//   #2: { value: 3, attrs: [WEC] }
// }}

My telegram channels:

EN - https://t.me/frontend_almanac
RU - https://t.me/frontend_almanac_ru

Русская версия: https://blog.frontend-a lmanac.ru/js-object-structure

State management in React applications

2024-03-19T19:09:17.606Z

The issue of state management in React applications has always been very relevant. React itself, when it first came out, did not offer any comprehensive approaches to state management and left this task to the developers. The technical tools available were the classic component properties and the internal state of components. The standard basic concept was extremely primitive and involved storing data in the component's state. Thus, global data could be stored in the state of the top component, while more specific data could be stored in the states of lower components. The only built-in way to exchange data between components was to use component properties.

Prop drilling

The typical approach looks something like this:

class App extends React.Component {
  constructor(props) {
    super(props);

    // initialize the state with default values
    this.state = {
      a: '',
      b: 0,
    };
  }

  render() {
    // pass data from the state to a child component
    return <Child a={this.state.a} b={this.state.b} />;
  }
}

class Child extends React.Component<any, any> {
  // the child component receives data through the reference this.props
  render() {
    return (
      <div>
        <div>{this.props.a}</div>
        <div>{this.props.b}</div>
      </div>
    );
  }
}

ReactDOM.render(<App />, document.getElementById('root'));

In the example above, the data is stored in the state of the parent component and passed to the child component through props. The child component may also have its own internal state.

class Child extends React.Component {
  constructor(props) {
    super(props);

    this.state = {
      c: 2,
    };
  }

  render() {
    return (
      <div>
        <div>{this.props.a}</div>
        <div>{this.props.b}</div>
        <Child2 c={this.state.c} />
      </div>
    );
  }
}

class Child2 extends React.Component {
  render() {
    return (
      <div>
        <div>{this.props.c}</div>
      </div>
    );
  }
}

In this case, changing the component's state is only possible by calling the method this.setState inside the component, meaning the child component can update the parent-level data only if it has the corresponding method passed to it through the same props.

class App extends React.Component {
  constructor(props) {
    super(props);

    this.state = {
      a: '',
      b: 0,
    };
  }

  render() {
    return (
      <Child
        a={this.state.a}
        b={this.state.b}
        setB={(b) => {
          this.setState({ b });
        }}
      />
    );
  }
}

class Child extends React.Component<any, any> {
  constructor(props) {
    super(props);

    this.state = {
      c: 2,
    };
  }

  render() {
    return (
      <div>
        <div>{this.props.a}</div>
        <div>{this.props.b}</div>
        <Child2
          b={this.state.b}
          c={this.state.c}
          setB={this.props.setB}
        />
      </div>
    );
  }
}

class Child2 extends React.Component {
  render() {
    return (
      <div>
        <div>{this.props.c}</div>

        <button
          onClick={() => {
            this.props.setB(this.props.b + 1);
          }}
        >
          Increment
        </button>
      </div>
    );
  }
}

At this stage, the problem of this approach becomes apparent. In real applications with a large number of components, this scheme leads to what is known as prop drilling, which is the mass passing of references down the component tree and back up. This inevitably leads to:

a) Data update race, where two components, unaware of each other, try to update the same reference in the state;

b) Components acting as intermediaries for data they don't actually operate with;

c) Complexity in replacing a component in the middle of the chain;

d) A long and convoluted graph of state references.

Additionally, the task was further complicated by the fact that in the early versions of React, simple functional components did not have internal state (hooks didn't exist back then).

const Child3 = ({ c }) => {
  // A functional component does not have this.state, the useState()
  // hook was introduced only in 2019 starting from version 16.8.0.
  return <div>{c}</div>;
};

Flux

Needless to say, the approach shown above led to a large number of errors and exponentially increasing code complexity. Even the creators of "React" could not avoid this. In the past years, errors related to various asynchronous processes such as disappearing or not displaying notifications and others constantly appeared on the "Facebook" website. In response, developers began to work on a new approach to organizing data management in the application, giving rise to the Flux pattern. The precursor of this pattern was the classic and very popular MVC pattern at the time. The essence of Flux is that data should always move in one direction and be stored in a separate large store. Data updates are carried out using special action methods that are not tied to any specific component.

Based on the Flux pattern, many state management libraries appeared, such as Fluxxor, Flummox, Baobab, and many others. The most popular of them, over the years and to this day, is Redux.

Redux

The application state management library Redux appeared in 2015 and has since gained immense popularity. Redux has proven the effectiveness of the Flux approach and until recently has been considered the standard in the React world.

The architecture of a typical application has taken the following form.

import { connect, Provider } from 'react-redux';

const defaultState1 = {
  a: "",
  b: 0
};

const reducer1 = function(state = defaultState1, action) {
  switch(action.type){
    case "A_TYPE":
      return { ...state, a: action.payload };
    case "B_TYPE":
      return { ...state, b: action.payload };
  }

  return state;
};

const defaultState2 = {
  c: false,
  d: []
};

const reducer2 = function(state = defaultState2, action) {
  switch(action.type){
    case "C_TYPE":
      return { ...state, c: action.payload };
    case "D_TYPE":
      return { ...state, c: action.payload };
  }

  return state;
};

const store = createStore(
  combineReducers({
    reducer1,
    reducer2
  })
);

const App = connect(
  (state) => ({ b: state.reducer1.b }),
  (dispatch) => {
    setB: (value) => dispatch({ type: "B_TYPE", payload: value }) 
  }
)(({ b }) => {
  return (
    <Provider store={store}>
      <button
        onClick={() => {
          setB(b + 1)
        }}
      >
        Increase {b}
      </button>
    </Provider>
  );
});

Now all the data in the application is stored in a separate large tree outside of any component. It is possible to "connect" to the tree, meaning to listen to all the changes in the necessary branch and react to these changes. To update a value in the tree, you can send a so-called action - an event containing an object with the field type. Based on this type, the reducer will understand what kind of action it is and execute the corresponding mutation of the tree.

In general, the issue that seemed to be resolved. Data live separately, components separately. No race or prop drilling. However, the price for this is bulky constructions to ensure the viability of the storage itself. A reducer and action are needed for each property of the tree. Moreover, in more complex applications, as the tree grows, specific cases begin to arise. For example, in deeply nested objects, it becomes harder to maintain immutability, leading to unresponsive reactions to state changes. Additional libraries have come to the help, such as immutable-js and reselect.

Then the issue of working with requests arose, as requests are the main source of data in the application in most cases. This meant that there was a need to add asynchrony to reducers. That's how redux-thunk and redux-saga came about. However, even that was not enough.

Requests, in addition to data, also have their own state. The average application needs to know at least whether the request is still in progress or the response has already been received. Traditionally, the request execution flag (usually called "isFetching" or "isLoading") was stored right in the tree, which required keeping the same mechanism for setting this flag for each request. Along with the loading flag in the same situation was the handling of request errors. The error message was also stored in the tree next to the data and loading flag. Digging deeper, advanced applications wanted to cache responses to requests for optimization purposes to avoid requesting data over the network every time a component is mounted, for example. All these routine operations and optimizations further bloated the already not small code serving the state tree. Therefore, the appearance of libraries like redux-toolkit (RTK) seems quite logical. The RTK library allows organizing work with the state tree in a unified pattern. And in combination with the additional rtk-query, you can get request caching and information on their status out of the box. However, it is still impossible to completely get rid of actions and reducers in this way.

useReducer

"Redux" and other Flux-like libraries are third-party developments. Of course, the "React" team did not stand aside and added the ability to work in a "Flux" style to the API. In fact, this is reflected in the introduction of the useReducer hook in React version 16.8.0.

The same example that was mentioned above can now be implemented without using "Redux."

const reducer = (state, action) => {
  switch (action.type) {
    case 'A_TYPE':
      return { ...state, a: action.payload };
    case 'B_TYPE':
      return { ...state, b: action.payload };

    default:
      return state;
  }
};

export const App = () => {
  const [state, dispatch] = useReducer(reducer, { a: "", b: 0 });

  return (
    <button
      onClick={() => {
        dispatch({ type: "A_TYPE", payload: b + 1 })
      }}
    >
      Increase {state.b}
    </button>
  );
};

However, all the previously mentioned issues related to working with Redux are also relevant to useReducer. Since Redux has grown with a multitude of additional libraries and tools, the hook has not gained much popularity among developers.

React context

The context in React has existed since the earliest versions. However, it was officially included in the API only starting from version 16.3.0 in 2018. The essence of the approach is as follows: data that needs to be made available to multiple components is placed in a separate independent location using the createContext() API method.

const MyContext = createContext({ a: "", b: 0 });

The result of the createContext method is an object containing references to the provider and consumer of the created context.

The provider should wrap a component or a tree of components that will have access to the data inside this context.

class App extends React.Component<any, any> {
  render() {
    return (
      <MyContext.Provider value={{ a: '', b: 0 }}>
        <Child />
      </MyContext.Provider>
    );
  }
}

class Child extends React.Component<any, any> {
  contextType = MyContext;

  render() {
    return (
      <div>
        <div>{this.context.a}</div>
        <Child2 />
      </div>
    );
  }
}

const Child2 = () => {
  return (
    <MyContext.Consumer>
      {(context) => <div>{context.b}</div>}
    </MyContext.Consumer>
  );
};

Access to the context is provided through a consumer link. In a class component, you can bind the context to the component by defining the contextType property. In functional components, you can use a direct reference to the consumer - MyContext.Consumer.

With the official support for context API in functional components, the useContext hook became available.

const Child2 = () => {
  const { b } = useContext(MyContext);

  return (
    <div>{b}</div>
  );
};

The component that created the context is responsible for updating the data in the context.

class App extends React.Component<any, any> {
  const [a, setA] = useState("");
  const [b, setB] = useState(0);

  render() {
    return (
      <MyContext.Provider value={{ a, b }}>
        <Child />
        <button onClick={() => setB(b => b + 1)}>
          Increase {b}
        </button>
      </MyContext.Provider>
    );
  }
}

If you need to delegate the ability to update data to lower-level components, you can also place a reference to the action in the context itself.

class App extends React.Component<any, any> {
  const [a, setA] = useState("");
  const [b, setB] = useState(0);

  render() {
    return (
      <MyContext.Provider value={{ a, b, setB }}>
        <Child />
      </MyContext.Provider>
    );
  }
}

const Child = () => {
  const { b, setB } = useContext(MyContext);

  return (
    <button onClick={() => setB(b => b + 1)}>
      Increase {b}
    </button>
  );
};

This way, you can control the context mutation process and allow modification of only those parts that are needed. Moreover, you can add intermediate actions similar to "Redux middleware" for even greater control over mutations.

class App extends React.Component<any, any> {
  const [a, setA] = useState("");
  const [b, setB] = useState(0);
  
  const increaseB = () => {
    setB((b) => {
      return b < 10 ? b + 1 : b;
    });
  };

  render() {
    return (
      <MyContext.Provider value={{ a, b, increaseB }}>
        <Child />
      </MyContext.Provider>
    );
  }
}

const Child = () => {
  const { b, increaseB } = useContext(MyContext);

  return (
    <button onClick={increaseB}>
      Increase {b}
    </button>
  );
};

Among the advantages of context are:

Flexibility

The context storage is extremely primitive, and the API consists of simple wrapper methods. Therefore, the developer has maximum control at all stages of context design.

Selectivity

Unlike Redux with its global tree, each specific context has the ability to wrap only the necessary components. Conversely, a component can be wrapped in several contexts at once. This allows you to control which data will be available and where.

Uniqueness

In some cases, there may be a need to duplicate the context model. This may be necessary, for example, when working with arrays.

import { connect, Provider } from 'react-redux';

const defaultState = {
  items: [
    { id: 1, name: "item 1" },
    { id: 2, name: "item 2" },
    { id: 3, name: "item 3" },
  ],
  selectedId: undefined,
};

const reducer = function(state = defaultState, action) {
  switch(action.type){
    case "SET_SELECTED_ID_TYPE":
      return {
        ...state,
        selectedId: action.id,
      };
    default:
      return state;
  }

  return state;
};

const store = createStore(reducer);

const SelectedItem = connect(
  (state) => ({ item: state.reducer.items.find(item => item.id === state.selectedId) }),
)(({ item }) => {
  return item ? null : (
    <div>
      Seleceted item: {item?.title}
    </div>
  );
});

const ItemsList = connect(
  (state) => ({
    items: state.reducer.items,
  }),
  (dispatch = {
    setItem: (id) => dispatch({ type: 'SET_SELECTED_ID_TYPE', id }),
  })
)(({ items, setItem }) => {
  return (
    <div>
      {items.map((item) => (
        <button key={item.id} onClick={() => setItem(item.id)}>
          {item.title}
        </button>
      ))}

      <SelectedItem />
    </div>
  );
});

In this example, everything seems fine as long as the ItemsList component is mounted. However, if we unmount it, for example, change the route, and then return to it again, the old value of selectedId will remain in the Redux tree. If we expect to see the default value here rather than the old one, we will have to take care of this separately and add the corresponding logic.

This example is quite simple. In practice, much more complex cases are encountered, which cannot be solved with a simple reset action.

In the case of context, the architecture could look like this, for example.

const ItemContext = createContext();

const SelectedItem: FC = ({ title }) => {
  const { title } = useContext(ItemContext);

  return <div>Selected item: {title}</div>;
};

const ItemsList: FC = () => {
  const [items] = useState([
    { id: 1, name: 'item 1' },
    { id: 2, name: 'item 2' },
    { id: 3, name: 'item 3' },
  ]);

  const [selectedItemId, setSelectedItemId] = useState();

  const item = useMemo(
    () => items.find((item) => item.id === selectedItemId),
    [items, selectedItemId]
  );

  return (
    <div>
      {items.map((item) => (
        <button key={item.id} onClick={() => setSelectedItemId(item.id)}>
          {item.title}
        </button>
      ))}

      {item && (
        <ItemContext.Provider value={item}>
          <SelectedItem />
        </ItemContext.Provider>
      )}
    </div>
  );
};

Since the data lives inside the ItemsList component, upon its remount, the state will always have the original appearance, and we do not need to worry additionally about its reset.

Meanwhile, the SelectedItem component operates within the ItemContext and even has no idea where and how the data has placed there.

Universal pattern of using React context

Below, I will present a universal template for typical usage of context in a real application. Like Redux, contexts work well with TypeScript, so I will provide an example with TS typing.

To begin with, let's create an independent context and a separate provider component for it.

// MyContext.tsx
import React, {
  createContext,
  Dispatch,
  FC,
  PropsWithChildren,
  SetStateAction,
  useCallback,
  useContext,
  useMemo,
  useState,
} from 'react';

export interface MyContextProps {
  myVar: string;
  setMyVar: Dispatch<SetStateAction<MyContextProps['myVar']>>;

  someAction: (a: number, b?: boolean) => void;
}

export const MyContext = createContext<MyContextProps>({
  myVar: '',
  setMyVar: () => {},

  someAction: () => {},
});

// instead of using WithMyContext, you can use a more traditional
// name - MyContextProvider
export const WithMyContext: FC<PropsWithChildren> = ({ children }) => {
  const [myVar, setMyVar] = useState<MyContextProps['myVar']>('');

  const someAction = useCallback<MyContextProps['someAction']>(
    (a, b) => {},
    []
  );

  const value = useMemo<MyContextProps>(
    () => ({
      myVar,
      setMyVar,

      someAction,
    }),
    [myVar, someAction]
  );

  return <MyContext.Provider value={value}>{children}</MyContext.Provider>;
};

// let's also create a separate hook for convenience.
export const useMyContext = () => {
  return useContext(MyContext);
};

The context is ready, now we just need to wrap the necessary component in it.

<WithMyContext>
  <MyComponent />
</WithMyContext>

Or, for instance, a specific route in "react-router".

<Route element={(
  <WithMyContext>
    <Outlet />
  </WithMyContext>
)}>
  <Route …>
</Route>

Now the context is available for use within nested components.

import { FC } from 'react';

import { useMyContext } from ‘./MyContext';

export const MyComponent: FC = () => {
  const { myVar } = useMyContext();

  return <div>My component {myVar}</div>;
};

My telegram channels:

EN - https://t.me/frontend_almanac
RU - https://t.me/frontend_almanac_ru

Русская версия: https://blog.frontend-almanac.ru/react-state-management

Garbage Collection in V8

2024-03-07T17:36:35.286Z

In this article, we will delve into the process of garbage collection by the V8 engine in detail. We will familiarize ourselves with the concepts of generations, Minor and Major Garbage Collections, see how objects are allocated, traced, and marked in memory. We will also explore what happens to empty spaces after cleaning and how garbage collection is performed in the background.

What the garbage collector collects

Before diving into the garbage collection process itself, let's first understand what exactly V8 collects and how it traces objects.

During V8 work, there can be various data structures in memory. Some of these structures are internal representations of V8 itself, such as hidden classes, lists, queues, and more. Another part consists of JavaScript objects. Practically all data types inside V8 are objects, except for so-called SMI - small numbers not exceeding 2^30 - 1, which are stored in memory as direct binary values, and all variables that have such a value store a reference to the memory area with this specific SMI value. I have written more on this in the article Deep JS. In memory of data and types. All other types are represented in memory as objects and simulate their mutability/immutability in accordance with the ECMA-262 specification, issuing, as we commonly say, "primitive" or "reference" types.

Indeed, the garbage collection process is not limited to JavaScript objects. The Chromium engine provides garbage collection for anything that can be collected, including removed HTML elements, unused CSS stylesheets, completed animations, and more. Since Chromium is written in C++, its internal engine objects are, obviously, C++ classes. However, JavaScript objects, although created using the same language, are more abstract concepts and must adhere to the requirements of the ECMA-262 specification. In particular, JavaScript objects do not have a fixed size and can change dynamically. The structure of a JavaScript heap differs from that of a C++ heap. Let's take a closer look at how such objects are placed in memory. It is important to understand that the process of collecting dead JavaScript objects will somewhat differ from the collection of C++ objects.

A few years ago, in approximately 2018, the Chromium team began developing a system for collecting dead C++ objects. The system was named Oilpan and became part of the internal rendering engine Blink. Later, in 2020, the developers decided to move the system inside the V8 engine. On one hand, V8 uses the same garbage collection mechanisms as Blink, and on the other hand, migrating to V8 makes the system available to third-party developers who integrate the V8 engine but do not use Blink, such as Node.js. As a result, the cppgc directory appeared in the V8 API.

Objects Tracing

As I mentioned before, the essence of garbage collection is to free memory from "dead" objects. An object is considered dead when there is no longer any reference to it, meaning it cannot be accessed. Therefore, such an object can no longer be used and should be cleared. Conversely, a "live" object is an object that can be reached through references from the root.

The simplified tracing scheme is depicted in the figure above. References to all created objects are stored in a separate global table called GlobalGCInfoTable. During garbage collection, an iterative traversal of objects occurs from roots (there can be multiple roots, and the traversal is carried out through all active roots). Objects reachable by the garbage collector are considered "live", and they are marked in black. All other objects are considered "dead" and marked in white.

Tracing C++ Objects

As I said earlier, C++ objects differ from JavaScript objects. The key difference is that JavaScript objects are standardized and described in section 6.1.7 The Object Type of the specification, making them predictable for the garbage collector. On the other hand, C++ objects are not standardized, and their structures can vary significantly. Moreover, not every C++ object needs to be potentially collectible. Therefore, a special API was provided for C++ objects in Oilpan.

There is a post in the V8 blog titled High-performance garbage collection for C++. I won't retell the entire post; I'll just outline the main concept. C++ objects that are intended to be collected by the garbage collector must implement GarbageCollected or GarbageCollectedMixin interfaces. In fact, this means that the object must have a Trace() method in which the object itself must call the tracing of other objects it references.

For example, here is what the tracing of the RunningAnimation class looks like (at the time of writing the article, in Chromium version 124.0.6339.1):

src/third_party/blink/renderer/core/animation/css/css_animations.h

class RunningAnimation final : public GarbageCollected<RunningAnimation> {
 public:
  RunningAnimation(Animation* animation, NewCSSAnimation new_animation)
      : animation(animation),
        name(new_animation.name),
        name_index(new_animation.name_index),
        specified_timing(new_animation.timing),
        style_rule(new_animation.style_rule),
        style_rule_version(new_animation.style_rule_version),
        play_state_list(new_animation.play_state_list) {}

  AnimationTimeline* Timeline() const {
    return animation->TimelineInternal();
  }
  const std::optional<TimelineOffset>& RangeStart() const {
    return animation->GetRangeStartInternal();
  }
  const std::optional<TimelineOffset>& RangeEnd() const {
    return animation->GetRangeEndInternal();
  }

  void Update(UpdatedCSSAnimation update) {
    DCHECK_EQ(update.animation, animation);
    style_rule = update.style_rule;
    style_rule_version = update.style_rule_version;
    play_state_list = update.play_state_list;
    specified_timing = update.specified_timing;
  }

  void Trace(Visitor* visitor) const {
    visitor->Trace(animation);
    visitor->Trace(style_rule);
  }

  Member<Animation> animation;
  AtomicString name;
  size_t name_index;
  Timing specified_timing;
  Member<StyleRuleKeyframes> style_rule;
  unsigned style_rule_version;
  Vector<EAnimPlayState> play_state_list;
};

Here we see that the class implements the GarbageCollected interface, and its Trace method triggers tracing of internal objects animation and style_rule.

Tracing JavaScript Objects.

Unlike C++ objects and the Oilpan system, there are no official publications about JavaScript objects. Therefore, it is common to mistakenly equate tracing of JavaScript objects with C++ objects. In reality, JavaScript objects are fully controlled by the V8 engine and reside in a dedicated V8 heap. This means there is no need for an additional externally managed API implementation. Each JavaScript object extend the HeadObject class, which has Iterate, IterateFast, IterateBody, and IterateBodyFast methods. The heap itself has a Visit method that initiates tracing through objects in this heap (at the time of writing the article, in V8 version 12.4.147).

src/objects/heap-object.h#204

// HeapObject is the superclass for all classes describing heap allocated
// objects.
class HeapObject : public TaggedImpl<HeapObjectReferenceType::STRONG, Address> {
 public:
  
  ...
  
  // Iterates over pointers contained in the object (including the Map).
  // If it's not performance critical iteration use the non-templatized
  // version.
  void Iterate(PtrComprCageBase cage_base, ObjectVisitor* v);

  template <typename ObjectVisitor>
  inline void IterateFast(PtrComprCageBase cage_base, ObjectVisitor* v);

  template <typename ObjectVisitor>
  inline void IterateFast(Tagged<Map> map, ObjectVisitor* v);

  template <typename ObjectVisitor>
  inline void IterateFast(Tagged<Map> map, int object_size, ObjectVisitor* v);

  // Iterates over all pointers contained in the object except the
  // first map pointer.  The object type is given in the first
  // parameter. This function does not access the map pointer in the
  // object, and so is safe to call while the map pointer is modified.
  // If it's not performance critical iteration use the non-templatized
  // version.
  void IterateBody(PtrComprCageBase cage_base, ObjectVisitor* v);
  void IterateBody(Tagged<Map> map, int object_size, ObjectVisitor* v);

  template <typename ObjectVisitor>
  inline void IterateBodyFast(PtrComprCageBase cage_base, ObjectVisitor* v);

  template <typename ObjectVisitor>
  inline void IterateBodyFast(Tagged<Map> map, int object_size,
                            ObjectVisitor* v);
  
  ...
}

Generations of Garbage Collection

The procedure of finding dead objects and cleaning them up can be quite slow. In modern applications, memory can contain thousands of objects, with sizes exceeding 1 Gb. When it comes to C++ object collection, work can be offloaded to separate threads and executed on-demand. However, when we talk about JavaScript, being single-threaded and without a mechanism for synchronization between threads, performing a full object tracing on a regular basis will likely lead to delays and reduced performance. From this point on, we will discuss the implementation of garbage collection specifically for JavaScript objects.

To avoid system overload and conduct the garbage collection process unnoticed by the user, the V8 team decided to break down the process into parts and work on each of them separately.

There is a hypothesis called the infant mortality or generational hypothesis, according to which, in most cases, young objects are more likely to die sooner than old ones.

Thus, in V8, the concept of generation was introduced. There are the young generation and the old generation.

The heap is conventionally divided into small young generations (up to 16 Mb), where all newly allocated objects are placed. The old generation is intended for old objects and can be up to 1.4 Gb in size.

Additionally, both generations are organized into so-called pages of 1 Mb each. Objects larger than 600 Kb are placed in separate pages and considered part of the old generation.

The old generation also includes code space with all executable code objects and map space with involved hidden classes.

Semi-space Objects Allocation in Young Generation

To move forward and start understanding the process of removing objects from memory, let's first grasp how these objects are stored in memory.

I have already mentioned that JavaScript operates in a single thread. It does not require synchronization, and each JavaScript context gets its own personal heap. The entire subsequent algorithm will be built based on these facts and the need to fit all processes into a single thread.

So, the young generation is divided into two semi-spaces, active and inactive. All new objects are initially placed in the current active semi-space using the bump-pointer method.

The method involves always having a pointer in the heap to the current free area. When creating a new object, this pointer will be the beginning of the object. The end of the object is determined simply by calculating its size. Having determined the size and, consequently, the end of the object, the pointer is shifted to the next free address.

Once the semi-space is fully occupied, the Scavenger mechanism kicks in. Its task is to go through the live objects and move them to the new, inactive semi-space. This operation is called Minor Garbage Collection.

After that, the two semi-spaces swap places. The current active semi-space becomes inactive, and the inactive one is cleared and becomes active. Therefore, starting from the second iteration, there might still be references to live objects in the inactive semi-space. During the next execution of Minor Garbage Collection, if the objects have already been transferred to the second semi-space once, they are considered old and moved to the old generation, while the dead ones are deleted.

The duration of Minor Garbage Collection depends on the number of live objects in the young generation. If all objects are dead, the process will take less than 1 ms. However, if all or most objects are alive, it will take significantly longer.

Old generation

The old generation also uses the bump-pointer method for objects allocation, with pointers stored in separate summary tables, similar to what I mentioned at the beginning of the article.

This generation is cleaned up by another process called Major Garbage Collection when the size of live objects in the old generation exceeds a heuristically calculated limit.

To reduce latency and memory consumption, the old generation uses the mark-sweep-compactor method. The delay during marking depends on the number of live objects that need to be marked. Marking the entire heap can take up to 100 ms for large web pages. To prevent this, V8 marks objects in small portions so that each step does not exceed 5 ms.

The scheme itself is called the tricolor marking scheme. More detailed information on the marking process can be found in the post Concurrent marking in V8 in the V8 blog. Again, retelling the entire post is meaningless. I will outline the general essence of the process. Each object is in one of three statuses, symbolically indicated by colors. In reality, the object's status is a 2-bit field, where:

00 - white - the initial status of all new objects. It means that the object has not been detected by the garbage collector yet.
01 - gray - the object transitions to this status as soon as the collector reaches it. Such an object is placed on the list for further tracing.
11 - black - the final status, indicating that the collector has visited all child nodes of the object, and it can be removed from the tracing list.

This scheme allows marking tasks to be queued in parts without blocking the main thread for a long time. The process will be completed when the list of objects for tracing becomes empty.

However, there is one problem here. Between marking steps, JavaScript code is executed, which can add new objects or remove old ones. This makes the status of already marked objects irrelevant. To solve this problem, the engine must notify the collector of all changes in the objects tree. This is done through a so-called write barrier. An example of implementing such a barrier is provided in the V8 blog.

// Called after `object.field = value`.
write_barrier(object, field_offset, value) {
  if (color(object) == black && color(value) == white) {
    set_color(value, grey);
    marking_worklist.push(value);
  }
}

Every time a new object is added to an existing one, a barrier function is triggered which checks if the parent has already been marked. In case the child object is not associated with anything yet, the parent will be returned to the tracing list, and the object itself will immediately transition to the gray status.

This code is no longer relevant these days, of course. Barriers are much more complex and look somewhat different now, but the essence remains the same. There are various implementation options for different scenarios. For a more complete picture, I will provide a code of real V8 barrier.

src/heap/marking-barrier-inl.h#64

void MarkingBarrier::MarkValueShared(Tagged<HeapObject> value) {
  // Value is either in read-only space or shared heap.
  DCHECK(InAnySharedSpace(value));
  // We should only reach this on client isolates (= worker isolates).
  DCHECK(!is_shared_space_isolate_);
  DCHECK(shared_heap_worklist_.has_value());
  // Mark shared object and push it onto shared heap worklist.
  if (marking_state_.TryMark(value)) {
    shared_heap_worklist_->Push(value);
  }
}

void MarkingBarrier::MarkValueLocal(Tagged<HeapObject> value) {
  DCHECK(!InReadOnlySpace(value));
  if (is_minor()) {
    // We do not need to insert into RememberedSet<OLD_TO_NEW> here because the
    // C++ marking barrier already does this for us.
    // TODO(v8:13012): Consider updating C++ barriers to respect
    // POINTERS_TO_HERE_ARE_INTERESTING and POINTERS_FROM_HERE_ARE_INTERESTING
    // page flags and make the following branch a DCHECK.
    if (Heap::InYoungGeneration(value)) {
      WhiteToGreyAndPush(value);  // NEW->NEW
    }
  } else {
    if (WhiteToGreyAndPush(value)) {
      if (V8_UNLIKELY(v8_flags.track_retaining_path)) {
        heap_->AddRetainingRoot(Root::kWriteBarrier, value);
      }
    }
  }
}

...

bool MarkingBarrier::WhiteToGreyAndPush(Tagged<HeapObject> obj) {
  if (marking_state_.TryMark(obj)) {
    current_worklist_->Push(obj);
    return true;
  }
  return false;
}

After the entire object graph has been marked, those objects reached by the garbage collector are marked with a black status. All others remain white. As with Minor Garbage Collection, live objects are moved to a new semi-space or a new old generation page.

The duration of Major Garbage Collection is linear and depends on the number of live objects in the old generation. Using an incremental garbage collection algorithm, V8 tries to keep the Major Garbage Collection execution time within 6 ms.

Page fragmentation

After marking, the collector can assess the level of fragmentation of the page. Empty areas appear between live objects after cleaning. Depending on which and how many objects are cleared, the final page can end up with different level of fragmentation.

The examples of highly fragmented (left) and lowly fragmented (right) pages are shown in the image above. The V8 engine evaluates the degree of fragmentation and decides what to do next with the page.

Compaction

In case of high fragmentation, the collector copies live objects to another page that has not yet been compacted, concurrently shifting them, getting rid of empty areas. This process is called compaction. As a result, a defragmented memory area with live objects is obtained. Dead objects are cleared along with the old semi-space. However, there are often many long-living objects in memory. Compacting each page may be too costly. Therefore, in the case of low fragmentation, the collector takes a different path.

Sweeping

With low fragmentation, relatively large areas remain between live objects. Instead of copying and rearranging objects, the scheduler simply puts addresses of merged dead regions into a special free-list. Later, when the engine needs to allocate space for a new object in memory, it first checks the free-list, and if there is a suitable space, it will place the new object there. This process is called sweeping.

Idle Tasks Scheduling

In the article Chromium. Web page rendering using Blink, CC and scheduler, I have described in detail the process of rendering web pages and task scheduling. Let's briefly recall what was discussed.

The Blink engine initiates the CC process in a separate compositor thread. CC receives signals from various Chromium systems and decides when and what to display on the screen. For instance, when an animation or scrolling is initiated, CC sends a signal to the main thread indicating the start of a new frame. Along with this signal, a deadline is passed – the time by which the frame must be generated. Since Chromium aims to maintain a frame rate of around 60 FPS, each frame lasts approximately 16.6 ms (1000/60). Blink has exactly this amount of time to sequentially perform tasks like processing user input, executing JavaScript code, handling other priority tasks, and updating the RenderTree. If Blink exceeds the specified time, the frame will be delayed, impacting the visual user experience (resulting in animation stuttering, flickering, etc.). However, in many cases, the engine requires much less time. With a small number of tasks, Chromium can handle a frame in less than 1 ms.

The remaining unused time is called idle time. However, idle time is not really idle. It is a task, just like the other tasks in the queue, but with a low priority. The duration of this task is equal to the time remaining until the next frame is formed. If there is no next frame expected, idle time is set to 50 ms. This number was chosen based on research showing that a user perceives a response to user input within 100 ms as instantaneous. If no new frames appear after 50 ms, a new idle time is queued and so on. However, if a signal is received to start a new frame, idle time will be interrupted without waiting for the time to end.

When idle time starts, tasks from a special low-priority queue can begin to be executed. These tasks are called idle tasks. To avoid exceeding the deadline, the end time of the idle time is being sent to the task. The responsibility of the task itself is to be completed by the specified deadline. The task can perform part of the work within the allotted time, and the remaining part can be queued as a new task. Similarly, if a task cannot complete any significant work within the specified time, it should reposition itself in the queue as a new task.

Idle tasks are not only the prerogative of the V8 engine. This mechanism is also available to web developers. Web browsers provide a method through the Web API - requestIdleCallback, which queues a task in the idle tasks. However, at the time of writing this article, the method is still in the process of development and is not supported by the Safari browser.

Idle Time Garbage Collection Scheduling

Earlier, we talked about how the garbage collection process can be quite intensive. In order not to block the system with this utility operation, V8 breaks down the entire process into small steps, with each step potentially taking up to 5 ms of CPU time. To make the process as unobtrusive as possible for the rest of the system, V8 queues garbage collection tasks specifically as idle tasks.

Minor Garbage Collection cannot be broken into parts and must be completed in a single try.

Major Garbage Collection consists of three parts:

Start of the incremental marking
Multiple marking steps
Finalization

Each of the phases has its own metrics for latency and memory impact. While the start of incremental marking phase itself is a fast operation, it leads to multiple marking steps and finalization, which can cause long pauses. Therefore, the start of marking can lead to worsened latency but has a significant impact on memory consumption metrics.

Launching Minor Garbage Collection reduces latency but has a relatively minor impact on memory consumption. However, regular execution of Minor Garbage Collection helps prevent objects from entering the phase of conservative garbage collection, which is performed during non-idle time. Conservative garbage collection can be initiated in critical situations, such as when a lack of allocated memory is detected.

Therefore, the scheduler should balance between starting too early (resulting in prematurely promoting objects to the old generation) and starting too late, which can lead to the young generation size growing excessively.

Minor Garbage Collection Idle Time Scheduling

In order to implement idle time Minor Garbage Collection the following is needed:

a predicate that tells whether to perform Minor Garbage Collection or not, given the idle task’s deadline and the state of the new generation
a mechanism to post an idle task on the Blink scheduler that performs a Minor Garbage Collection at an appropriate time

V8 performs idle time Minor Garbage Collection only if its estimated time fits within the given idle task’s deadline and there are enough objects allocated in the young generation.

Let H be the total size in bytes of objects in the young generation.

S' be the average speed of previously observed mi- nor garbage collection in bytes per second

T be the current idle task deadline in seconds

T' be the average idle task deadline in seconds

V8 performs Minor Garbage Collection if:

max(T' * S' - N, Hmin) < H <= S' * T

where, N is the estimated number of bytes that will be allocated before the next idle task

Hmin is the minimum young generation size that warrants garbage collection.

The (T' * S' - N) < H condition can be rewritten as (T' * S') < (H + N), чwhich estimates if the next idle time Minor Garbage Collection would overrun the average idle task deadline. If it does then V8 needs to perform idle time Minor Garbage Collection in the current idle task. If not, in the young generation there is no enough objects for effective work.

In order to request idle time for Minor Garbage Collection from the Blink scheduler, V8 puts allocation bailout markers at every N bytes of the new generation. When an allocation from the JavaScript code crosses an allocation bailout marker, the allocation takes the slow path and invokes a V8 runtime function that posts an idle task to the Blink scheduler.

Through experimentation, it has been established that setting N = 512 Kb is sufficient to maintain throughput without compromising performance significantly. This value is low enough to enable V8 to have several opportunities to schedule idle tasks.

Major Garbage Collection Idle Time Scheduling

The process of launching the incremental marking will be discussed in more detail later. For now, let's assume that it is already running. Immediately upon initialization, V8 inserts an idle task into the Blink scheduler. This task directly handles the marking process.

Based on the average marking speed, the idle task aims to achieve the maximum amount of work possible during the current idle period.

Let Tidle be the deadline in seconds of the idle task,

M be the mark- ing speed in byte per second.

Then,

Tidle * M is a number of bytes will be marked in the idle task.

The idle task iteratively requeues itself until the entire heap is marked. Afterward, V8 schedules the task to finalize Major Garbage Collection. The finalization process will be executed if the estimated time for this task meets the deadline. V8 determines the finalization time based on the speed of previous finalizations.

Memory Reducer

Memory reducer is a controller for scheduling Major Garbage Collections which tries to reclaim memory for inactive webpages during idle time.

The Major Garbage Collector starts working when the heap reaches a certain predefined size. This size is calculated and set at the end of the previous Major Garbage Collection based on the heap growing factor f and the total size of live objects in the old generation.

limit' = f * size

The next Major Garbage Collection is queued when the number of bytes allocated since the previous collection exceeds this threshold limit.

Everything is fine as long as the web page steadily allocates memory. However, if the web page becomes idle, memory allocation stops, and thus, the set limit will not be reached, and Major Garbage Collection will not be triggered.

Often, many web pages demonstrate high memory allocation intensity at the moment of loading because they initialize their internal data structures. A few seconds or minutes after loading, the web page often becomes inactive, holding a large number of unnecessary objects in memory. This can lead to a decrease in memory allocation speed and, consequently, a decrease in the speed of executing JavaScript code.

The diagram above shows an example of Major Garbage Collection scheduling. The first collection occurs at time t1, as the heap size limit is reached. V8 sets a new limit based on the heap growing coefficient and the heap size. The next call for Major Garbage Collection will happen at time t2 when the new limit is reached, then at time t3, and so on. The dotted line represents the heap size without using of the memory reducer.

In this way, the memory reducer can trigger Major Garbage Collection without waiting for the allocation limit to be reached. However, uncontrolled reduction of the limit can lead to deteriorating latency performance. Therefore, the V8 team has developed a heuristic method that relies not only on the idle time provided by the Blink scheduler between frames but also on whether the page is currently inactive. The indicators of page activity are the JavaScript allocation speed and the rate of JavaScript calls from the browser. When both speeds drop below a specified threshold, the page is considered inactive.

The diagram illustrates the states and transitions of the memory reducer. In the done state, the controller waits for a signal indicating that a sufficient number of allocations have been made to guarantee the initiation of garbage collection. At this point, a so-called non-idle Major Garbage Collection is triggered upon reaching the allocation limit, signaling a transition to the wait(i) state. In this state, the controller waits for the web page to become inactive. Once this happens, the incremental marking process is initiated, transitioning to the run(i) state until the Major Garbage Collection completes its operation. If subsequent calculations suggest that another Major Garbage Collection could likely free up more memory, the controller moves to the wait(i+1) state. Otherwise, it returns to the initial done state.

The key part of the controller is a well-tuned allocation rate threshold. Initially, this threshold was of a fixed value. Overall, this approach worked well on desktop devices. However, on slower systems, such as mobile devices, it did not work. Therefore, developers had to implement dynamic adaptation for different hardware configurations.

Let g is the Major Garbage Collection speed,

a is the allocation rate.

Then,

μ = g/(g+a)

This ratio μ can be thought of as the mutator utilization for the time window from now until the next Major Garbage Collection, under the assumption that the current allocation rate stays constant and the heap is currently empty:

Tmu = limit/a               (mutator time)

  Tgc = limit/g             (GC time)
  
    μ = Tmu /(Tmu + Tgc )   (mutator utilization)
    
      = (limit /a)/(limit /a + limit /g)
      
      = g/(g + a)

This gives us the condition for inactive allocation rate: μ ≥ μinactive , where μinactive is a fixed constant.

In V8 code, µinactive has a value of 0.993.

bool Heap::HasLowOldGenerationAllocationRate() {
  double mu = ComputeMutatorUtilization(
      "Old generation",
      tracer()->OldGenerationAllocationThroughputInBytesPerMillisecond(),
      tracer()->CombinedMarkCompactSpeedInBytesPerMillisecond());
  const double kHighMutatorUtilization = 0.993;
  return mu > kHighMutatorUtilization;
}

My telegram channels:

EN - https://t.me/frontend_almanac
RU - https://t.me/frontend_almanac_ru

Русская версия: https://blog.frontend-almanac.ru/v8-garbage-collection

Chromium. Web page rendering using Blink, CC and scheduler

2024-02-27T22:29:51.055Z

The Chromium engine from Google consists of a vast number of internal mechanisms, subsystems, and other engines. In this article, we will delve into the process of composing and rendering web pages directly on the screen, as well as get a little closer acquainted with the Blink engine, the composer (or, as it is also called, the content collator), and the task scheduler.

Web Page Parsing

First of all, let's remember how the rendering of a web page actually happens.

After receiving the HTML document, the browser parses it. Since HTML was originally developed to be compatible with the traditional XML structure, there are no interesting features for us at this stage. As a result of parsing, the browser obtains a hierarchical tree of objects - the DOM (Document Object Model).

As the browser goes through the structure of the HTML and parses it into the DOM, it encounters elements such as styles and JS scripts (both inline and as remote resources). Such elements require additional processing. JS script is parsed by the JavaScript engine into an AST structure and then is laid out in memory in the form of internal objects of the engine itself. Styles, on the other hand, are arranged into a cascading CSSOM tree. Inline styles of elements will also be added to this tree.

Having obtained the DOM and CSSOM, the browser now has the possibility to perform all the necessary calculations for the positioning and display of elements and, as a result, to construct a single Render Tree, based on which the graphics will be rendered directly on the screen.

Web Page Rendering

At present, most browsers are multi-threaded, and browsers based on the Chromium engine are no exception.

Blink

A separate system called Blink is responsible for all content rendering in the browser tab. Overall, Blink is a large and complex engine that includes functions such as implementing the HTML specification in terms of DOM, CSS, and Web IDL, integrating the V8 engine and running JavaScript code, rendering graphics on the screen (via the Skia engine), requesting network resources, handling input operations, building trees (DOM, CSSOM, Render Tree), calculating styles and positioning, and much more, including the Chrome Compositor (CC).

The engine itself is not a standalone "out-of-the-box" solution and cannot be launched independently. It is a kind of fork of the WebCore component of the WebKit engine.

Blink is used in platforms such as Chromium, Android WebView, Opera, Microsoft Edge, and many other Chromium-based browsers.

Chrome Compositor (CC)

In the Chromium codebase, this mechanism is located in the cc/ directory. Historically, the abbreviation "CC" is interpreted as Chrome Compositor, although as of today, it does not function as a compositor itself. Dana Jensens (danakj) even proposed an alternative name - Content Collator.

The CC is launched by the Blink engine and can operate in both single-threaded and multi-threaded modes. The operation of the CC requires a separate article; we will not delve into all the mechanics of the system here. Let's just note that the main entities operated by the CC are layers and layer trees. These entities are available from the CC as an API. Layers can be of various types, such as picture layers, texture layers, surface layers, and more. The task of the CC client (in our case, Blink serves as the client for the CC) is to construct its layer tree (LayerTreeHost) and inform the CC that it is ready and can be rendered. This approach allows the process of generating the final composition to be atomic.

Fundamental Rendering Scheme

The Chromium is a multi-threaded engine. For many specific rendering operations, separate threads are allocated. The basic threads, can be considered the main thread and the compositor thread.

The main thread is the general thread in which Blink operates. It is here that the final RenderTree and LayerTreeHost are composed. Grouped input operations are also processed here, and JavaScript code is executed. After all necessary operations and calculations, Blink notifies the CC that the trees are ready for rendering.

The compositor thread is responsible for the operation of the CC, i.e. for the scheduling of the rendering tasks and direct drawing on a screen.

Blink strives to display graphics at a rate of 60 FPS (60 frames per second), i.e., one frame should be output to the screen in approximately 16.6 ms. This frame rate is considered optimal for human perception. A lower frequency can lead to junking, juddering, and jittering.

The simplified rendering scheme is shown in the diagram above. As I mentioned earlier, the CC runs in a separate thread. At a certain point, it decides that it's time to initiate frame rendering. The CC signals the main thread to start a new frame. Blink receives the signal in the main thread and performs necessary scheduled operations, such as batch processing of input, execution of JavaScript code (or more precisely, JavaScript tasks from the Event Loop), and updating the RenderTree. Once the RenderTree is ready, the engine makes corresponding changes in the LayerTreeHost (in its temporary copy) and sends a commit signal to the CC, where it retrieves all calculations and sends tasks to draw graphics on the final device using the APIs of the respective OS graphics libraries, such as OpenGL and DirectX.

This entire process is given a time window of 1000/60 = ~16.6 ms. If the engine cannot complete all necessary operations within this time, the frame will be delayed, resulting in a decrease in the frame rate. Therefore, a crucial task for Blink is to calculate and predict the execution time of upcoming tasks. Knowing how long a particular operation will take, the engine can only work on what it can accomplish within the allocated time, deferring the rest of the operations until later.

There are also operations that do not involve specific calculations and do not use JavaScript, such as scrolling. CC can perform such operations independently in its own thread, thereby not blocking the main thread. Conversely, for example, animations require intensive calculations on the main thread throughout a large number of frames. If the main thread is occupied with other high-priority tasks, a portion of the animation operations may be postponed or delayed.

Task Scheduler

The task scheduler is designed to minimize the likelihood of delays in updating the frame. It is launched in the main thread. Each task is placed by the engine mechanisms in one of the queues specific to that type of task. CC tasks go into their own queue, input processing operations go into their own queue, JavaScript code execution goes into its own queue, and processes for loading the page go into their own queue.

Tasks within a queue are executed in the order in which they are placed there (remember the Event Loop). However, the scheduler, which is free to dynamically choose from which queue to execute the next task, chooses the priority of the queue according to its own discretion. When and which priority to set, the scheduler decides based on signals received from multiple different systems. For example, if a page is still loading, network requests and HTML parsing will be given priority. And if a touch event is detected, the scheduler will temporarily increase the priority of input operations for the next 100 ms to correctly recognize possible gestures. It is assumed that during this time interval, the next possible events might include scrolling, tapping, zooming, etc.

Having full information about the queues and tasks in them, as well as signals from other components, the scheduler can calculate the approximate idle time of the system. Just above, we considered an example of frame rendering. Along with the signal from CC about the start of frame rendering, the estimated time of the next frame is also sent, if the frame is available (+16.6ms). Knowing if the operations necessary for rendering the frame, input processing, and the JavaScript code to be executed are available, the scheduler can estimate the duration of these tasks. And knowing the time of the next frame, it can also calculate the time of the idle time. In fact, this period is not exactly idle. It can be used to perform a number of low-priority tasks (idle tasks). These tasks are placed in their own queue and executed in portions only after other queues have emptied, and within a limited period of time. In particular, the garbage collector actively utilizes this queue. This is where most of the work on marking dead objects and memory defragmentation takes place. The conservative garbage collection is only triggered with high priority in extreme cases, such as when memory shortage is detected. We will discuss this in more detail in the article Garbage Collection in V8.

Frame Rate Regularity

I have already mentioned that Chromium aims to achieve a frame rate of 60 FPS. In order to achieve this goal, the engine is equipped with a scheduler, CC, and many other systems. However, in practice, achieving perfect regularity is almost impossible, as there can be a large number of unforeseen situations that can affect the process, both internal (one or more tasks may take longer to complete than estimated by the scheduler) and external (for example, CPU or GPU load from other processes).

This is approximately what the scrolling of the page https://www.google.com/chrome looks like in the tracer. Not all animation frames were able to fit into the allocated window of 16.6 ms.

Furthermore, in addition to delays in rendering, some frames may be rejected by the Blink engine itself. This often happens, for example, during animation. There are many reasons for dropping animation frames. Blink supposes about twenty such reasons (at the time of writing this article, the Chromium version was 124.0.6326.0).

/third_party/blink/renderer/core/animation/compositor_animations.h#65

enum FailureReason : uint32_t {
  kNoFailure = 0,
  
  // Cases where the compositing is disabled by an exterior cause.
  kAcceleratedAnimationsDisabled = 1 << 0,
  kEffectSuppressedByDevtools = 1 << 1,
  
  // There are many cases where an animation may not be valid (e.g. it is not
  // playing, or has no effect, etc). In these cases we would never composite
  // it in any world, so we lump them together.
  kInvalidAnimationOrEffect = 1 << 2,
  
  // The compositor is not able to support all setups of timing values; see
  // CompositorAnimations::ConvertTimingForCompositor.
  kEffectHasUnsupportedTimingParameters = 1 << 3,
  
  // Currently the compositor does not support any composite mode other than
  // 'replace'.
  kEffectHasNonReplaceCompositeMode = 1 << 4,
  
  // Cases where the target element isn't in a valid compositing state.
  kTargetHasInvalidCompositingState = 1 << 5,
  
  // Cases where the target is invalid (but that we could feasibly address).
  kTargetHasIncompatibleAnimations = 1 << 6,
  kTargetHasCSSOffset = 1 << 7,
  
  // This failure reason is no longer used, as multiple transform-related
  // animations are allowed on the same target provided they target different
  // transform properties (e.g. rotate vs scale).
  kObsoleteTargetHasMultipleTransformProperties = 1 << 8,
  
  // Cases relating to the properties being animated.
  kAnimationAffectsNonCSSProperties = 1 << 9,
  kTransformRelatedPropertyCannotBeAcceleratedOnTarget = 1 << 10,
  kFilterRelatedPropertyMayMovePixels = 1 << 12,
  kUnsupportedCSSProperty = 1 << 13,
  
  // This failure reason is no longer used, as multiple transform-related
  // animations are allowed on the same target provided they target different
  // transform properties (e.g. rotate vs scale).
  kObsoleteMultipleTransformAnimationsOnSameTarget = 1 << 14,
  
  kMixedKeyframeValueTypes = 1 << 15,
  
  // Cases where the scroll timeline source is not composited.
  kTimelineSourceHasInvalidCompositingState = 1 << 16,
  
  // Cases where there is an animation of compositor properties but they have
  // been optimized out so the animation of those properties has no effect.
  kCompositorPropertyAnimationsHaveNoEffect = 1 << 17,
  
  // Cases where we are animating a property that is marked important.
  kAffectsImportantProperty = 1 << 18,
  
  kSVGTargetHasIndependentTransformProperty = 1 << 19,
  
  // When adding new values, update the count below *and* add a description
  // of the value to CompositorAnimationsFailureReason in
  // tools/metrics/histograms/enums.xml .
  // The maximum number of flags in this enum (excluding itself). New flags
  // should increment this number but it should never be decremented because
  // the values are used in UMA histograms. It should also be noted that it
  // excludes the kNoFailure value.
  kFailureReasonCount = 20,
};

From the entire set, the most common causes are the absence of a visual animation effect (kCompositorPropertyAnimationsHaveNoEffect), when the result of the animation does not lead to changes in the graphics and therefore does not require redrawing.

Also, a frame reset can be caused by an unsupported CSS property (kUnsupportedCSSProperty). This can happen if the engine does not understand how to recalculate a certain property, even if the property itself looks perfectly valid.

<style>
  #block1 {
    animation: expand 1s linear infinite;
  }

  @keyframes expand {
    to {
      height: auto;
    }
  }
</style>

<div id="block1"></div>

In the example above, the engine does not know how to calculate the height of the block, as the final value is undefined and cannot be calculated during the animation stage. As a result, the engine will reset the first frame of the animation, and will not even attempt to calculate any further frames, since it makes no sense to do so.

In the tracer, in this case, we will find a record like this:

{"args":{"data":{"compositeFailed":8224,"unsupportedProperties":["height"]}},"cat":"blink.animations,...

All of this leads to the fact that the actual number of frames rendered per second may be less than 60.

Discrepancy as a Metric for Frame Rate Regularity

The regularity of frame rendering is important in animation-based applications, in addition to the average frame rate. If an application renders 60 (or close to it) frames per second, but the intervals between frames vary significantly, the user may experience junking, juddering, or jittering. There are numerous methods for evaluating this phenomenon, from simply measuring the longest frame to calculating the divergence in frame lengths. Each method has its advantages, but most only cover a range of cases and do not take into account the temporal order of frames. In particular, they cannot differentiate between situations where two dropped frames are close together and when they are far apart.

In response to this, Google developers proposed their own method for evaluating frame regularity. The method is based on the discrepancy in the sequence of frame durations, similar to the mathematical method of Monte Carlo integration.

The theoretical basis of the method was presented at the 37th annual ACM SIGPLAN conference in 2016.

The figure below shows an example of the discrepancy of frame regularity.

Each line represents a set of timestamps. The rendered frames are indicated by black dots, while the dropped frames are indicated by white dots. The distance between the dots is 1 VSYNC, which equals 16.6 ms for a 60 Hz refresh rate. The final discrepancies are calculated in terms of VSYNC intervals:

D(S1) = 1
D(S2) = 2
D(S3) = 2
D(S4) = 25/9
D(S5) = 3

In the perfect case (S1), the discrepancy is equal to the interval between frames (1 VSYNC). If one of the frames was dropped (S2), the discrepancy will be equal to the greatest distance between two rendered frames. In the case of S2, the greatest distance will be between points 2 and 3, equal to 2 VSYNC. The same applies if there are two dropped frames, but far apart from each other (S3). This is because the method aims to identify the worst-case performance, rather than the average, as reflected in the calculation formulas. Therefore, the method is combined with the average frame duration to differentiate a single dropped frame from a series of repeated dropouts (the last one is obviously worse). In case S4, we see two dropped frames that are close to each other. Such frames are considered as a single missed area, and the discrepancy here will be 25/9 (~2.7) VSYNC. The situation is even worse in case S5, as there were no rendered frames between the two dropped frames. The greatest distance between the rendered frames here will be between points 2 and 4, which equals 3 intervals (3 VSYNC).

My telegram channels:

EN - https://t.me/frontend_almanac
RU - https://t.me/frontend_almanac_ru

Русская версия: https://blog.frontend-almanac.ru/chromium-rendering

Iterators in JavaScript

2024-02-20T17:08:52.741Z

In this article, we will look at the mechanism of iterators. What they are, how to apply them and how to create your own.

Basic terms

To understand the iteration mechanism, let's take a look at the following interfaces.

interface Iterable {
  [Symbol.iterator]: () => Iterator;
}

interface Iterator {
  next: () => IteratorResult;
  
  return?: (value?: any) => IteratorResult;
  
  throw?: (exception?: any) => IteratorResult;
}

interface IteratorResult {
  done?: boolean;
  value?: any;
}

So, an object is considered iterable if it implements the Iterable interface. In other words, if it contains the [Symbol.iterator] method - a function that directly returns an iterator object.

An iterator is a ordinary object that contains a next() method. The other two methods in the Iterator interface are not mandatory. The next() method is required to return an IteratorResult object.

The essence of iterability is that such an object can be traversed with for..of and for..in loops.

for (const item of [1, 2, 3]) {
    console.log(item);
}
// 1
// 2
// 3

Built-in iterators

The iteration mechanism is one of the most widely used in JavaScript. The language is literally riddled with embedded iterable objects. These include: Array, TypedArray, Map, Set, WeakMap, WeakSet, String.

// Array
for (const item of new Array(1, 2, 3)) {
    console.log(item);
}
// 1
// 2
// 3

// TypedArray
for (const item of new Int8Array(3)) {
    console.log(item);
}
// 0
// 0
// 0

// Map
for (const item of new Map([[1, 'one'], [2, 'two'], [3, 'three']])) {
    console.log(item);
}
// [1, 'one']
// [2, 'two']
// [3, 'three']

// Set
for (const item of new Set([1, 2, 3])) {
    console.log(item);
}
// 1
// 2
// 3

// String
for (const item of "abc") {
    console.log(item);
}
// a
// b
// c

In addition to JavaScript, some Web API objects also implement the Iterable interface. For example, in the DOM standard, examples of such objects are NodeList and DOMTokenList.

// NodeList
for (const item of document.querySelectorAll("div")) {
    console.log(item);
}
// Node
// Node
// ...

// DOMTokenList
const block = document.createElement("div");
block.classList.add("classA", "classB")

for (const item of block.classList) {
    console.log(item)
}
// classA
// classB

Custom iterators

Other than built-in iterable objects, it is possible to create our own. To do this, it is sufficient to simply implement the Iterable interface, following the iteration protocol.

So, as mentioned earlier, an object is considered iterable if its prototype contains the method [Symbol.iterator](). Otherwise, if an attempt is made to iterate over such an object, an exception will be thrown.

const obj = {};

for (const item of obj) {
    console.log(item);
}

// Uncaught TypeError: obj is not iterable

Now let's add an iterator method to our object.

const obj = {
    [Symbol.iterator]: () => {},
};

for (const item of obj) {
    console.log(item);
}

// Uncaught TypeError: Result of the Symbol.iterator method is not an object

Now, formally, the object is considered iterable, but it still cannot be iterated over in its current state, as the iterator method does not return an object that implements the Iterator interface, as required by the protocol.

next()

According to the protocol, an iterator should be a simple object that contains at least one method, next(). The next() method may take arguments, but it's not strictly required. The ECMA-262 specification guarantees that all built-in consumers of iterable objects call this method without arguments. However, in rare cases, arguments may be useful when manually calling the iterator.

const obj = {
    [Symbol.iterator]: () => {
        return {
            next: () => {},
        };
    },
};

for (const item of obj) {
    console.log(item);
}

// Uncaught TypeError: Iterator result undefined is not an object

In the above example, we added the next() method, but this method still doesn't return the correct IteratorResult.

An IteratorResult is also a simple object with two properties, done and value.

The done property is a boolean and expresses the completion of the iteration process. In other words, as long as the object can be iterated further, its iterator returns done: false; once it reaches the last step of iteration, the iterator must return done: true, signaling the user of the iterable object (e.g., a loop) to end the process (exit the loop).

The value property is the actual value associated with a given step of iteration. There are no restrictions on the format of the returned value.

As I just mentioned, if the iterator returns done: true, the iteration will be considered complete, the next iteration will not occur, and therefore, there is no point in the value. Consequently, passing it together with done: true is not necessary in this case.

It is worth noting that the ECMA-262 specification has taken a very liberal approach to the issue of iterators. In fact, it is not mandatory to return either the done property or the value property. Default values are provided for both (false and undefined, respectively). In other words, in order for our iterable object to finally work, the iterator only needs to return an empty object.

const obj = {
    [Symbol.iterator]: () => {
        return {
            next: () => {
                return {}; // { done: false, value: undefined }
            },
        };
    },
};

for (const item of obj) {
    console.log(item);
}

// Caution!!! This code leads to an infinite loop

However, there is little benefit from such an iterator. Moreover, since the iterator will never return done: true, the entire code will go into an infinite loop.

So, let's describe a functional iterator according to all the rules.

const obj = {
    [Symbol.iterator]: () => {
        let i = 0;
        
        return {
            next: () => {
                return {
                    done: i >= 3,
                    value: i++,
                };
            },
        };
    },
};

for (const item of obj) {
    console.log(item);
}

// 0
// 1
// 2

In this example, we sequentially return the numbers 0, 1, 2. Exiting the loop is done when i === 3.

return()

In some cases, the iteration process can be forcibly stopped in one way or another from the outside. In this case, the user of the iterable object must call the return() iterator method, if it exists.

const obj = {
    [Symbol.iterator]: () => {
        let i = 0;
        
        return {
            next: () => {
                return {
                    done: i >= 3,
                    value: i++,
                };
            },
            
            return: () => {
                console.log("Return", i);
                return {
                    done: i >= 3,
                    value: i,
                }
            }
        };
    },
};

for (const item of obj) {
    console.log(item);
    
    if (item === 1) {
        break;
    }
}
// 0
// 1
// Return 2

Like the next() method, the return() method must return an IteratorResult object. This method is, in a way, a callback at the time of forced interruption of the iteration. It is assumed that specific operations necessary to complete the process can be performed here. For example, unbinding listeners or clearing memory.

throw()

This is another callback method similar to return(). Its essence is to allow the user of the iterable object to report a discovered error. There are no built-in JavaScript users that can invoke this method in any situation. However, this callback can be manually invoked.

The protocol allows passing an argument to the throw() method, which is suggested to be used as a reference to the exception, although formally there are no restrictions on the number or types of arguments.

When called, the throw() method should throw the passed exception to halt the further iteration process. Again, such behavior is recommended and anticipated, but not mandatory. The iterator's author has the right to define the further logic.

const obj = {
  [Symbol.iterator]: () => {
    let i = 0;
    
    return {
      next: () => {
        return {
          done: i >= 3,
          value: i++,
        };
      },
      
      throw: (exception) => {
        console.log("Thrown:", exception);
        
        if (exception) {
          throw exception;
        }
        
        return {
          done: true,
        };
      },
    };
  },
};

for (const item of obj) {
  console.log(item);
  
  if (item === 1) {
    obj[Symbol.iterator]().throw(`Reached ${item}`);
  }
}

// 0
// 1
// Thrown: Reached 1
// Uncaught Reached 1

Most often, the throw() method is used in asynchronous iterators in conjunction with generators. More on this later.

Performing the iterator manually

As it has already become clear, the main users of iterable objects are the constructs for..of and for..in. These built-in users independently implement the iteration protocol. However, sometimes there is a need to create your own user, or simply to manually iterate through the process. As we saw in the last example, the iterator can be accessed directly to iterate through the entire loop on its own.

const obj = {
  [Symbol.iterator]: () => {
    let i = 0;
    
    return {
      next: () => {
        return {
          done: i >= 5,
          value: i++,
        };
      },
      
      return: () => {
        return {
          done: true,
          value: i,
        };
      },
      
      throw: (exception) => {
        if (exception) {
          throw exception;
        }
        
        return {
          done: true,
        };
      },
    };
  },
};

// getting the iterator by calling the iterator method
const iterator = obj[Symbol.iterator]();

// first step of the iteration
let result = iterator.next();
console.log(result.value);

// the remaining steps will be called in a loop until
// the iterator returns `done: true`
while (!result.done) {
  const result = iterator.next();
  console.log(result.value);
  
  if (isSuccess(result.value)) {
    // if necessary, we can stop the iteration process
    iterator.return();
    break;
  }
  
  if (isFailed(result.value)) {
    // or throw an exception
    iterator.throw(new Error("failed"));
  }
}

Self-iterating objects

We have already acquainted ourselves with two concepts: iterable object (Iterable) and iterator (Iterator). So far, we have considered both entities separately. The following technique allows us to combine everything into a single self-iterating object.

const obj = {
  i: 0,
  
  [Symbol.iterator]() {
    return this;
  },
  
  next() {
    return {
      done: this.i >= 3,
      value: this.i++,
    };
  },
  
  return() {
    return {
      done: true,
      value: this.i,
    };
  },
  
  throw(exception) {
    if (exception) {
      throw exception;
    }
    
    return {
      done: true,
    };
  },
};

for (const item of obj) {
  console.log(item);
}

In this example, in the iterator method, we returned a reference to the iterable object as the iterator, so obj simultaneously serves as both the iterator and the iterable object.

A similar pattern might be seen in an iterable class.

class Obj {
  i = 0;
  
  [Symbol.iterator]() {
    return this;
  }
  
  next() {
    return {
      done: this.i >= 3,
      value: this.i++,
    };
  }
  
  return() {
    return {
      done: true,
      value: this.i,
    };
  }
  
  throw(exception) {
    if (exception) {
      throw exception;
    }
    
    return {
      done: true,
    };
  }
}

const obj = new Obj();

for (const item of obj) {
  console.log(item);
}

Asynchronous iterators

So far we've only been talking about synchronous iterators. In June 2018, the 9th edition of the ECMA-262 specification was published. This version introduced asynchronous iterators and the AsyncIterator protocol.

In essence, an asynchronous iterator differs little from a synchronous one. Let's take a look at the following interfaces.

interface AsyncIterable {
  [Symbol.asyncIterator]: () => AsyncIterator;
}

interface AsyncIterator {
  next: () => Promise<IteratorResult>;
  
  return?: (value?: any) => Promise<IteratorResult>;
  
  throw?: (exception?: any) => Promise<IteratorResult>;
}

So, the main difference between synchronous and asynchronous iterable objects is that an asynchronous object must have an iterator method [Symbol.asyncIterator] (instead of [Symbol.iterator] as in the case of a synchronous object). As for the return values of the next(), return(), and throw() methods, they are expected to be Promises.

Asynchronous iterators themselves wouldn't be as convenient to use if the specification didn't provide for a new structure - the asynchronous for..await..of loop.

const obj = {
  [Symbol.asyncIterator]: () => {
    let i = 0;
    
    return {
      next: () => {
        return Promise.resolve({
          done: i >= 3,
          value: i++,
        });
      },
      
      return: () => {
        return Promise.resolve({
          done: true,
          value: i,
        });
      },
      
      throw: (exception) => {
        if (exception) {
          return Promise.reject(exception);
        }
        
        return Promise.resolve({
          done: true,
        });
      },
    };
  },
};

(async () => {
  for await (const item of obj) {
    console.log(item);
    
    if (item === 1) {
      await obj[Symbol.asyncIterator]().throw(`Reached ${1}`);
    }
  }
})();

Asynchronous generators

One important addition in the 9th edition of ECMA-262 is the introduction of asynchronous generators closely related to asynchronous iterators.

A simple asynchronous generator may look as follows.

async function* gen() {
  yield 0;
  yield 1;
  yield 2;
}

(async () => {
  for await (const item of gen()) {
    console.log(item);
  }
})();

// 0
// 1
// 2

An asynchronous generator implements the AsyncIterator protocol, so we can use all available iterator methods manually.

async function* gen() {
  yield 0;
  yield 1;
  yield 2;
}

const iterator = gen();

(async () => {
  console.log(await iterator.next());
  console.log(await iterator.next());
  console.log(await iterator.next());
  console.log(await iterator.next());
})();

// {value: 0, done: false}
// {value: 1, done: false}
// {value: 2, done: false}
// {value: undefined, done: true}

This includes pausing the iteration process.

async function* gen() {
  yield 0;
  yield 1;
  yield 2;
}

const iterator = gen();

(async () => {
  console.log(await iterator.next());
  console.log(await iterator.return("My return reason"));
})();

// {value: 0, done: false}
// {value: 'My return reason', done: true}

Or throwing an exception

async function* gen() {
  yield 0;
  yield 1;
  yield 2;
}

const iterator = gen();

(async () => {
  console.log(await iterator.next());
  console.log(await iterator.throw("My error"));
})();

// {value: 0, done: false}
// Uncaught (in promise) My error

Async-from-Sync iterator

An Async-from-Sync iterator is an asynchronous iterator obtained from a synchronous one through the abstract operation CreateAsyncFromSyncIterator. I remind you that an abstract operation is an internal mechanism of the JavaScript language. Normally, such operations are not available within the execution context. However, for example, the V8 engine allows the use of these operations when the --allow-natives-syntax flag is enabled.

> v8-debug --allow-natives-syntax iterator.js

// iterator.js
const syncIterator = {
  [Symbol.iterator]() {
    return this;
  },
  
  next() {
    return {
      done: true,
      value: Promise.resolve(1),
    };
  },
};

const asyncIterator = %CreateAsyncFromSyncIterator(syncIterator);

console.log(asyncIterator);
// [object Async-from-Sync Iterator]

console.log(asyncIterator[Symbol.asyncIterator]);
// function [Symbol.asyncIterator]() { [native code] }

As we can see, this abstract operation converts a synchronous iterator to an asynchronous one. As I mentioned before, we cannot call an abstract operation in the normal execution context. The engine itself handles this where necessary. According to the specification, this is required in one specific case:

The current environment is asynchronous.
The iterable object does not have a [Symbol.asyncIterator] method.
The iterable object has a [Symbol.iterator] method.

Как мы можем видеть, эта абстрактная операция преобразует синхронный итератор в асинхронный. Как я уже говорил, в обычном исполняемом контексте мы не можем вызвать абстрактную операцию. Это делает сам движок в тех местах, где требуется. А требуется это, согласно спецификации, в одном конкретном случае:

Текущее окружение является асинхронным
Итерируемый объект не имеет метода [Symbol.asyncIterarot]
Итерируемый объект имеет метод [Symbol.iterator]

The easiest way to demonstrate this process is with generators.

function* syncGen() {
  yield 1;
  yield 2;
  yield Promise.resolve(3);
  yield Promise.resolve(4);
  yield 5;
}

for (const item of syncGen()) {
  console.log(item);
}

// 1
// 2
// Promise
// Promise
// 5

In this case, a synchronous generator will return unresolved promises at steps 3 and 4. However, an asynchronous user for..await..of can convert these steps into asynchronous ones.

function* syncGen() {
  yield 1;
  yield 2;
  yield Promise.resolve(3);
  yield Promise.resolve(4);
  yield 5;
}

(async () => {
  for await (const item of syncGen()) {
    console.log(item);
  }
})();

// 1
// 2
// 3
// 4
// 5

The same applies to regular synchronous iterators.

const syncIterator = {
  i: 0,
  
  [Symbol.iterator]() {
    return this;
  },
  
  next() {
    const done = this.i >= 3;

    if (this.i === 1) {
      return {
        done: false,
        value: Promise.resolve(this.i++),
      };
    }

    return {
      done,
      value: this.i++,
    };
  },
};

for (const item of syncIterator) {
  console.log(item);
}

// 0
// Promise
// 2

However, when an asynchronous user is applied, the second step will be transformed into an asynchronous one.

const syncIterator = {
  i: 0,
  
  [Symbol.iterator]() {
    return this;
  },
  
  next() {
    const done = this.i >= 3;

    if (this.i === 1) {
      return {
        done: false,
        value: Promise.resolve(this.i++),
      };
    }

    return {
      done,
      value: this.i++,
    };
  },
};

(async () => {
  for await (const item of syncIterator) {
    console.log(item);
  }
})();

// 0
// 1
// 2

My telegram channels:

EN - https://t.me/frontend_almanac
RU - https://t.me/frontend_almanac_ru

Русская версия: https://blog.frontend-almanac.ru/iterators