Implement vm_throw callback (#4726)

Slightly improve the description of vm_exec_stop callback.

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com

docs/02.API-REFERENCE.md

@@ -153,6 +153,7 @@ Possible compile time enabled feature types:
  - JERRY_FEATURE_SNAPSHOT_EXEC - executing snapshot files
  - JERRY_FEATURE_DEBUGGER - debugging
  - JERRY_FEATURE_VM_EXEC_STOP - stopping ECMAScript execution
+ - JERRY_FEATURE_VM_THROW - capturing ECMAScript throws
  - JERRY_FEATURE_JSON - JSON support
  - JERRY_FEATURE_PROMISE - promise support
  - JERRY_FEATURE_TYPEDARRAY - Typedarray support
@@ -1122,6 +1123,32 @@ typedef jerry_value_t (*jerry_vm_exec_stop_callback_t) (void *user_p);
 
 - [jerry_set_vm_exec_stop_callback](#jerry_set_vm_exec_stop_callback)
 
+## jerry_vm_throw_callback_t
+
+**Summary**
+
+Callback which is called when a value is thrown in an ECMAScript code. The callback
+should not change the `error_value`. The callback is not called again until the value
+is caught.
+
+Note:
+ - The engine considers errors thrown by external functions as never caught. The
+   application can maintain a status flag to ignore the next call of the callback
+   if necessary.
+   See: [jerry_create_external_function](#jerry_create_external_function)
+
+**Prototype**
+
+```c
+typedef void (*jerry_vm_throw_callback_t) (const jerry_value_t error_value, void *user_p);
+```
+
+*New in [[NEXT_RELEASE]]*.
+
+**See also**
+
+- [jerry_set_vm_throw_callback](#jerry_set_vm_throw_callback)
+
 ## jerry_promise_state_t
 
 Enum which describes the state of a Promise.
@@ -11329,8 +11356,7 @@ backtrace_callback (jerry_backtrace_frame_t *frame_p,
 
 **Summary**
 
-When JERRY_FEATURE_VM_EXEC_STOP is enabled a callback function can be
-specified by this function. This callback is periodically called when
+The callback passed to this function is periodically called when
 JerryScript executes an ECMAScript program.
 
 If the callback returns with undefined value the ECMAScript execution
@@ -11345,6 +11371,10 @@ 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.
 
+*Notes*:
+- This API depends on a build option (`JERRY_VM_EXEC_STOP`) and can be checked
+  in runtime with the `JERRY_FEATURE_VM_EXEC_STOP` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
 
 **Prototype**
 
@@ -11368,14 +11398,14 @@ jerry_set_vm_exec_stop_callback (jerry_vm_exec_stop_callback_t stop_cb,
 ```c
 #include "jerryscript.h"
 
-static int countdown = 10;
-
 static jerry_value_t
 vm_exec_stop_callback (void *user_p)
 {
-  while (countdown > 0)
+  int *countdown_p = (int *) user_p;
+
+  while (*countdown_p > 0)
   {
-    countdown--;
+    (*countdown_p)--;
     return jerry_create_undefined ();
   }
 
@@ -11388,6 +11418,7 @@ main (void)
 {
   jerry_init (JERRY_INIT_EMPTY);
 
+  int countdown = 10;
   jerry_set_vm_exec_stop_callback (vm_exec_stop_callback, &countdown, 16);
 
   // Infinite loop.
@@ -11402,12 +11433,77 @@ main (void)
 
 **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)
 
+## jerry_set_vm_throw_callback
+
+**Summary**
+
+The callback passed to this function is called when an error is thrown
+in ECMAScript code. The callback is not called again until the value is
+caught. See: [jerry_vm_throw_callback_t](#jerry_vm_throw_callback_t).
+
+*Notes*:
+- This API depends on a build option (`JERRY_VM_THROW`) and can be checked
+  in runtime with the `JERRY_FEATURE_VM_THROW` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+void
+jerry_set_vm_throw_callback (jerry_vm_throw_callback_t throw_cb,
+                             void *user_p);
+```
+
+- `throw_cb` - callback which is called on throws (passing NULL disables this feature)
+- `user_p` - user pointer passed to the `throw_cb` function
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include "jerryscript.h"
+
+static void
+vm_throw_callback (const jerry_value_t error_value, /**< captured error */
+                   void *user_p) /**< user pointer */
+{
+  (void) error_value;
+
+  /* Counts the number of throws. */
+  int *counter_p = (int *) user_p;
+  (*counter_p)++;
+}
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  int counter = 0;
+  jerry_set_vm_throw_callback (vm_throw_callback, &counter);
+
+  const jerry_char_t script[] = "try { throw new Error('1') } catch (e) { throw new Error('2') }";
+
+  jerry_value_t parsed_code = jerry_parse (script, sizeof (script) - 1, NULL);
+  jerry_release_value (jerry_run (parsed_code));
+  jerry_release_value (parsed_code);
+
+  /* The counter contains 2. */
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_vm_throw_callback_t](#jerry_vm_throw_callback_t)
+
 ## jerry_get_resource_name
 
 **Summary**