Components.utils

  • Revision slug: Components.utils
  • Revision title: Components.utils
  • Revision id: 336545
  • Created:
  • Creator: saneyuki_s
  • Is current revision? No
  • Comment

Revision Content

Components.utils is a collection of various useful XPConnect features. Its interface is defined at {{ Source("js/xpconnect/idl/xpccomponents.idl") }}.

The object currently has the following members:

EDITORS! please keep this list in sync with the Components object page

Methods

Method Description
createArrayIn() Returns an array created in specified compartment. {{ gecko_minversion_inline("16") }}
createObjectIn() Creates a new object, created in the scope of the specified object's compartment. {{ gecko_minversion_inline("8.0") }}
dispatch() Dispatches a runnable to the current/main thread. If the parameter is passed, the runnable will be dispatch in the compartment of the parameter, which affects which error reporter gets called. {{ gecko_minversion_inline("17") }}
evalInSandbox() Runs JavaScript code in a sandbox, usually used to run code with restricted privileges.
forceGC() {{ Gecko_minversion_inline(1.9) }} Forces a garbage collection cycle.
forceCC() {{ Gecko_minversion_inline(17) }} Forces a cycle collection cycle.
forceShrinkingGC() {{ Gecko_minversion_inline(12) }} Forces a shrinking garbage collection cycle.
getComponentsForScope() {{ Gecko_minversion_inline(18) }} This seemingly-paradoxical API allows privileged code to explicitly give unprivileged code a reference to its own Components object (whereas it's normally hidden away on a scope chain visible only to XBL methods). See also SpecialPowers.getComponents.
getGlobalForObject() {{ Gecko_minversion_inline("1.9.3") }} Returns the global object with which a given object is associated (through its prototype chain at birth, for example).
getJSTestingFunctions() {{ Gecko_minversion_inline(13) }}
getWeakReference() {{ Gecko_minversion_inline(1.9) }} Gets a weak reference for the object passed in.
import() {{ Gecko_minversion_inline(1.9) }} Loads a JS module into the current script, without sharing a scope.
isDeadWrapper() {{ Gecko_minversion_inline(17) }} Determines whether this object is backed by a DeadObjectProxy.
lookupMethod()

Looks up a native (i.e. declared in the interface) method or property of an XPCOM object. Serves the same purpose as XPCNativeWrapper.

makeObjectPropsNormal() Ensures that all functions come from the specified object's scope, and aren't cross-compartment wrappers. May only be called from JavaScript code. {{ gecko_minversion_inline("8.0") }}
nondeterministicGetWeakMapKeys() Return the keys in a weak map. This operation is non-deterministic because it is affected by the scheduling of the garbage collector and the cycle collector. This should only be used to write tests of the interaction of the GC and CC with weak maps. {{ gecko_minversion_inline("10") }}
nukeSandbox() {{ gecko_minversion_inline("17") }}
recomputeWrappers() {{ gecko_minversion_inline("17") }}To be called from JS only. This is for Gecko internal use only, and may disappear at any moment.
reportError() Reports a JavaScript Error object to the Error Console.
setWantXrays() {{ gecko_minversion_inline("20") }} To be called from JS only. This is for Gecko internal use only, and may disappear at any moment.
schedulePreciseGC() Schedules a garbage collection cycle for some time in the future at which no JavaScript code is running. This lets you specify a callback so you can be notified once the garbage collection cycle has been performed. {{ gecko_minversion_inline("7.0") }}
setGCZeal() Sets the level of garbage collection level for full garbage collection. See {{ jsapixref("JS_SetGCZeal") }} for details; this method calls through to that with the specified value as the zeal value. {{ gecko_minversion_inline("10.0") }}

Properties

 

Property Type Description
Sandbox {{ interface("nsIXPCComponents_utils_Sandbox") }} Creates sandbox objects for use with evalInSandbox().
atline {{ gecko_minversion_inline("10.0") }} Boolean When atline is enabled, comments of the form //@line num set the number of the following line to num. This reflects the value of the JavaScript environment's option by the same name. Read only.
ion {{ gecko_minversion_inline("18") }} Boolean Read only.
methodjit {{ gecko_minversion_inline("10.0") }} Boolean This reflects the value of the JavaScript environment's option by the same name. Read only.
methodjit_always {{ gecko_minversion_inline("10.0") }} Boolean This reflects the value of the JavaScript environment's option by the same name. Read only.
relimit {{ gecko_minversion_inline("10.0") }} Boolean This reflects the value of the JavaScript environment's option by the same name. Read only.
strict {{ gecko_minversion_inline("10.0") }} Boolean Strict mode is enabled. This reflects the value of the JavaScript environment's option by the same name. Read only.
strict_mode {{ gecko_minversion_inline("15") }} Boolean Read only.
werror {{ gecko_minversion_inline("10.0") }} Boolean Warnings should be treated as errors. This reflects the value of the JavaScript environment's option by the same name. Read only.
xml {{ gecko_minversion_inline("10.0") }} Boolean XML mode is enabled. This reflects the value of the JavaScript environment's option by the same name. Read only.

 

{{ languages( { "fr": "fr/Components.utils", "ja": "ja/Components.utils", "pl": "pl/Components.utils" } ) }}

Revision Source

<p><code>Components.utils</code> is a collection of various useful XPConnect features. Its interface is defined at {{ Source("js/xpconnect/idl/xpccomponents.idl") }}.</p>
<p>The object currently has the following members:</p>
<p><span class="comment">EDITORS! please keep this list in sync with the <a href="/en/Components_object" title="en/Components object">Components object</a> page</span></p>
<h2 id="Methods">Methods</h2>
<table class="fullwidth-table">
  <tbody>
    <tr>
      <th>Method</th>
      <th>Description</th>
    </tr>
    <tr>
      <td><a href="/en/Components.utils.createArrayIn" title="en/Components.utils.createArrayIn"><code>createArrayIn()</code></a></td>
      <td>Returns an array created in specified compartment. {{ gecko_minversion_inline("16") }}</td>
    </tr>
    <tr>
      <td><a href="/en/Components.utils.createObjectIn" title="en/Components.utils.createObjectIn"><code>createObjectIn()</code></a></td>
      <td>Creates a new object, created in the scope of the specified object's compartment. {{ gecko_minversion_inline("8.0") }}</td>
    </tr>
    <tr>
      <td><a href="/en/Components.utils.dispatch" title="en/Components.utils.dispatch"><code>dispatch()</code></a></td>
      <td>Dispatches a runnable to the current/main thread. If the parameter is passed, the runnable will be dispatch in the compartment of the parameter, which affects which error reporter gets called. {{ gecko_minversion_inline("17") }}</td>
    </tr>
    <tr>
      <td><code><a href="/en/Components.utils.evalInSandbox" title="en/Components.utils.evalInSandbox">evalInSandbox()</a></code></td>
      <td>Runs JavaScript code in a sandbox, usually used to run code with restricted privileges.</td>
    </tr>
    <tr>
      <td><code><a href="/en/Components.utils.forceGC" title="en/Components.utils.forceGC">forceGC()</a></code></td>
      <td>{{ Gecko_minversion_inline(1.9) }} Forces a garbage collection cycle.</td>
    </tr>
    <tr>
      <td><code><a href="/en/Components.utils.forceCC" title="en/Components.utils.forceGC">forceCC()</a></code></td>
      <td>{{ Gecko_minversion_inline(17) }} Forces a cycle collection cycle.</td>
    </tr>
    <tr>
      <td><code><a href="/en/Components.utils.forceShrinkingGC" title="en/Components.utils.forceShrinkingGC">forceShrinkingGC()</a></code></td>
      <td>{{ Gecko_minversion_inline(12) }} Forces a shrinking garbage collection cycle.</td>
    </tr>
    <tr>
      <td><code><a href="/en/Components.utils.getComponentsForScope" title="en/Components.utils.getComponentsForScope">getComponentsForScope()</a></code></td>
      <td>{{ Gecko_minversion_inline(18) }} This seemingly-paradoxical API allows privileged code to explicitly give <span class="difflineplus">unprivileged code a reference to its own Components object (whereas it's </span><span class="difflineplus">normally hidden away on a scope chain visible only to XBL methods). See</span><span class="difflineplus"> also SpecialPowers.getComponents.</span></td>
    </tr>
    <tr>
      <td><code><a href="/en/Components.utils.getGlobalForObject" title="en/Components.utils.getGlobalForObject">getGlobalForObject()</a></code></td>
      <td>{{ Gecko_minversion_inline("1.9.3") }} Returns the global object with which a given object is associated (through its prototype chain at birth, for example).</td>
    </tr>
    <tr>
      <td><code><a href="/en/Components.utils.getJSTestingFunctions" title="en/Components.utils.getJSTestingFunctions">getJSTestingFunctions()</a></code></td>
      <td>{{ Gecko_minversion_inline(13) }}</td>
    </tr>
    <tr>
      <td><code><a href="/en/Components.utils.getWeakReference" title="en/Components.utils.getWeakReference">getWeakReference()</a></code></td>
      <td>{{ Gecko_minversion_inline(1.9) }} Gets a weak reference for the object passed in.</td>
    </tr>
    <tr>
      <td><code><a href="/en/Components.utils.import" title="en/Components.utils.import">import()</a></code></td>
      <td>{{ Gecko_minversion_inline(1.9) }} Loads a JS module into the current script, without sharing a scope.</td>
    </tr>
    <tr>
      <td><code><a href="/en/Components.utils.isDeadWrapper" title="en/Components.utils.isDeadWrapper">isDeadWrapper()</a></code></td>
      <td>{{ Gecko_minversion_inline(17) }} Determines whether this object is backed by a DeadObjectProxy.</td>
    </tr>
    <tr>
      <td><code><a href="/en/Components.utils.lookupMethod" title="en/Components.utils.lookupMethod">lookupMethod()</a></code></td>
      <td>
        <p>Looks up a native (i.e. declared in the interface) method or property of an XPCOM object. Serves the same purpose as <a href="/en/XPCNativeWrapper" title="en/XPCNativeWrapper">XPCNativeWrapper</a>.</p>
      </td>
    </tr>
    <tr>
      <td><a href="/en/Components.utils.makeObjectPropsNormal" title="en/Components.utils.makeObjectPropsNormal"><code>makeObjectPropsNormal()</code></a></td>
      <td>Ensures that all functions come from the specified object's scope, and aren't cross-compartment wrappers. May only be called from JavaScript code. {{ gecko_minversion_inline("8.0") }}</td>
    </tr>
    <tr>
      <td><a href="/en/Components.utils.nondeterministicGetWeakMapKeys" title="en/Components.utils.nondeterministicGetWeakMapKeys"><code>nondeterministicGetWeakMapKeys()</code></a></td>
      <td>Return the keys in a weak map. This operation is non-deterministic because it is affected by the scheduling of the garbage collector and the cycle collector. This should only be used to write tests of the interaction of the GC and CC with weak maps. {{ gecko_minversion_inline("10") }}</td>
    </tr>
    <tr>
      <td><a href="/en/Components.utils.nukeSandbox" title="en/Components.utils.nukeSandbox"><code>nukeSandbox()</code></a></td>
      <td>{{ gecko_minversion_inline("17") }}</td>
    </tr>
    <tr>
      <td><code><a href="/en/Components.utils.recomputeWrappers" title="en/Components.utils.recomputeWrappers">recomputeWrappers()</a></code></td>
      <td>{{ gecko_minversion_inline("17") }}To be called from JS only. This is for Gecko internal use only, and may disappear at any moment.</td>
    </tr>
    <tr>
      <td><code><a href="/en/Components.utils.reportError" title="en/Components.utils.reportError">reportError()</a></code></td>
      <td>Reports a JavaScript Error object to the <a href="/en/Error_Console" title="en/Error_Console">Error Console</a>.</td>
    </tr>
    <tr>
      <td><code><a href="/en/Components.utils.setWantXrays" title="en/Components.utils.setWantXrays">setWantXrays()</a></code></td>
      <td>{{ gecko_minversion_inline("20") }} To be called from JS only. This is for Gecko internal use only, and may disappear at any moment.</td>
    </tr>
    <tr>
      <td><a href="/en/Components.utils.schedulePreciseGC" title="en/Components.utils.schedulePreciseGC"><code>schedulePreciseGC()</code></a></td>
      <td>Schedules a garbage collection cycle for some time in the future at which no JavaScript code is running. This lets you specify a callback so you can be notified once the garbage collection cycle has been performed. {{ gecko_minversion_inline("7.0") }}</td>
    </tr>
    <tr>
      <td><a href="/en/Components.utils.setGCZeal" title="en/Components.utils.setGCZeal"><code>setGCZeal()</code></a></td>
      <td>Sets the level of garbage collection level for full garbage collection. See {{ jsapixref("JS_SetGCZeal") }} for details; this method calls through to that with the specified value as the <code>zeal</code> value. {{ gecko_minversion_inline("10.0") }}</td>
    </tr>
  </tbody>
</table>
<h2 id="Properties">Properties</h2>
<p>&nbsp;</p>
<table class="standard-table" style="width: auto;">
  <tbody>
    <tr>
      <td class="header">Property</td>
      <td class="header">Type</td>
      <td class="header">Description</td>
    </tr>
    <tr>
      <td><code><a href="/en/Components.utils.Sandbox" title="en/Components.utils.Sandbox">Sandbox</a></code></td>
      <td>{{ interface("nsIXPCComponents_utils_Sandbox") }}</td>
      <td>Creates sandbox objects for use with <code>evalInSandbox()</code>.</td>
    </tr>
    <tr>
      <td><code>atline</code> {{ gecko_minversion_inline("10.0") }}</td>
      <td><code>Boolean</code></td>
      <td>When <code>atline</code> is enabled, comments of the form <code>//@line <em>num</em></code> set the number of the following line to <code><em>num</em></code>. This reflects the value of the <a href="/en/Introduction_to_the_JavaScript_shell#options%28.5Boption_....5D%29" title="https://developer.mozilla.org/en/Introduction_to_the_JavaScript_shell#options%28.5Boption_....5D%29">JavaScript environment's option</a> by the same name.<strong> Read only.</strong></td>
    </tr>
    <tr>
      <td><code>ion</code> {{ gecko_minversion_inline("18") }}</td>
      <td><code>Boolean</code></td>
      <td><strong>Read only.</strong></td>
    </tr>
    <tr>
      <td><code>methodjit</code> {{ gecko_minversion_inline("10.0") }}</td>
      <td><code>Boolean</code></td>
      <td>This reflects the value of the <a href="/en/Introduction_to_the_JavaScript_shell#options%28.5Boption_....5D%29" title="https://developer.mozilla.org/en/Introduction_to_the_JavaScript_shell#options%28.5Boption_....5D%29">JavaScript environment's option</a> by the same name.<strong> Read only.</strong></td>
    </tr>
    <tr>
      <td><code>methodjit_always</code> {{ gecko_minversion_inline("10.0") }}</td>
      <td><code>Boolean</code></td>
      <td>This reflects the value of the <a href="/en/Introduction_to_the_JavaScript_shell#options%28.5Boption_....5D%29" title="https://developer.mozilla.org/en/Introduction_to_the_JavaScript_shell#options%28.5Boption_....5D%29">JavaScript environment's option</a> by the same name.<strong> Read only.</strong></td>
    </tr>
    <tr>
      <td><code>relimit</code> {{ gecko_minversion_inline("10.0") }}</td>
      <td><code>Boolean</code></td>
      <td>This reflects the value of the <a href="/en/Introduction_to_the_JavaScript_shell#options%28.5Boption_....5D%29" title="https://developer.mozilla.org/en/Introduction_to_the_JavaScript_shell#options%28.5Boption_....5D%29">JavaScript environment's option</a> by the same name.<strong> Read only.</strong></td>
    </tr>
    <tr>
      <td><code>strict</code> {{ gecko_minversion_inline("10.0") }}</td>
      <td><code>Boolean</code></td>
      <td>Strict mode is enabled. This reflects the value of the <a href="/en/Introduction_to_the_JavaScript_shell#options%28.5Boption_....5D%29" title="https://developer.mozilla.org/en/Introduction_to_the_JavaScript_shell#options%28.5Boption_....5D%29">JavaScript environment's option</a> by the same name.<strong> Read only.</strong></td>
    </tr>
    <tr>
      <td><code>strict_mode</code> {{ gecko_minversion_inline("15") }}</td>
      <td><code>Boolean</code></td>
      <td><strong>Read only.</strong></td>
    </tr>
    <tr>
      <td><code>werror</code> {{ gecko_minversion_inline("10.0") }}</td>
      <td><code>Boolean</code></td>
      <td>Warnings should be treated as errors. This reflects the value of the <a href="/en/Introduction_to_the_JavaScript_shell#options%28.5Boption_....5D%29" title="https://developer.mozilla.org/en/Introduction_to_the_JavaScript_shell#options%28.5Boption_....5D%29">JavaScript environment's option</a> by the same name.<strong> Read only.</strong></td>
    </tr>
    <tr>
      <td><code>xml</code> {{ gecko_minversion_inline("10.0") }}</td>
      <td><code>Boolean</code></td>
      <td>XML mode is enabled. This reflects the value of the <a href="/en/Introduction_to_the_JavaScript_shell#options%28.5Boption_....5D%29" title="https://developer.mozilla.org/en/Introduction_to_the_JavaScript_shell#options%28.5Boption_....5D%29">JavaScript environment's option</a> by the same name.<strong> Read only.</strong></td>
    </tr>
  </tbody>
</table>
<p>&nbsp;</p>
<p>{{ languages( { "fr": "fr/Components.utils", "ja": "ja/Components.utils", "pl": "pl/Components.utils" } ) }}</p>
Revert to this revision