Memory Management in the JavaScript Engine

Introduction

This document describes the dynamic memory management of the JavaScript Engine in QML. It is a rather technical, in depth description. You only need to read this if you care about the exact characteristics of JavaScript memory management in QML. In particular, it can be helpful if you're trying to optimize your application for maximum performance.

Basic Principles

The JavaScript engine in QML has a dedicated memory manager that requests address space in units of multiple pages from the operating system. Objects, strings, and other managed values created in JavaScript are then placed in this address space, using the JavaScript engine's own allocation scheme. The JavaScript engine does not use the C library's malloc() and free(), nor the default implementations of C++'s new and delete to allocate memory for JavaScript objects.

Requests for address space are generally done with mmap() on Unix-like systems and with VirtualAlloc() on windows. There are several platform-specific implementations of those primitives. Address space reserved this way is not immediately committed to physical memory. Rather, the operating system notices when a page of memory is actually accessed and only then commits it. Therefore, the address space is practically free and having a lot of it gives the JavaScript memory manager the leverage it needs to place objects in an efficient way on the JavaScript heap. Furthermore, there are platform-specific techniques to tell the operating system that a chunk of address space, though still reserved, does not have to be mapped into physical memory for the time being. The operating system can then decommit the memory as needed and use it for other tasks. Crucially, most operating systems do not guarantee immediate action on such a decommit request. They will only decommit the memory when it is actually needed for something else. On Unix-like systems we generally use madvise() for this. Windows has specific flags to VirtualFree() to do the equivalent.

All values stored on the JavaScript heap are subject to garbage collection. None of the values are immediately "deleted" when they go out of scope or are otherwise "dropped". Only the garbage collector may remove values from the JavaScript heap and return memory (see Garbage Collection below for how this works).

QObject-based Types

QObject-based types, and in particular everything you can phrase as a QML element, are allocated on the C++ heap. Only a small wrapper around the pointer is placed on the JavaScript heap when a QObject is accessed from JavaScript. Such a wrapper, however, can own the QObject it points to. See QJSEngine::ObjectOwnership. If the wrapper owns the object, it will be deleted when the wrapper is garbage-collected. You can then also manually trigger the deletion by calling the destroy() method on it. destroy() internally calls QObject::deleteLater(). It will therefore not immediately delete the object, but wait for the next event loop iteration.

QML-declared properties of objects are stored on the JavaScript heap. They live as long as the object they belong to lives. Afterwards they are removed the next time the garbage collector runs.

Object Allocation

In JavaScript, any structured type is an object. This includes function objects, arrays, regular expressions, date objects and much more. QML has a number of internal object types, such as the above mentioned QObject wrapper. Whenever an object is created, the memory manager locates some storage for it on the JavaScript heap.

JavaScript strings are also managed values, but their string data is not allocated on the JavaScript heap. Similar to QObject wrappers, the heap objects for strings are just thin wrappers around a pointer to string data.

When allocating memory for an object, the size of the object is first rounded up to 32 byte alignment. Each 32 byte piece of address space is called a "slot". For objects smaller than a "huge size" threshold, the memory manager performs a series of attempts to place the object in memory:

• The memory manager keeps linked lists of previously freed pieces of heap, called "bins". Each bin holds pieces of heap with a fixed per-bin size in slots. If the bin for the right size is not empty, it picks the first entry and places the object there.
• The memory that hasn't been used yet is managed via a bumper allocator. A bumper pointer points to the byte beyond the occupied address space. If there is still enough unused address space, the bumper is increased accordingly, and the object is placed in unused space.
• A separate bin is kept for previously freed pieces of heap of varying sizes larger than the specific sizes mentioned above. The memory manager traverses this list and tries to find a piece it can split to accommodate the new object.
• The memory manager searches the lists of specifically sized bins larger than the object to be allocated and tries to split one of those.
• Finally, if none of the above works, the memory manager reserves more address space and allocates the object using the bumper allocator.

Huge objects are handled by their own allocator. For each of those one or more separate memory pages are obtained from the OS and managed separately.

Additionally, each new chunk of address space the memory manager obtains from the OS gets a header that holds a number of flags for each slot:

• object: The first slot occupied by an object is flagged with this bit.
• extends: Any further slots occupied by an object are flagged with this bit.
• mark: When the garbage collector runs, it sets this bit if the object is still in use.

Internal Classes

In order to minimize the required storage for metadata on what members an object holds, the JavaScript engine assigns an "internal class" to each object. Other JavaScript engines call this "hidden class" or "shape". Internal classes are deduplicated and kept in a tree. If a property is added to an object, the children of the current internal class are checked to see if the same object layout has occurred before. If so, we can use the resulting internal class right away. Otherwise we have to create a new one.

Internal classes are stored in their own section of the JavaScript heap that otherwise works the same way as the general object allocation described above. This is because internal classes have to be kept alive while the objects using them are collected. Internal classes are then collected in a separate pass.

The actual property attributes stored in internal classes are not kept on the JavaScript heap, though, but rather managed using new and delete.

Garbage Collection

The garbage collector used in the JavaScript engine is a non-moving, stop-the-world Mark and Sweep design. In the mark phase we traverse all the known places where live references to objects can be found. In particular:

• JavaScript globals
• Undeletable parts of QML and JavaScript compilation units
• The JavaScript stack
• The persistent value storage. This is where QJSValue and similar classes keep references to JavaScript objects.

For any object found in those places the mark bits are set recursively for anything it references.

In the sweep phase the garbage collector then traverses the whole heap and frees any objects not marked before. The resulting released memory is sorted into the bins to be used for further allocations. If a chunk of address space is completely empty, it is decommitted, but the address space is retained (see Basic Principles above). If the memory usage grows again, the same address space is re-used.

The garbage collector is triggered either manually by calling the gc() function or by a heuristic that takes the following aspects into account:

• The amount of memory managed by object on the JavaScript heap, but not directly allocated on the JavaScript heap, such as strings and internal class member data. A dynamic threshold is maintained for those. If it is surpassed, the garbage collector runs and the threshold is increased. If the amount of managed external memory falls far below the threshold, the threshold is decreased.
• The total address space reserved. The internal memory allocation on the JavaScript heap is only considered after at least some address space has been reserved.
• The additional address space reservation since the last garbage collector run. If the amount of address space is more than double the amount of used memory after the last garbage collector run, we run the garbage collector again.

Analyzing Memory Usage

In order to observe the development of both the address space and the number of objects allocated in it, it is best to use a specialized tool. The QML Profiler provides a visualization that helps here. More generic tools cannot see what the JavaScript memory manager does within the address space it reserves and may not even notice that part of the address space is not committed to physical memory.

Another way to debug memory usage are the logging categories qt.qml.gc.statistics and qt.qml.gc.allocatorStats. If you enable the Debug level for qt.qml.gc.statistics, the garbage collector will print some information every time it runs:

• How much total address space is reserved
• How much memory was in use before and after the garbage collection
• How many objects of various sizes were allocated so far

The Debug level for qt.qml.gc.allocatorStats prints more detailed statistics that also include how the garbage collector was triggered, timings for the mark and sweep phases and a detailed breakdown of memory usage by bytes and chunks of address space.