JS_GetParent

Syntax

JSObject *
JS_GetParent(JSObject *obj);

Description

JS_GetParent retrieves the parent object of obj, or NULL if obj does not have a parent.

Each object is assigned a parent when it is created:

• The standard library objects and functions all have the global object as their parent.
• Objects created by standard library functions, such as Array.prototype.concat, have the global object as their parent.
• An object created by a script via the new keyword has the same parent as the constructor.  For example, after d = new Date, d has the same parent as Date, ordinarily the global object.
• An object created by a script via implicit conversion (the ECMAScript ToObject operator), an object initializer ({a: 1, b: 2}), or an array initializer ([1, 2, 3]), has the global object as its parent.
• The parent of a Function created by evaluating a function declaration or function expression in a script depends on the lexical scope of the function.  If there is no enclosing function, with statement, or block scope, then the Function's parent is the global object. Otherwise, the parent is implementation-defined. It may be a Call, With, or Block object representing the function's dynamic scope, or it may be the global object. In any case the global object is guaranteed appear on the new function's parent chain.

• The initial parent of an object created via the JSAPI depends on the particular JSAPI function (of which there are many that create objects, including but not limited to JS_NewObject, JS_ConstructObject, JS_DefineObject, JS_ValueToObject, JS_NewArrayObject, JS_NewScriptObject, JS_NewFunction, JS_CompileFunction, JS_DefineFunction, JS_DefineFunctions, and JS_InitClass). Some of these functions allow the application to specify a parent object. If the JSAPI function creating the object has a parent parameter, and the application passes a non-null value to it, then that object becomes the new object's parent. Otherwise, if the context is running any scripts or functions, a default parent object is selected based on those. Otherwise, if the context has a global object, it is used. Otherwise the new object has no parent. This is often the case for the global object, which is typically the first object created in a new context.

The preferred way to set an object's parent is by using the parent parameter to JS_NewObject or JS_ConstructObject.  An application can also use JS_SetParent, but see the caveats on that page.

An object's parent serves two purposes in SpiderMonkey:

1. For some functions, it is used to implement lexical scoping (but this is an implementation detail).
2. Applications that use SpiderMonkey's custom security features can use the parent during security checks, as a convenient way to determine the security domain of an object being accessed. The typical rule is that every object is in the same security domain as its parent. (But each application can define its own security rules. See the Security section of the User Guide for an introduction to the security model.)

In some cases, JavaScript code can get an object's parent via the read-only obj.__parent__ property. But if an object's parent is an internal-use-only object (that is, a special Call, With, or Block object), JS_GetParent simply returns it, but obj.__parent__ === null. Similarly, if an object's parent is an inner object, JS_GetParent simply returns it, but obj.__parent__ returns the corresponding outer object.

See Also

• MXR ID Search for JS_GetParent
• bug 1131805 -- removed