Support ECMAScript stopping in JerryScript. (#1753)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com
2017-04-28 14:19:23 +02:00
parent 0e38356e5b
commit 894aa6d036
9 changed files with 279 additions and 2 deletions
@@ -36,6 +36,7 @@ Possible compile time enabled feature types:
 - JERRY_FEATURE_SNAPSHOT_SAVE - saving snapshot files
 - JERRY_FEATURE_SNAPSHOT_EXEC - executing snapshot files
 - JERRY_FEATURE_DEBUGGER - debugging
+ - JERRY_FEATURE_VM_EXEC_STOP - stopping ECMAScript execution

 ## jerry_char_t

@@ -234,6 +235,28 @@ typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_na
                                                 void *user_data_p);
 ```

+## jerry_vm_exec_stop_callback_t
+
+**Summary**
+
+Callback which tells whether the ECMAScript execution should be stopped.
+If it returns with undefined value the ECMAScript execution continues.
+Otherwise the result is thrown by the engine (if the error flag is not
+set for the returned value the engine automatically sets it). The
+callback function might be called again even if it threw an error.
+In this case the function must throw the same error again.
+
+**Prototype**
+
+```c
+typedef jerry_value_t (*jerry_vm_exec_stop_callback_t) (void *user_p);
+```
+
+**See also**
+
+- [jerry_set_vm_exec_stop_callback](#jerry_set_vm_exec_stop_callback)
+
+
 # General engine functions

 ## jerry_init
@@ -3896,3 +3919,81 @@ jerry_parse_and_save_literals (const jerry_char_t *source_p,
 - [jerry_init](#jerry_init)
 - [jerry_cleanup](#jerry_cleanup)
 - [jerry_register_magic_strings](#jerry_register_magic_strings)
+
+
+# Miscellaneous functions
+
+## jerry_set_vm_exec_stop_callback
+
+**Summary**
+
+When JERRY_FEATURE_VM_EXEC_STOP is enabled a callback function can be
+specified by this function. This callback is periodically called when
+JerryScript executes an ECMAScript program.
+
+If the callback returns with undefined value the ECMAScript execution
+continues. Otherwise the result is thrown by the engine (if the error
+flag is not set for the returned value the engine automatically sets
+it). The callback function might be called again even if it threw
+an error. In this case the function must throw the same error again.
+
+To reduce the CPU overhead of constantly checking the termination
+condition the callback is called when a backward jump is executed
+or an exception is caught. Setting the `frequency` to a greater
+than `1` value reduces this overhead further. If its value is N
+only every Nth event (backward jump, etc.) trigger the next check.
+
+
+**Prototype**
+
+```c
+void
+jerry_set_vm_exec_stop_callback (jerry_vm_exec_stop_callback_t stop_cb,
+                                 void *user_p,
+                                 uint32_t frequency);
+```
+
+- `stop_cb` - periodically called callback (passing NULL disables this feature)
+- `user_p` - user pointer passed to the `stop_cb` function
+- `frequency` - frequency of calling the `stop_cb` function
+
+**Example**
+
+```c
+static jerry_value_t
+vm_exec_stop_callback (void *user_p)
+{
+  static int countdown = 10;
+
+  while (countdown > 0)
+  {
+    countdown--;
+    return jerry_create_undefined ();
+  }
+
+  // The error flag is added automatically.
+  return jerry_create_string ((const jerry_char_t *) "Abort script");
+}
+
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_set_vm_exec_stop_callback (vm_exec_stop_callback, &countdown, 16);
+
+  // Inifinte loop.
+  const char *src_p = "while(true) {}";
+
+  jerry_value_t src = jerry_parse ((jerry_char_t *) src_p, strlen (src_p), false);
+  jerry_release_value (jerry_run (src));
+  jerry_release_value (src);
+  jerry_cleanup ();
+}
+```
+
+**See also**
+
+- [jerry_init](#jerry_init)
+- [jerry_cleanup](#jerry_cleanup)
+- [jerry_parse](#jerry_parse)
+- [jerry_run](#jerry_run)
+- [jerry_vm_exec_stop_callback_t](#jerry_vm_exec_stop_callback_t)