View source for XPConnect object wrapping

== Some notes on wrapped natives and native wrappers ==

=== Wrapped Natives ===

Every C++ <tt>nsISupports*</tt> can be "wrapped" by a JS object. In such a scenario, the JS object holds an <tt>XPCWrappedNative*</tt> in its private slot. The cluster of "<tt>JSObject+XPCWrappedNative</tt>" is sort of considered as a unit; code and comments frequently refer to the JS side ''or'' the C++ side as "a wrapped native".

The picture looks like this:
                                                               __
                                                                 \
 +----------------------------------------------------------+    |
 | JSObject { JSClass *class = { "HTMLDivElement", ... }    |    |
 |            slots[0] = ...                                |    |
 |            slots[JSSLOT_PRIVATE] = XPCWrappedNative* }   |    |
 +----------------------------------------------------|-----+    |  "the
                                             ^        |           \  wrapper"
                                             |        V           /
 +-------------------------------------------|--------------+    |
 | XPCWrappedNative { JSObject* mFlatJSObject;              |    |
 |                    ...                                   |    |
 |                    nsISupports* mIdentity; }             |    |
 +------------------------------------------|---------------+    |
                                            |                  __/
                                            V
 +----------------------------------------------------------+
 | nsHTMLDivElement { ... }                                 |
 +----------------------------------------------------------+

Note that the <tt>JSObject</tt> has a special <tt>JSClass</tt> that is named after the object it's wrapping. The <tt>JSObject</tt> forwards calls to the wrapped C++ object using helpers in this class.


=== Lifecycle and refcounts ===

When constructing the collection of objects pictured above, we can imagine that the caller was C++, and was providing the <tt>nsHTMLDivElement*</tt>. In such a case, the caller would have received back an <tt>XPCWrappedNative*</tt> with refcount 2. Why 2?

# The reference any caller usually gets to an XPCOM object it just asked for.
# The reference the <tt>JSObject</tt>'s private slot has to the <tt>XPCWrappedNative</tt>.

This models a simple fact: for the <tt>XPCWrappedNative</tt> to die, both the C++ XPCOM world ''and'' the JS heap ought to have forgetten about it. If either side still sees it, it should stay alive.

Thus the <tt>JSObject</tt> keeps the <tt>XPCWrappedNative</tt> alive, and the <tt>XPCWrappedNative</tt> keeps the <tt>nsISupports</tt> that it's pointing to alive. But there's an important detail: the <tt>XPCWrappedNative</tt> does ''not'' directly keep the <tt>JSObject</tt> alive. Doing so unconditionally -- for example rooting the <tt>JSObject</tt> -- would give rise to a cyclic graph: the pair of objects would keep each other alive indefinitely. So the <tt>XPCWrappedNative</tt> holds a pointer to the <tt>JSObject</tt>, but doesn't root it.

This may prompt the curious reader to wonder what sort of mechanisms exist to keep the <tt>JSObject</tt> associated with an <tt>XPCWrappedNative</tt> alive. There are at least four (!) such mechanisms, each tailored to a situation in which it's "appropriate" to keep the <tt>JSObject</tt> alive:

# Obviously, if there's a root in the JS heap that can reach the <tt>JSObject</tt>, it stays alive.
# As long as a C++ caller holds a strong XPCOM reference to the <tt>XPCWrappedNative</tt>, the <tt>XPCWrappedNative</tt> has refcount >= 2. It turns out that every live <tt>XPCWrappedNative</tt> is ''also'' held in a hashtable, internal to xpconnect. The hashtable maps <tt>nsISupports*</tt> to <tt>XPCWrappedNative*</tt>. During JS GC a function (<tt>WrappedNativeJSGCThingMarker</tt> in <tt>xpcwrappednativescope.cpp</tt>) is run over that hashtable, marking the <tt>JSObject</tt> pointed to by every <tt>XPCWrappedNative</tt> with refcount > 1. This keeps things like "preserved wrappers" alive (see further below).
# Many C++ callers don't construct <tt>XPCWrappedNatives</tt> themselves, they actually call <tt>XPConnect::WrapNative()</tt>. <tt>WrapNative()</tt> constructs the <tt>XPCWrappedNative</tt> and tables it, but returns a <tt>XPCJSObjectHolder</tt> pointing to the <tt>JSObject</tt>. <tt>XPCJSObjectHolder</tt> ''does'' keep the <tt>JSObject</tt> alive for the duration of its use, by rooting. See <tt>XPCJSObjectHolder::XPCJSObjectHolder</tt> in <tt>xpcwrappednative.cpp</tt>.
# If the C++ caller is part of xpconnect itself, and is operating on <tt>XPCWrappedNatives</tt> that aren't in the table yet, the caller may store a pointer to an <tt>XPCWrappedNative</tt> in an <tt>AutoMarkingWrappedNativePtr</tt>. This is a special type which inserts itself into a global per-thread linked list and also receives a call during JS GC, which it forwards on to the <tt>AutoMark()</tt> method on the <tt>XPCWrappedNative</tt>, which subsequently causes the <tt>JSObject</tt> to be marked (thus kept alive). It's not clear to me why this is done rather than rooting or automatically inserting into the table, but it is. There is some baroque macrology and locking / work-interleaving code that suggests the answer may be complicated. <tt>AutoMarkingWrappedNativePtr</tt> is private to the implementation of xpconnect, so you won't see it in normal XPCOM-using client code.

=== Native Wrappers ===

There is a further complication to the pretty picture above (and terminology namespace): native wrappers.

A native wrapper, despite name-similarity to "wrapped native", is not just another term for one side of this <tt>JSObject+XPCWrappedNative</tt> cluster. It's a specific state that the JSObject involved in the cluster can have.

Concretely: the <tt>JSObject</tt>'s <tt>JSClass</tt> can be <tt>XPCNativeWrapper::sXPC_NW_JSClass.base</tt>. When this is true, the <tt>JSObject</tt> is said to ''be'' a native wrapper.

Here is the picture:

 +------------------------------------------------------------+
 | JSObject { JSClass *class = { "XPCNativeWrapper", ... }    |
 |            slots[0] = ...                                  |
 |            slots[JSSLOT_PRIVATE] = XPCWrappedNative* }     |
 +----------------------------------------------------|-------+
                                             ^        |
                                             |        V
 +-------------------------------------------|----------------+
 | XPCWrappedNative { JSObject* mFlatJSObject;                |
 |                    ...                                     |
 |                    nsISupports* mIdentity; }               |
 +------------------------------------------|-----------------+
                                            |
                                            V
 +------------------------------------------------------------+
 | nsHTMLDivElement { ... }                                   |
 +------------------------------------------------------------+

The picture looks similar to the first one, and is similar in terms of memory ''ownership'' semantics. The functional difference is that a <tt>XPCNativeWrapper</tt> performs property lookup differently from a normal wrapped native. The difference is related to a certain type of attack vector involving property-name shadowing.

For example, suppose chrome JS associated with some browser logic (to maintain, e.g., the current document's title in the window titlebar; or hover-sensitive context menu items) or extension were to walk the content DOM. Doing so involves acquiring wrappers to content DOM nodes and calling DOM methods on the <tt>JSObject</tt> side of those wrappers, but with chrome privilege. If content were malicious, it could shadow DOM methods that are supposed to pass through to the underlying C++ DOM element, by attaching same-named properties to the wrapper JSObject. If these shadowed properties contained attack code, and other bugs bit, chrome would call the attack code with chrome privilege.  Even without other bugs, chrome could be misled by content properties.

So instead of returning a normal wrapper to JS chrome in such a case, we return a wrapper whose <tt>JSObject</tt> has class <tt>XPCNativeWrapper</tt>. This wrapper still has an <tt>XPCWrappedNative</tt> object that points to the DOM node, but the <tt>JSObject</tt> in the cluster routes property-lookup requests through <tt>JSClass</tt> methods in <tt>XPCNativeWrapper.cpp</tt>. Such a wrapper performs special property lookup that's guaranteed to pass through to the underlying wrapped C++ object, and ignore script properties that might shadow native properties.

Unfortunately code and comments are not always careful with the term "wrapper", and use it to refer to either case, as well as either the JS or C++ objects in either case. So when a comment mentions "the wrapper" it may be talking about an <tt>XPCWrappedNative</tt> or a <tt>JSObject</tt>, in either "native wrapper" or "wrapped native" scenarios.

Personally, I wish <tt>XPCNativeWrapper</tt> had been called "security device" or something. It looks a lot like <tt>XPCWrappedNative</tt>, and my eyes often gloss one as the other (it's especially annoying given that both classes have some of the same methods!)

Oh well.

=== Preserved Wrappers ===

When a script obtains "a wrapper" (either a plain wrapped native or a native wrapper, see above) it thinks it has a normal JS object. Normal JS objects permit scripts to stick new properties on them. So scripts expect wrappers to retain properties that are stuck to them.

Unfortunately if you draw a picture of this you'll soon realize that there's not enough connectivity for that to work by default. Here's a picture of an HTML element with a script property -- a <tt>JSString</tt> -- stuck on it:

 +------------------------------------------------------------+
 | JSString { "hello world" }                                 |
 +------------------------------------------------------------+
                             ^
                             |
 +---------------------------|--------------------------------+
 | JSObject { slots[N] = { jsval }                            |
 |            JSClass *class = { "HTMLDivElement", ... }      |
 |            slots[JSSLOT_PRIVATE] = XPCWrappedNative* }     |
 +----------------------------------------------------|-------+
                                             ^        |
                                             |        V
 +-------------------------------------------|----------------+
 | XPCWrappedNative { JSObject* mFlatJSObject;                |
 |                    ...                                     |
 |                    nsISupports* mIdentity; }               |
 +-------------------------------------------|----------------+
                                             |
                                             V
 +------------------------------------------------------------+
 | nsHTMLDivElement { ... }                                   |
 +------------------------------------------------------------+

The script asked for a div element from the DOM, got a wrapper (an <tt>XPCWrappedNative+JSObject</tt> cluster) and put a string on the <tt>JSObject</tt> side of the wrapper. All well and good until the script then stops running. The DOM isn't holding any references to the <tt>XPCWrappedNative</tt>, and there are no roots, so the <tt>JSObject</tt> is soon GC'ed and the <tt>XPCWrappedNative</tt> is recycled. That's ideal most of the time because wrappers are generally supposed to be ephemeral; they're instantiated for the duration of a call and then thrown out. We wouldn't normally want to keep them around. 

But in this case it's no good: the string is forgotten about. If script later goes looking for the property it set, the string is gone. So we have one more trick: when someone mutates a wrapper, we tell the C++ DOM node to "preserve" the wrapper (at least the <tt>XPCWrappedNative</tt> side of it, which is enough), keeping it alive by storing a strong XPCOM reference to it in a hashtable associated with the DOM node.

When such a DOM node is deleted, it releases all the "preserved wrappers" associated with it. Until then, properties added to the wrapper by script content persist.