JS_SuspendRequest

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

Revision Content

{{ obsolete_header("jsapi18") }}

Suspends the calling thread's current request, if any, to allow the thread to block or perform time-consuming calculations.

Syntax

jsrefcount JS_SuspendRequest(JSContext *cx);

void JS_ResumeRequest(JSContext *cx, jsrefcount saveDepth);
Name Type Description
cx JSContext * The context whose current request is to be suspended or resumed.
saveDepth jsrefcount (only in JS_ResumeRequest) The valued returned by the matching JS_SuspendRequest call.

Description

In JS_THREADSAFE builds, when a multi-threaded application is in a request but needs to block or perform lengthy computation that can race safely with the garbage collector, it should call JS_SuspendRequest before the time-consuming operation and JS_ResumeRequest after. For more information about thread safety and requests, see JS_THREADSAFE.

JS_SuspendRequest suspends any currently active requests associated with the context cx. This allows the runtime to perform garbage collection if needed and allows other threads to access objects that the calling thread had locked. The return value is the number of nested requests that were suspended. It may be 0.

JS_ResumeRequest resumes the previously suspended requests. The saveDepth argument must be the value returned by the matching JS_SuspendRequest call. If saveDepth is nonzero and garbage collection is underway, JS_ResumeRequest blocks until the garbage collector is done.

{{ Jsapi_maxversion_inline(1.7) }} JS_SuspendRequest and JS_ResumeRequest are available only in JS_THREADSAFE builds. In SpiderMonkey 1.8 and later, these functions will be present, but will do nothing, in non-JS_THREADSAFE builds.

{{ LXRSearch("ident", "i", "JS_SuspendRequest") }}
{{ LXRSearch("ident", "i", "JS_ResumeRequest") }}

Revision Source

<p>{{ obsolete_header("jsapi18") }}</p>
<p>Suspends the calling thread's current request, if any, to allow the thread to block or perform time-consuming calculations.</p>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="eval">
<a href="/en/Jsrefcount" title="en/Jsrefcount">jsrefcount</a> <strong>JS_SuspendRequest</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx);

void <strong>JS_ResumeRequest</strong>(<a href="/en/SpiderMonkey/JSAPI_Reference/JSRuntime" title="en/JSRuntime">JSContext</a> *cx, <a href="/en/Jsrefcount" title="en/Jsrefcount">jsrefcount</a> saveDepth);
</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 whose current request is to be suspended or resumed.</td>
    </tr>
    <tr>
      <td><code>saveDepth</code></td>
      <td><code><a href="/en/Jsrefcount" title="en/Jsrefcount">jsrefcount</a></code></td>
      <td><em>(only in <code>JS_ResumeRequest</code>)</em> The valued returned by the matching <code>JS_SuspendRequest</code> call.</td>
    </tr>
  </tbody>
</table>
<h2 id="Description" name="Description">Description</h2>
<p>In <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_THREADSAFE" title="en/JS_THREADSAFE">JS_THREADSAFE</a></code> builds, when a multi-threaded application is in a request but needs to block or perform lengthy computation that can race safely with the garbage collector, it should call <code>JS_SuspendRequest</code> before the time-consuming operation and <code>JS_ResumeRequest</code> after. For more information about thread safety and requests, see <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_THREADSAFE" title="en/JS_THREADSAFE">JS_THREADSAFE</a></code>.</p>
<p><strong><code>JS_SuspendRequest</code></strong> suspends any currently active requests associated with the context <code>cx</code>. This allows the runtime to perform garbage collection if needed and allows other threads to access objects that the calling thread had locked. The return value is the number of nested requests that were suspended. It may be <code>0</code>.</p>
<p><strong><code>JS_ResumeRequest</code></strong> resumes the previously suspended requests. The <code>saveDepth</code> argument must be the value returned by the matching <code>JS_SuspendRequest</code> call. If <code>saveDepth</code> is nonzero and garbage collection is underway, <code>JS_ResumeRequest</code> blocks until the garbage collector is done.</p>
<p>{{ Jsapi_maxversion_inline(1.7) }} <code>JS_SuspendRequest</code> and <code>JS_ResumeRequest</code> are available only in <code><a href="/en/SpiderMonkey/JSAPI_Reference/JS_THREADSAFE" title="en/JS_THREADSAFE">JS_THREADSAFE</a></code> builds. In SpiderMonkey 1.8 and later, these functions will be present, but will do nothing, in non-<code>JS_THREADSAFE</code> builds.</p>
<p>{{ LXRSearch("ident", "i", "JS_SuspendRequest") }}<br />
  {{ LXRSearch("ident", "i", "JS_ResumeRequest") }}</p>
Revert to this revision