Update the webpage (#1820)

* Add docs of extensions * Use `category` to distinct dropdown pages * Sort the documents alphabetical JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
2017-05-15 08:42:18 +02:00
parent 13a04be79c
commit 5d2b25659d
11 changed files with 874 additions and 47 deletions
@@ -1,6 +1,7 @@
 ---
 layout: page
 title: API Reference
+category: navbar
 permalink: /api-reference/
 ---

@@ -45,6 +46,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

@@ -243,6 +245,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
@@ -1058,6 +1082,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**
@@ -1966,6 +2031,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
@@ -2411,6 +2534,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**
@@ -3514,7 +3672,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!
    }
@@ -3568,7 +3726,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**

@@ -3905,3 +4063,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)