JS_SetGCZeal

  • Revision slug: SpiderMonkey/JSAPI_Reference/JS_SetGCZeal
  • Revision title: JS_SetGCZeal
  • Revision id: 382929
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment update for bug 742570 by noting "compartment" argument was removed in Firefox 14.

Revision Content

{{ jsapi_minversion_header("1.8") }}

Enable GC zeal, a testing and debugging feature that helps find GC-related bugs in JSAPI applications.

Syntax

void JS_SetGCZeal(JSContext *cx, uint8 zeal, uint32 frequency, JSBool compartment);
Name Type Description
cx JSContext * A context. The GC zeal level of the associated JSRuntime is set.
zeal uint8 The desired level of garbage collection: 0 for normal, 1 for very frequent GC, 2 for extremely frequent GC.
frequency uint32 When zeal is 2, a GC is triggered every frequency allocations.
compartment JSBool If this is true, the triggered allocation will be a compartment GC. Otherwise it will be a full GC. {{obsolete_inline(14)}}

Description

JS_SetGCZeal sets the level of garbage collection for a runtime. This is the zeal argument. At level 0, the default, garbage collection rarely happens unless the application explicitly requests it. At level 1, SpiderMonkey collects at places that are likely to cause problems for embedders, such as when roots are removed. At level 2, SpiderMonkey collects every time an object, string, or function is allocated (or really every frequency allocations). When the compartment argument is true, only the current compartment is collected. Otherwise, all compartments are collected.

Note: The compartment parameter was removed in Gecko 14.

With GC zeal enabled, GC-related crashes are much easier to reproduce (they happen more reliably) and debug (they happen sooner, closer to the source of the bug). The drawback is that GC zeal causes JavaScript code to run very (or extremely) slowly.

Regularly running your test suite with GC zeal enabled at level 2 is a good practice.

This function is available only in DEBUG builds. To enable this function in an optimized build, define the macro JS_GC_ZEAL when building SpiderMonkey.

(In a debug build of Gecko, you can also set the current GC zeal level using the javascript.options.gczeal preference.)

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

Revision Source

<p>{{ jsapi_minversion_header("1.8") }}</p>
<p>Enable GC zeal, a testing and debugging feature that helps find GC-related bugs in JSAPI applications.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="eval">
void <strong>JS_SetGCZeal</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uint8</a> zeal, uint32 frequency, JSBool compartment);
</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>A context. The GC zeal level of the associated <code><a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSRuntime</a></code> is set.</td>
    </tr>
    <tr>
      <td><code>zeal</code></td>
      <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uint8</a></code></td>
      <td>The desired level of garbage collection: <code>0</code> for normal, <code>1</code> for very frequent GC, <code>2</code> for extremely frequent GC.</td>
    </tr>
    <tr>
      <td><code>frequency</code></td>
      <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/jsint" title="en/jsint">uint32</a></code></td>
      <td>When <code>zeal</code> is 2, a GC is triggered every <code>frequency</code> allocations.</td>
    </tr>
    <tr>
      <td><code>compartment</code></td>
      <td><code><a href="/en/SpiderMonkey/JSAPI_Reference/JSBool" title="en/JSBool">JSBool</a></code></td>
      <td>If this is <code>true</code>, the triggered allocation will be a compartment GC. Otherwise it will be a full GC. {{obsolete_inline(14)}}</td>
    </tr>
  </tbody>
</table>
<h2 id="Description" name="Description">Description</h2>
<p><strong><code>JS_SetGCZeal</code></strong> sets the level of garbage collection for a runtime. This is the <code>zeal</code> argument. At level <code>0</code>, the default, garbage collection rarely happens unless the application explicitly requests it. At level <code>1</code>, SpiderMonkey collects at places that are likely to cause problems for embedders, such as when roots are removed. At level <code>2</code>, SpiderMonkey collects every time an object, string, or function is allocated (or really every <code>frequency</code> allocations). When the <code>compartment</code> argument is <code>true</code>, only the current compartment is collected. Otherwise, all compartments are collected<strong>.</strong></p>
<div class="note">
  <p><strong>Note:</strong> The <code>compartment</code> parameter was removed in Gecko 14.</p>
</div>
<p>With GC zeal enabled, GC-related crashes are much easier to reproduce (they happen more reliably) and debug (they happen sooner, closer to the source of the bug). The drawback is that GC zeal causes JavaScript code to run very (or extremely) slowly.</p>
<p>Regularly running your test suite with GC zeal enabled at level 2 is a good practice.</p>
<p>This function is available only in <code>DEBUG</code> builds. To enable this function in an optimized build, define the macro <code><a href="/en/JS_GC_ZEAL" title="en/JS_GC_ZEAL">JS_GC_ZEAL</a></code> when building SpiderMonkey.</p>
<p>(In a debug build of Gecko, you can also set the current GC zeal level using the <code>javascript.options.gczeal</code> preference.)</p>
<p>{{ LXRSearch("ident", "i", "JS_SetGCZeal") }}</p>
Revert to this revision