How to make a C++ class cycle collected

Should my class be cycle collected?

First, you need to decide if your class should be cycle collected. There are three main criteria:

It can be part of a cycle of strong references, including refcounted objects and JS. Usually, this happens when it can hold alive and be held alive by cycle collected objects or JS.
It must be refcounted.
It must be single threaded. The cycle collector can only work with objects that are used on a single thread. The main thread and DOM worker and worklet threads each have their own cycle collectors.

If your class meets the first criteria but not the second, then whatever class uniquely owns it should be cycle collected, assuming that is refcounted, and this class should be traversed and unlinked as part of that.

The cycle collector supports both nsISupports and non-nsISupports (known as “native” in CC nomenclature) refcounting. However, we do not support native cycle collection in the presence of inheritance, if two classes related by inheritance need different CC implementations. (This is because we use QueryInterface to find the right CC implementation for an object.)

Once you’ve decided to make a class cycle collected, there are a few things you need to add to your implementation:

Cycle collected refcounting. Special refcounting is needed so that the CC can tell when an object is created, used, or destroyed, so that it can determine if an object is potentially part of a garbage cycle.
Traversal. Once the CC has decided an object might be garbage, it needs to know what other cycle collected objects it holds strong references to. This is done with a “traverse” method.
Unlinking. Once the CC has decided that an object is garbage, it needs to break the cycles by clearing out all strong references to other cycle collected objects. This is done with an “unlink” method. This usually looks very similar to the traverse method.

The traverse and unlink methods, along with other methods needed for cycle collection, are defined on a special inner class object, called a “participant”, for performance reasons. The existence of the participant is mostly hidden behind macros so you shouldn’t need to worry about it.

Next, we’ll go over what the declaration and definition of these parts look like. (Spoiler: there are lots of ALL_CAPS macros.) This will mostly cover the most common variants. If you need something slightly different, you should look at the location of the declaration of the macros we mention here and see if the variants already exist.

Reference counting

nsISupports

If your class inherits from nsISupports, you’ll need to add NS_DECL_CYCLE_COLLECTING_ISUPPORTS to the class declaration. This will declare the QueryInterface (QI), AddRef and Release methods you need to implement nsISupports, as well as the actual refcount field.

In the .cpp file for your class you’ll have to define the QueryInterface, AddRef and Release methods. The ins and outs of defining the QI method is out-of-scope for this document, but you’ll need to use the special cycle collection variants of the macros, like NS_INTERFACE_MAP_BEGIN_CYCLE_COLLECTION. (This is because we use the nsISupports system to define a special interface used to dynamically find the correct CC participant for the object.)

Finally, you’ll have to actually define the AddRef and Release methods for your class. If your class is called MyClass, then you’d do this with the declarations NS_IMPL_CYCLE_COLLECTING_ADDREF(MyClass) and NS_IMPL_CYCLE_COLLECTING_RELEASE(MyClass).

non-nsISupports

If your class does not inherit from nsISupports, you’ll need to add NS_INLINE_DECL_CYCLE_COLLECTING_NATIVE_REFCOUNTING to the class declaration. This will give inline definitions for the AddRef and Release methods, as well as the actual refcount field.

Cycle collector participant

Next we need to declare and define the cycle collector participant. This is mostly boilerplate hidden behind macros, but you will need to specify which fields are to be traversed and unlinked because they are strong references to cycle collected objects.

Declaration

First, we need to add a declaration for the participant. As before, let’s say your class is MyClass.

The basic way to declare this for an nsISupports class is NS_DECL_CYCLE_COLLECTION_CLASS(MyClass).

If your class inherits from multiple classes that inherit from nsISupports classes, say Parent1 and Parent2, then you’ll need to use NS_DECL_CYCLE_COLLECTION_CLASS_AMBIGUOUS(MyClass, Parent1) to tell the CC to cast to nsISupports via Parent1. You probably want to pick the first class it inherits from. (The cycle collector needs to be able to cast MyClass* to nsISupports*.)

Another situation you might encounter is that your nsISupports class inherits from another cycle collected class CycleCollectedParent. In that case, your participant declaration will look like NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(MyClass, CycleCollectedParent). (This is needed so that the CC can cast from nsISupports down to MyClass.) Note that we do not support inheritance for non-nsISupports classes.

If your class is non-nsISupports, then you’ll need to use the NATIVE family of macros, like NS_DECL_CYCLE_COLLECTION_NATIVE_CLASS(MyClass).

In addition to these modifiers, these different variations have further SCRIPT_HOLDER variations which are needed if your class holds alive JavaScript objects. This is because the tracing of JS objects held alive by this class must be declared separately from the tracing of C++ objects held alive by this class so that the garbage collector can also use the tracing. For example, NS_DECL_CYCLE_COLLECTION_SCRIPT_HOLDER_CLASS_AMBIGUOUS(MyClass, Parent1).

There are also WRAPPERCACHE variants of the macros which you need to use if your class is wrapper cached. These are effectively a specialized form of SCRIPT_HOLDER, as a cached wrapper is a JS object held alive by the C++ object. For example, NS_DECL_CYCLE_COLLECTION_WRAPPERCACHE_CLASS_AMBIGUOUS(MyClass, Parent1).

There is yet another variant of these macros, SKIPPABLE. This document won’t go into detail here about how this works, but the basic idea is that a class can tell the CC when it is definitely alive, which lets the CC skip it. This is a very important optimization for things like DOM elements in active documents, but a new class you are making cycle collected is likely not common enough to worry about.

Implementation

Finally, you must write the actual implementation of the CC participant, in the .cpp file for your class. This will define the traverse and unlink methods, and some other random helper functions. In the simplest case, this can be done with a single macro like this: NS_IMPL_CYCLE_COLLECTION(MyClass, mField1, mField2, mField3), where mField1 and the rest are the names of the fields of your class that are strong references to cycle collected objects. There is some template magic that says how many common types like RefPtr, nsCOMPtr, and even some arrays, should be traversed and unlinked. There’s also a variant NS_IMPL_CYCLE_COLLECTION_INHERITED, which you should use when there’s a parent class that is also cycle collected, to ensure that fields of the parent class are traversed and unlinked. The name of that parent class is passed in as the second argument. If either of these work, then you are done. Your class is now cycle collected. Note that this does not work for fields that are JS objects.

However, if that doesn’t work, you’ll have to get into the details a bit more. A good place to start is by copying the definition of NS_IMPL_CYCLE_COLLECTION.

For a script holder method, you also need to define a trace method in addition to the traverse and unlink, using NS_IMPL_CYCLE_COLLECTION_TRACE_BEGIN and other similar macros. You’ll need to include all of the JS fields that your class holds alive. The trace method will be used by the GC as well as the CC, so if you miss something you can end up with use-after-free crashes. You’ll also need to call mozilla::HoldJSObjects(this); in the ctor for your class, and mozilla::DropJSObjects(this); in the dtor. This will register (and unregister) each instance of your object with the JS runtime, to ensure that it gets traced properly. This does not apply if you have a wrapper cached class that does not have any additional JS fields, as nsWrapperCache deals with all of that for you.