Qt Quick and QML

Since Qt 6.8, the V4 ECMAScript engine used in Qt (qtdeclarative) employs an incremental, precise mark-and-sweep garbage collection (GC) algorithm.

Key Characteristics

• Incremental: The collector and mutator (user application) run in the same thread, but the collector executes in chunks, pausing the mutator at specific intervals.
• Precise: The GC can accurately distinguish between pointers to heap objects and other pointer-sized values.
• Non-generational: It does not divide objects into generations based on survival.
• Non-moving: It does not relocate objects in memory.

Marking States

During the mark phase, every heap item exists in one of three states:

1. White (unvisited): The GC has not encountered this item.
2. Grey (seen): The item has been discovered, but its reachable children have not necessarily been visited. Grey items are tracked in a MarkStack.
3. Black (finished): The item and all its directly reachable children have been visited. Black items are tracked via a black-object bitmap.

Root Set

The GC starts its process from a set of 'roots', which include:

• Engine-global objects (JS globals).
• All strings and symbols in the identifier table.
• All actively linked compilation units.
• Values on the JS stack (treated as 'fast roots').
• Persistent Values: Everything stored in a QJSValue and all bound functions of QQmlBindings.
• QObjectWrappers: QObjects with C++ ownership, or those parented to/rooted in a QObject with C++ ownership.

When describing QML Elements in the MOC JSON, each class object contains metadata about its identity, location, and members.

Key fields include:

• className: The C++ class name (e.g., MyClass).
• qualifiedClassName: The fully-qualified C++ name (e.g., MyNamespace::MyClass).
• lineNumber: The line number where the class is defined (used by qmlls for navigation).
• object: true if the type is an object, false if it is a gadget or namespace.
• gadget: true if the type is a gadget, false if it is an object or namespace.
• namespace: true if the type is a namespace.
• superClasses: A list of base types. Note that multiple superclasses are not supported; use the interfaces field for multiple inheritance.
• interfaces: A list of interface names implemented by the type (corresponds to Q_INTERFACES or QML_IMPLEMENTS_INTERFACES in C++).

Members include:

• properties: A list of properties (see Property fields).
• enums: A list of enums (see Enum fields).
• methods, signals, slots, constructors: Lists of functional members (all share similar field structures).

{
    "classInfos": [
        {
            "name": "QML.Element",
            "value": "myGadget"
        }
    ],
    "className": "MyGadget",
    "gadget": true,
    "lineNumber": 6,
    "properties": [
        {
            "constant": false,
            "designable": true,
            "final": false,
            "index": 0,
            "lineNumber": 10,
            "member": "m_myInt",
            "name": "myInt",
            "required": false,
            "scriptable": true,
            "stored": true,
            "type": "int",
            "user": false
        }
    ],
    "qualifiedClassName": "MyGadget"
}

A PropertyPass runs whenever a property is read, written, or has a binding created. Because property access is more frequent than element instantiation, you should specify the target type and property name during registration to maintain performance.

Registration

You can omit the type name to target all properties with a specific name (e.g., width), or omit the property name to target all properties of a specific type.

Methods

• onBinding(element, propertyName, bindingScope, location, binding, value): Called when a binding is created. binding provides type information, and value is a QQmlSA::Element (useful for object bindings).
• onRead(element, propertyName, readScope, location): Called when a property is read (via binding or script).
• onWrite(element, propertyName, writeScope, location, value): Called when a property is written to. value contains the element or type information being written.

To support incremental collection, the V4 GC operates through a structured state machine. This allows the engine to pause and resume collection without stopping the entire application (Stop-The-World) for the entire duration.

GC Stages

1. Initialization: markStart (atomic) initializes the MarkStack and sets the incremental flag.
2. Global Marking: markGlobalObject (atomic) marks the global object, identifier table, and compilation units.
3. Stack Marking: markJSStack (atomic) marks the JS stack.
4. Persistent/Weak Value Marking:
   • initMarkPersistentValues (atomic) followed by markPersistentValues (interruptible).
   • initMarkWeakValues (atomic) followed by markWeakValues (interruptible).
5. Drain Phase: markDrain (interruptible) processes the MarkStack until empty.
6. Finalization & Cleanup:
   • initCallDestroyObjects (atomic) rescans the stack and drains the MarkStack to ensure all live objects are marked.
   • callDestroyObject (interruptible) calls destroyObject on non-marked QObjectWrappers.
   • freeWeakMaps / freeWeakSets (atomic) remove references to dead objects.
   • handleQObjectWrappers (atomic) clears pending references.
7. Sweep Phase: Multiple atomic phases perform the actual memory freeing across different allocators (identifier table, block allocator, huge item allocator, IC allocator). This phase also triggers destroy on objects marked with V4_NEEDS_DESTROY.
8. Completion: updateMetaData (atomic) updates bitmaps and statistics, marking the cycle as done.

To run qmllint without CMake, you must manually provide import paths and resource files so the tool can map source files to their build-time locations.

Key Flags:

• -I <path>: Add an import path. Use multiple -I flags for multiple paths.
• --resource <path>: Pass the .qrc files generated by the build system. This allows qmllint to map QML files from their build path back to their source paths.
• --bare: Disables automatic adding of the current directory, default import paths, and auto-discovery of qmldir files. Use this to ensure linting only uses the paths you explicitly provided.

Example Invocation: If Main.qml is part of MyModule and depends on a module in /path/to/build/:

qmllint \
    -I /path/to/build/ \
    -I /path/to/qt/qml \
    --resource /path/to/build/.qt/rcc/qmake_mymodule.qrc \
    --resource /path/to/build/.qt/rcc/appmymodule_raw_qml_0.qrc \
    --bare \
    /path/to/source/MyModule/Main.qml