Add promise C API (#1796)

Add API: jerry_create_promise, jerry_value_is_promise and jerry_resolve_or_reject_promise. related issue: 1794 JerryScript-DCO-1.0-Signed-off-by: Zidong Jiang zidong.jiang@intel.com
2017-05-04 16:13:26 +08:00
parent 240411771a
commit ede13835b2
11 changed files with 457 additions and 24 deletions
@@ -1072,6 +1072,47 @@ jerry_value_is_object (const jerry_value_t value)
 - [jerry_release_value](#jerry_release_value)


+## jerry_value_is_promise
+
+**Summary**
+
+Returns whether the given `jerry_value_t` is a promise value.
+
+*Note*: This API depends on the ES2015-subset profile.
+
+**Prototype**
+
+```c
+bool
+jerry_value_is_promise (const jerry_value_t value)
+```
+
+- `value` - api value
+- return value
+  - true, if the given `jerry_value_t` is a promise
+  - false, otherwise
+
+**Example**
+
+```c
+{
+  jerry_value_t value;
+  ... // create or acquire value
+
+  if (jerry_value_is_promise (value))
+  {
+    ...
+  }
+
+  jerry_release_value (value);
+}
+```
+
+**See also**
+
+- [jerry_release_value](#jerry_release_value)
+
+
 ## jerry_value_is_string

 **Summary**
@@ -1980,6 +2021,64 @@ jerry_value_to_string (const jerry_value_t value);
 - [jerry_value_to_primitive](#jerry_value_to_primitive)


+# Functions for promise objects
+
+These APIs all depends on the ES2015-subset profile.
+
+## jerry_resolve_or_reject_promise
+
+**Summary**
+
+Resolve or reject the promise with an argument.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_resolve_or_reject_promise (jerry_value_t promise,
+                                 jerry_value_t argument,
+                                 bool is_resolve)
+```
+
+- `promise` - the promise value
+- `argument` - the argument for resolve or reject
+- `is_resolve` - whether the promise should be resolved or rejected
+- return value
+  - undefined jerry value - resolve or reject successed
+  - jerry value with error flag - otherwise
+
+**Example**
+
+```c
+{
+  jerry_value_t promise = ... // acquire/create a promise object.
+
+  ...
+
+  bool is_resolve = ... // whether the promise should be resolved or rejected
+  jerry_value_t argument = ... // prepare the argumnent for the resolve or reject.
+
+  jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise,
+                                                         argument,
+                                                         is_resolve);
+
+  if (jerry_value_has_error_flag (is_ok))
+  {
+    // handle the error.
+  }
+
+  jerry_release_value (is_ok);
+  jerry_release_value (argument);
+  jerry_release_value (promise);
+}
+```
+
+**See also**
+
+- [jerry_release_value](#jerry_release_value)
+- [jerry_value_has_error_flag](#jerry_value_has_error_flag)
+
+
 # Acquire and release API values

 ## jerry_acquire_value
@@ -2425,6 +2524,41 @@ jerry_create_object (void);
 - [jerry_release_value](#jerry_release_value)


+## jerry_create_promise
+
+**Summary**
+
+Create an empty promise object which can be resolved or rejected later
+by calling jerry_resolve_or_reject_promise.
+
+*Note*: This API depends on the ES2015-subset profile.
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_create_promise (void)
+```
+
+- return value - value of the newly created promise
+
+**Example**
+
+```c
+{
+  jerry_value_t p = jerry_create_promise ();
+
+  ...// usage of the promise
+
+  jerry_release_value (p);
+}
+
+**See also**
+
+- [jerry_resolve_or_reject_promise](#jerry_resolve_or_reject_promise)
+- [jerry_release_value](#jerry_release_value)
+
+
 ## jerry_create_string

 **Summary**
@@ -3528,7 +3662,7 @@ static const jerry_object_native_info_t native_obj_type_info =
    {
      // The type of this's native pointer matches what is expected.
      // Only now is it safe to cast to native_obj_t * and dereference the
-      // pointer: 
+      // pointer:
      native_obj_t *native_obj = native_p;
      native_obj->bar = ...; // Safe to access now!
    }
@@ -3582,7 +3716,7 @@ jerry_set_object_native_pointer (const jerry_value_t obj_val,
 **Example**

 See [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) for a
-best-practice example. 
+best-practice example.

 **See also**