Interactuar con el colector de ciclos de XPCOM

This is a quick overview of the cycle collector introduced into XPCOM for Firefox 3, including a description of the steps involved in modifying an existing C++ class to participate in XPCOM cycle collection. If you have a class that you think is involved in a cyclical-ownership leak, this page is for you.

The intended audience is Mozilla C++ developers.

What the cycle collector does

The cycle collector spends most of its time accumulating (and forgetting about) pointers to XPCOM objects that might be involved in garbage cycles. This is the idle stage of the collector's operation, in which special variants of nsAutoRefCnt register and unregister themselves very rapidly with the collector, as they pass through a "suspicious" refcount event (from N+1 to N, for nonzero N).

Periodically the collector wakes up and examines any suspicious pointers that have been sitting in its buffer for a while. This is the scanning stage of the collector's operation. In this stage the collector repeatedly asks each candidate for a singleton cycle-collection helper class, and if that helper exists, the collector asks the helper to describe the candidate's (owned) children. This way the collector builds a picture of the ownership subgraph reachable from suspicious objects.

If the collector finds a group of objects that all refer back to one another, and establishes that the objects' reference counts are all accounted for by internal pointers within the group, it considers that group cyclical garbage, which it then attempts to free. This is the unlinking stage of the collectors operation. In this stage the collector walks through the garbage objects it has found, again consulting with their helper objects, asking the helper objects to "unlink" each object from its immediate children.

Note that the collector also knows how to walk through the JS heap, and can locate ownership cycles that pass in and out of it.

How the collector can fail

The cycle collector is a conservative device. There are situations in which it will fail to collect a garbage cycle.

1. It does not suspect any pointers by default; objects must suspect themselves, typically by using an nsCycleCollectingAutoRefCnt rather than a nsAutoRefCnt.
2. It only traverses objects that return a helper object when QI'ed to nsICycleCollectionParticipant. If it encounters an unknown edge during its traversal, it gives up on that edge; this means that every edge involved in a cycle must be participating, otherwise the cycle will not be found.
3. The Traverse and Unlink methods on the helper object are not magic; they are programmer-supplied and must be correct, or else the collector will fail.
4. The collector does not know how to find temporary owning pointers that exist on the stack, so it is important that it only run from near the top-loop of the program. It will not crash if there are extra owning pointers, but it will find itself unable to account for the reference counts it finds in the owned objects, so may fail to collect cycles.

How to make your classes participate

The interface between the cycle collector and your classes can be accessed directly using the contents of xpcom/base/nsCycleCollector.h, but there are convenience macros for annotating your classes in xpcom/base/nsCycleCollectionParticipant.h that are much easier to use. In general, assuming you are modifying class nsFoo with two nsCOMPtr edges mBar and mBaz, the process can be distilled to a few simple modifications:

1. Include the header nsCycleCollectionParticipant.h in both nsFoo.h and nsFoo.cpp.
2. Change the line NS_DECL_ISUPPORTS to NS_DECL_CYCLE_COLLECTING_ISUPPORTS in the definition of nsFoo.
3. Add a line NS_DECL_CYCLE_COLLECTION_CLASS(nsFoo) within the public portion of definition of nsFoo.
4. Add a line NS_INTERFACE_MAP_ENTRIES_CYCLE_COLLECTION(nsFoo) to the interface map of nsFoo in nsFoo.cpp.
5. Change the line NS_IMPL_ADDREF(nsFoo) to NS_IMPL_CYCLE_COLLECTING_ADDREF(nsFoo) in nsFoo.cpp.
6. Change the line NS_IMPL_RELEASE(nsFoo) to NS_IMPL_CYCLE_COLLECTING_RELEASE(nsFoo) in nsFoo.cpp.
7. Add a line NS_IMPL_CYCLE_COLLECTION_CLASS_2(nsFoo, mBar, mBaz) in nsFoo.cpp.

It is possible that your class has more complicated structure than this picture. For example, your class may have multiple nsISupports base classes, which requires the use of some *_AMBIGUOUS macros that perform a disambiguating downcast. Or your class may have a complicated ownership structure, such that the simple NS_IMPL_CYCLE_COLLECTION_CLASS_N macros are insufficient; in this case you might need to implement the Traverse and Unlink methods of your helper class manually. It's helpful even in these cases to use the NS_IMPL_CYCLE_COLLECTION_TRAVERSE_{BEGIN,END} and NS_IMPL_CYCLE_COLLECTION_UNLINK_{BEGIN,END} macros. You can see an example of their use in some more complicated classes such as content/base/src/nsGenericElement.cpp. If your class has tearoffs or is being aggregated by other classes it is important to make the tearoff classes or the outer classes participate in cycle collection too, not doing so could lead to the cycle collector trying to collect the objects too soon.