diff docs/rendered/_sources/pymonkey.txt @ 115:f4c550369332

Added documentation for gc() and operation callback functions.
author Atul Varma <varmaa@toolness.com>
date Mon, 17 Aug 2009 03:33:40 -0700
parents 87147faa031a
children 06269ca0b36c
line wrap: on
line diff
--- a/docs/rendered/_sources/pymonkey.txt	Mon Aug 17 03:02:51 2009 -0700
+++ b/docs/rendered/_sources/pymonkey.txt	Mon Aug 17 03:33:40 2009 -0700
@@ -76,13 +76,13 @@
       stored within the new JS object; it can be retrieved using
       :meth:`get_object_private()`.
 
-   .. method:: new_function(callable, name)
+   .. method:: new_function(func, name)
 
       Creates a new :class:`Function` instance that wraps the
       given Python callable.  In JS-land, the function will
       have the given name.
 
-      When the function is executed from JavaScript, `callable`
+      When the function is executed from JavaScript, `func`
       will be passed three positional arguments.
 
       The first argument is a :class:`Context` that represents the
@@ -196,6 +196,47 @@
       <https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JS_InitStandardClasses>`_,
       which this method wraps.
 
+   .. method:: gc()
+
+      Performs garbage collection on the context's JavaScript runtime.
+
+   .. method:: set_operation_callback(func)
+
+      Sets the operation callback for the context to the given Python
+      callable. The callback can be triggered via
+      :meth:`trigger_operation_callback()`.
+
+      `func` takes one argument: the context that triggered it.
+
+   .. method:: trigger_operation_callback()
+
+      Triggers the context's operation callback. If no callback has
+      yet been set, this function does nothing.
+
+      This function is one of the few thread-safe functions available
+      to a JS runtime, and together with
+      :meth:`set_operation_callback()` can be used to abort the
+      execution of long-running code.
+
+      For instance:
+
+        >>> import time, threading
+        >>> cx = pymonkey.Runtime().new_context()
+        >>> def stop_running_code(cx):
+        ...   raise Exception('JS took too long to execute.')
+        >>> cx.set_operation_callback(stop_running_code)
+        >>> def watchdog_thread():
+        ...   time.sleep(0.1)
+        ...   cx.trigger_operation_callback()
+        >>> thread = threading.Thread(target=watchdog_thread)
+        >>> thread.start()
+        >>> try:
+        ...   cx.evaluate_script(cx.new_object(), 'while (1) {}',
+        ...                      '<string>', 1)
+        ... except pymonkey.error, e:
+        ...   print cx.get_object_private(e.args[0])
+        JS took too long to execute.
+
 .. class:: Runtime()
 
    Creates a new JavaScript runtime. JS objects created by the runtime