Add notification callback for Promise operations (#4595)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com
2021-02-18 11:29:52 +01:00
parent c14702c129
commit 01e0388d77
18 changed files with 703 additions and 46 deletions
@@ -53,6 +53,17 @@ To see how a profile file should be created, or what configuration options are a
 | CMake:  | `-DJERRY_PROFILE="path"`                     |
 | Python: | `--profile="path"`                           |

+### Promise callback
+
+Enables Promise event notification support. This feature allows setting a user callback, which is called when certain Promise related events occur such as
+creating a new Promise, resolving a Promise with a value, etc.
+
+| Options |                                              |
+|---------|----------------------------------------------|
+| C:      | `-DJERRY_PROMISE_CALLBACK=0/1`               |
+| CMake:  | `-DJERRY_PROMISE_CALLBACK=ON/OFF`            |
+| Python: | `--promise-callback=ON/OFF`                  |
+
 ### External context

 Enables external context support in the engine. By default, JerryScript uses a statically allocated context to store the current state of the engine internals.
@@ -157,6 +157,8 @@ Possible compile time enabled feature types:
 - JERRY_FEATURE_WEAKSET - WeakSet support
 - JERRY_FEATURE_BIGINT - BigInt support
 - JERRY_FEATURE_REALM - realm support
+ - JERRY_FEATURE_GLOBAL_THIS - GlobalThisValue support
+ - JERRY_FEATURE_PROMISE_CALLBACK - Promise callback support

 *New in version 2.0*.

@@ -164,6 +166,8 @@ Possible compile time enabled feature types:

 *Changed in version 2.4*: Added `JERRY_FEATURE_BIGINT`, `JERRY_FEATURE_REALM` values.

+*Changed in version [[NEXT_RELEASE]]*: Added `JERRY_FEATURE_GLOBAL_THIS`, `JERRY_FEATURE_PROMISE_CALLBACK` values.
+
 ## jerry_container_type_t

 Container object types:
@@ -883,6 +887,80 @@ Possible values:

 - [jerry_get_promise_result](#jerry_get_promise_result)

+## jerry_promise_event_type_t
+
+Event types for [jerry_promise_callback_t](#jerry_promise_callback_t) callback function.
+The description of the `object` and `value` arguments are provided for each type.
+
+Possible values:
+
+- JERRY_PROMISE_EVENT_CREATE - A new Promise object is created.
+  - object - the new Promise object
+  - value - parent Promise for `then` chains, undefined otherwise.
+- JERRY_PROMISE_EVENT_RESOLVE - Called when a Promise is about to be resolved.
+  - object - the Promise object
+  - value - value for resolving.
+- JERRY_PROMISE_EVENT_REJECT - Called when a Promise is about to be rejected.
+  - object - the Promise object
+  - value - value for rejecting.
+- JERRY_PROMISE_EVENT_BEFORE_REACTION_JOB - Called before executing a Promise reaction job.
+  - object - the Promise object
+  - value - undefined
+- JERRY_PROMISE_EVENT_AFTER_REACTION_JOB - Called after a Promise reaction job is completed.
+  - object - the Promise object
+  - value - undefined
+- JERRY_PROMISE_EVENT_ASYNC_AWAIT - Called when an async function awaits the result of a Promise object.
+  - object - internal object representing the execution status
+  - value - the Promise object
+- JERRY_PROMISE_EVENT_ASYNC_BEFORE_RESOLVE - Called when an async function is continued with resolve.
+  - object - internal object representing the execution status
+  - value - value for resolving
+- JERRY_PROMISE_EVENT_ASYNC_BEFORE_REJECT - Called when an async function is continued with reject.
+  - object - internal object representing the execution status
+  - value - value for rejecting
+- JERRY_PROMISE_EVENT_ASYNC_AFTER_RESOLVE - Called when an async function resolve is completed.
+  - object - internal object representing the execution status
+  - value - value for resolving
+- JERRY_PROMISE_EVENT_ASYNC_AFTER_REJECT - Called when an async function reject is completed.
+  - object - internal object representing the execution status
+  - value - value for rejecting
+
+*New in version [[NEXT_RELEASE]]*.
+
+**See also**
+
+- [jerry_promise_callback_t](#jerry_promise_callback_t)
+- [jerry_promise_set_callback](#jerry_promise_set_callback)
+
+
+## jerry_promise_callback_t
+
+**Summary**
+
+Notification callback for tracking Promise and async function operations. The arguments
+passed to the callback depends on the `event_type` which is detailed in the
+description of [jerry_promise_event_type_t](#jerry_promise_event_type_t).
+
+**Prototype**
+
+```c
+typedef void (*jerry_promise_callback_t) (jerry_promise_event_type_t event_type,
+                                          const jerry_value_t object, const jerry_value_t value,
+                                          void *user_p);
+```
+
+- `event_type` - type of the event notification.
+- `object` - object corresponding to the event.
+- `value` - optional value argument.
+- `user_data_p` - optional user data pointer supplied via the (jerry_promise_set_callback)[#jerry_promise_set_callback] method.
+
+*New in version [[NEXT_RELEASE]]*.
+
+**See also**
+
+- [jerry_promise_event_type_t](#jerry_promise_event_type_t)
+- [jerry_promise_set_callback](#jerry_promise_set_callback)
+
 ## jerry_typedarray_type_t

 Enum which describes the TypedArray types.
@@ -4213,6 +4291,79 @@ example (void)
 - [jerry_create_promise](#jerry_create_promise)
 - [jerry_promise_state_t](#jerry_promise_state_t)

+## jerry_promise_set_callback
+
+**Summary**
+
+Sets a callback for tracking Promise and async operations.
+
+*Notes*:
+- This API depends on a build option (`JERRY_PROMISE_CALLBACK`) and can be checked
+  in runtime with the `JERRY_FEATURE_PROMISE_CALLBACK` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+
+**Prototype**
+
+```c
+void jerry_promise_set_callback (jerry_promise_callback_t callback, void *user_p);
+```
+
+- `callback` - callback function, the previously set value is overwritten,
+               and setting NULL disables the tracking
+- `user_p` - pointer passed to the callback function, can be NULL
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include <stdio.h>
+#include <string.h>
+#include "jerryscript.h"
+
+static void
+promise_callback (jerry_promise_event_type_t event_type, /**< event type */
+                  const jerry_value_t object, /**< target object */
+                  const jerry_value_t value, /**< optional argument */
+                  void *user_p) /**< user pointer passed to the callback */
+{
+  if (event_type == JERRY_PROMISE_EVENT_CREATE)
+  {
+    printf ("A new promise is created\n");
+
+    if (!jerry_value_is_undefined (value))
+    {
+      printf ("  The Promise is created by Promise.then() built-in.\n");
+    }
+  }
+} /* promise_callback */
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_promise_set_callback (promise_callback, NULL);
+
+  const char *source_p = "var p = Promise.resolve(0)\n"
+                         "p.then(function (v) { return v; })";
+  jerry_release_value (jerry_eval ((const jerry_char_t *) source_p,
+                                   strlen (source_p),
+                                   JERRY_PARSE_NO_OPTS));
+
+  jerry_cleanup ();
+  return 0;
+} /* main */
+```
+
+**See also**
+
+- [jerry_create_promise](#jerry_create_promise)
+- [jerry_promise_state_t](#jerry_promise_state_t)
+
 ## jerry_from_property_descriptor

 **Summary**