JS_ClearNewbornRoots

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_ClearNewbornRoots
  • Revision title: JS_ClearNewbornRoots
  • Revision id: 312375
  • Created:
  • Creator: tschneidereit
  • Is current revision? Yes
  • Comment

Revision Content

{{ Obsolete_header("jsapi5") }}

Clear a context's newborn roots, which temporarily protect newly allocated values from garbage collection.

Syntax

void JS_ClearNewbornRoots(JSContext *cx);
Name Type Description
cx JSContext * The context to clear.

Description

The last GC thing of each type (object, string, double, external string types) created on a given context is kept alive until another thing of the same type is created, using a newborn root in the context. These newborn roots help native code protect newly-created GC-things from GC invocations activated before those things can be rooted using local or global roots.

However, the newborn roots can also entrain great gobs of garbage, so the JS_GC entry point clears them for the context on which GC is being forced. Embeddings may need to do likewise for all contexts.

See JS_EnterLocalRootScope for a better way to manage newborns in cases where native hooks (functions, getters, setters, etc.) create many GC-things, potentially without connecting them to predefined local roots such as *rval or argv{{ mediawiki.external('i') }} in an active JSNative function. Using JS_EnterLocalRootScope disables updating of the context's per-gc-thing-type newborn roots, until control flow unwinds and leaves the outermost nesting local root scope.

{{ LXRSearch("ident", "i", "JS_ClearNewbornRoots") }}

Revision Source

<p>{{ Obsolete_header("jsapi5") }}</p>
<p>Clear a context's <em>newborn roots</em>, which temporarily protect newly allocated values from garbage collection.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="eval">
void <strong>JS_ClearNewbornRoots</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx);
</pre>
<table class="fullwidth-table">
  <tbody>
    <tr>
      <th>Name</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
    <tr>
      <td><code>cx</code></td>
      <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a>&nbsp;*</code></td>
      <td>The context to clear.</td>
    </tr>
  </tbody>
</table>
<h2 id="Description" name="Description">Description</h2>
<p>The last GC thing of each type (object, string, double, external string types) created on a given context is kept alive until another thing of the same type is created, using a newborn root in the context. These newborn roots help native code protect newly-created GC-things from GC invocations activated before those things can be rooted using local or global roots.</p>
<p>However, the newborn roots can also entrain great gobs of garbage, so the <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_GC" title="en/JS_GC">JS_GC</a></code> entry point clears them for the context on which GC is being forced. Embeddings may need to do likewise for all contexts.</p>
<p>See <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_EnterLocalRootScope" title="en/JS_EnterLocalRootScope">JS_EnterLocalRootScope</a></code> for a better way to manage newborns in cases where native hooks (functions, getters, setters, etc.) create many GC-things, potentially without connecting them to predefined local roots such as <code>*rval</code> or <code>argv{{ mediawiki.external('i') }}</code> in an active <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSNative" title="en/JSNative">JSNative</a></code> function. Using <code>JS_EnterLocalRootScope</code> disables updating of the context's per-gc-thing-type newborn roots, until control flow unwinds and leaves the outermost nesting local root scope.</p>
<p>{{ LXRSearch("ident", "i", "JS_ClearNewbornRoots") }}</p>
Revert to this revision