1662214 - Add documentation for when to use HoldJSObjects

Status: RESOLVED FIXED

(Core :: XPConnect, task)

Description

[Kelsey Gilbert [:jgilbert]]

[jgilbert] What does HoldJSObjects do?
[jgilbert] uhh mccr8 ^
[jgilbert] specifically, what goes wrong if I don't call it
[Waldo] jgilbert: (blind leading the blind) I think if you don't do that, the cycle collector doesn't understand that your object has JS stuff hanging off it, that will need to be traced using JS-engine APIs.
[mccr8] jgilbert: Like Waldo said, HoldJSObjects makes your C++ object actually root the JS you are holding onto. If you C++ object is wrapper cached, then the wrapper caching code will deal with it for you.
[mccr8] If your C++ class has its own JS objects besides the JS reflector, it should probably call Hold/DropJSObjects.
[mccr8] The wrapper caching Hold/Drop only does a hold while the wrapper is preserved.
[mccr8] (That happens in nsWrapperCache::PreserveWrapper)
[jgilbert] mccr8: ok! I have objects that might have JS expando-object-references, and also hold internal RefPtrs to c++ side of JS objects (which also have expandos)
[jgilbert] mccr8: Can you think of an example failure mode here?
[mccr8] jgilbert: if the only direct references a class has to JS objects are via the wrapper cache, then you don't need hold JS objects. HoldJSObjects is needed when you have fields like JS::Heap<JSObject*>.
[mccr8] A fairly simple example of this is https://searchfox.org/mozilla-central/source/dom/base/Pose.h
[mccr8] That is wrapper cached and has a bunch of JS::Heap<> fields, so it calls HoldJSObjects in the ctor.

Comment 1

[Kelsey Gilbert [:jgilbert]]

Attachment: Bug 1662214 - Add docstring for HoldJSObjects.

Comment 2

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/436d098f0319
Add docstring for HoldJSObjects. r=mccr8 DONTBUILD

Comment 3

[Cristian Brindusan [:cbrindusan]]

https://hg.mozilla.org/mozilla-central/rev/436d098f0319