Skip to main content

Module registry

Module registry 

Source
Expand description

The bridge’s object index and deletion policy.

Liveness is not held here: every attached object is kept alive by its proxy, so a Rust value lives exactly as long as its QObject, plus any user handles, which are plain Rc<RefCell<T>>s whose drops never tear anything down. The registry observes each object through a Weak reference and decides when the QObjects of Rust-created objects die.

Entries are grouped by their registration Owner:

  • Owner::RustRegistry: Rust-created. Pinned to CppOwnership while Rust holds a handle, so the QML engine cannot delete it. The engine keeps the JS wrapper of a CppOwnership object alive for the whole object lifetime. collect_garbage therefore hands ownership to the engine by setting JavaScriptOwnership for objects without Rust interest (strong count is down to the proxy’s own). The engine’s garbage collector deletes them with exact reachability and takes down the value together with the proxy. An object that re-enters Rust is changed back to CppOwnership. Objects that were never wrapped with a JS wrapper are deleted directly when Rust interest vanishes.
  • Owner::Engine: QML-created. The engine (or a parent) deletes the QObject; the registry never does, and the entry only serves the proxy lookup.

The CppOwnership flag guards only against the garbage collector: deletion paths that ignore the ownership flag (parents, components, engine death) can take a QObject of either kind. The registry entry is deleted together with the QObject but the Rust value then survives through user handles and gets a fresh QObject with Owner::RustRegistry attached on its next exposure.

collect_garbage is triggered by the garbage collection of the QmlEngine and under allocation pressure (see register). A garbage collection cannot be observed with e.g. connecting to a signal, so we use a sentinel that is injected into the QML engine and that should be deleted on the next garbage collector cycle.

Enums§

Owner
ownership indicator:

Functions§

attached_object_count
The number of objects with an attached QObject, including both registry-owned and engine-owned entries. Useful for leak checks.
collect_garbage
Frees every object that is neither referenced from Rust nor reachable from QML. Runs automatically after every garbage collection if using crate::QApp and under allocation pressure; call it explicitly for deterministic reclamation points.
install_gc_sentinel
Arms the automatic collection trigger on engine by creating a sentinel.
registry_owned_count
The number of objects the registry currently owns. Engine-owned objects are not included. Useful for leak checks.