Update the webpage (#3319)

JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
2019-11-14 20:43:11 +01:00
parent 3731fbf0af
commit 5b86cf113e
2 changed files with 302 additions and 13 deletions
@@ -221,6 +221,17 @@ A value of 0 will use the default value.
 | CMake:  | `-DJERRY_GC_LIMIT=(int)`                     |
 | Python: | `--gc-limit=(int)`                           |

+### GC mark recursion limit
+
+This option can be used to adjust the maximum recursion depth during the GC mark phase. The provided value should be an integer, which represents the allowed number of recursive calls. Increasing the depth of the recursion reduces the time of GC cycles, however increases stack usage.
+A value of 0 will prevent any recursive GC calls.
+
+| Options |                                                   |
+|---------|---------------------------------------------------|
+| C:      | `-DJERRY_GC_MARK_LIMIT=(int)`                     |
+| CMake:  | `-DJERRY_GC_MARK_LIMIT=(int)`                     |
+| Python: | `--gc-mark-limit=(int)`                           |
+
 ### Stack limit

 This option can be used to cap the stack usage of the engine, and prevent stack overflows due to recursion. The provided value should be an integer, which represents the allowed stack usage in kilobytes.
@@ -306,9 +317,27 @@ These files can be directly compiled with an application using the JerryScript A
 For example with the following command:

 ```sh
-$ gcc -Wall -o demo_app demo_app.c gen_src/jerryscript.c gen_src/jerryscript-port-default.c jerryscript-libm.c -Igen_src/ 
+$ gcc -Wall -o demo_app demo_app.c gen_src/jerryscript.c gen_src/jerryscript-port-default.c jerryscript-libm.c -Igen_src/
 ```

 Please note that the headers must be available on the include path.

 In addition there is a `-DENABLE_ALL_IN_ONE_SOURCE=ON` CMake option to use this kind of sources during the build.
+
+# Target specific information
+
+## x86 with GCC
+
+When building for Intel 32 bit architecture it is possible that GCC uses conservative options, thus assuming the most
+basic floating-point support (that is it does not generate SSE or others instructions).
+However this could lead to loss off precision and/or different results than what is required by the JavaScript standard
+in regards of floating-point values and arithmetic.
+
+To resolve this precision problem it is advised to use at least SSE2.
+To do this with GCC please provide the `-mfpmath=sse -msse2` options during build.
+
+These options can also be specified via the `build.py` script:
+
+```sh
+$ ./tools/build.py --compile-flag=-mfpmath=sse --compile-flag=-msse2 --compile-flag=-m32
+```
@@ -326,6 +326,11 @@ Enum that contains the supported binary operation types
 - JERRY_BIN_OP_GREATER - greater relation (>)
 - JERRY_BIN_OP_GREATER_EQUAL - greater or equal relation (>=)
 - JERRY_BIN_OP_INSTANCEOF - instanceof operation
+ - JERRY_BIN_OP_ADD - addition operator (+)
+ - JERRY_BIN_OP_SUB - subtraction operator (-)
+ - JERRY_BIN_OP_MUL - multiplication operator (*)
+ - JERRY_BIN_OP_DIV - division operator (/)
+ - JERRY_BIN_OP_REM - remainder operator (%)

 *New in version 2.0*.

@@ -605,6 +610,22 @@ 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_promise_state_t
+
+Enum which describes the state of a Promise.
+
+Possible values:
+
+ - JERRY_PROMISE_STATE_NONE - Invalid/Unknown state (possibly called on a non-promise object).
+ - JERRY_PROMISE_STATE_PENDING - Promise is in "Pending" state.
+ - JERRY_PROMISE_STATE_FULFILLED - Promise is in "Fulfilled" state.
+ - JERRY_PROMISE_STATE_REJECTED - Promise is in "Rejected" state.
+
+*New in version [NEXT VERSION]*.
+
+**See also**
+
+- [jerry_get_promise_result](#jerry_get_promise_result)

 ## jerry_typedarray_type_t

@@ -3241,6 +3262,144 @@ jerry_value_to_string (const jerry_value_t value);

 These APIs all depend on the ES2015-subset profile (or on some build options).

+## jerry_get_promise_result
+
+**Summary**
+
+The function returns the result of a Promise object.
+
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+  is no longer needed.
+- This API depends on a build option (`JERRY_ES2015_BUILTIN_PROMISE`) and can be checked
+  in runtime with the `JERRY_FEATURE_PROMISE` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- The ES2015-subset profile enables this by default.
+
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_get_promise_result (const jerry_value_t promise);
+```
+
+- `promise` - the input Promise object.
+- return
+  - The result of the Promise.
+  - If the Promise is not resolved yet the result is the 'undefined' value.
+  - A TypeError is returned if the input argument was not a Promise object or
+    the Promise support was not built into the library.
+
+*New in version [NEXT VERSION]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include <jerryscript.h>
+
+static void
+example (void)
+{
+  // acquire/create a promise object.
+  jerry_value_t promise = jerry_create_promise ();
+  {
+    // prepare the argumnent for the resolve or reject.
+    jerry_value_t argument = jerry_create_number (33);
+
+    jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise,
+                                                           argument,
+                                                           true);
+    // 'is_ok' should be checked if it is an error or not.
+    // skipped in this example
+    jerry_release_value (is_ok);
+    jerry_release_value (argument);
+  }
+
+  jerry_value_t promise_result = jerry_get_promise_result (promise);
+  // 'promise_result' is now the number 33.
+
+  jerry_release_value (promise_result);
+  jerry_release_value (promise);
+}
+```
+
+**See also**
+
+- [jerry_create_promise](#jerry_create_promise)
+- [jerry_promise_state_t](#jerry_promise_state_t)
+
+## jerry_get_promise_state
+
+**Summary**
+
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+  is no longer needed.
+- This API depends on a build option (`JERRY_ES2015_BUILTIN_PROMISE`) and can be checked
+  in runtime with the `JERRY_FEATURE_PROMISE` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+- The ES2015-subset profile enables this by default.
+
+
+**Prototype**
+
+```c
+jerry_promise_state_t
+jerry_get_promise_state (const jerry_value_t promise);
+```
+
+- `promise` - the input promise object.
+- return
+  - [jerry_promise_state_t](#jerry_promise_state_t)
+  - `JERRY_PROMISE_STATE_NONE` is returned if the input argument was not a promise object or
+    the Promise support was not built into the library.
+
+*New in version [NEXT VERSION]*.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include <jerryscript.h>
+
+static void
+example (void)
+{
+  // acquire/create a promise object.
+  jerry_value_t promise = jerry_create_promise ();
+
+  jerry_promise_state_t start_state = jerry_get_promise_state (promise);
+  // a Promise have a default state of JERRY_PROMISE_STATE_PENDING
+
+  {
+    // prepare the argumnent for the resolve or reject.
+    jerry_value_t argument = jerry_create_number (33);
+
+    jerry_value_t is_ok = jerry_resolve_or_reject_promise (promise,
+                                                           argument,
+                                                           true);
+    // 'is_ok' should be checked if it is an error or not.
+    // skipped in this example
+    jerry_release_value (is_ok);
+    jerry_release_value (argument);
+  }
+
+  jerry_promise_state_t current_state = jerry_get_promise_state (promise);
+  // at this point the Promise should be in the JERRY_PROMISE_STATE_FULFILLED state.
+
+  jerry_release_value (promise);
+}
+```
+
+**See also**
+
+- [jerry_create_promise](#jerry_create_promise)
+- [jerry_promise_state_t](#jerry_promise_state_t)
+
 ## jerry_resolve_or_reject_promise

 **Summary**
@@ -4078,7 +4237,7 @@ jerry_value_t
 jerry_create_string (const jerry_char_t *str_p);
 ```

- `str_p` - pointer to string
+- `str_p` - non-null pointer to string
 - return value - value of the created string

 **Example**
@@ -4117,7 +4276,7 @@ jerry_create_string_sz (const jerry_char_t *str_p,
                        jerry_size_t str_size)
 ```

- `str_p` - pointer to string
+- `str_p` - non-null pointer to string
 - `str_size` - size of the string
 - return value - value of the created string

@@ -4148,8 +4307,9 @@ jerry_create_string_sz (const jerry_char_t *str_p,

 Create string from a valid UTF8 string.

-*Note*: The difference from [jerry_create_string](#jerry_create_string) is that it accepts utf-8 string instead of cesu-8 string.
-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+*Note*:
+ - The difference from [jerry_create_string](#jerry_create_string) is that it accepts utf-8 string instead of cesu-8 string.
+ - Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
 is no longer needed.

 **Prototype**
@@ -4159,7 +4319,7 @@ jerry_value_t
 jerry_create_string_from_utf8 (const jerry_char_t *str_p);
 ```

- `str_p` - pointer to string
+- `str_p` - non-null pointer to string
 - return value - value of the created string

 *New in version 2.0*.
@@ -4189,19 +4349,20 @@ jerry_create_string_from_utf8 (const jerry_char_t *str_p);

 Create string from a valid UTF8 string.

-*Note*: The difference from [jerry_create_string_sz](#jerry_create_string_sz) is that it accepts utf-8 string instead of cesu-8 string.
-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+*Note*:
+ - The difference from [jerry_create_string_sz](#jerry_create_string_sz) is that it accepts utf-8 string instead of cesu-8 string.
+ - Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
 is no longer needed.

 **Prototype**

 ```c
 jerry_value_t
-jerry_create_string_sz (const jerry_char_t *str_p,
-                        jerry_size_t str_size)
+jerry_create_string_sz_from_utf8 (const jerry_char_t *str_p,
+                                  jerry_size_t str_size)
 ```

- `str_p` - pointer to string
+- `str_p` - non-null pointer to string
 - `str_size` - size of the string
 - return value - value of the created string

@@ -7405,6 +7566,105 @@ main (void)
 - [jerry_create_external_function](#jerry_create_external_function)


+## jerry_get_resource_name
+
+**Summary**
+
+Get the resource name (usually a file name) of the currently executed script or the given function object.
+
+This function is typically called from native callbacks.
+
+*Notes*:
+- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
+is no longer needed.
+- This feature depends on build option (`JERRY_LINE_INFO`) and can be checked
+  in runtime with the `JERRY_FEATURE_LINE_INFO` feature enum value,
+  see: [jerry_is_feature_enabled](#jerry_is_feature_enabled).
+
+**Prototype**
+
+```c
+jerry_value_t
+jerry_get_resource_name (jerry_value_t value);
+```
+- `value` - api value to obtain the resource name from
+- return string value constructed from
+  - the currently executed function object's resource name, if the given value is undefined
+  - resource name of the function object, if the given value is a function object
+  - "<anonymous>", otherwise
+
+**Example**
+
+[doctest]: # (name="02.API-REFERENCE-jsresourcename.c")
+
+```c
+#include <stdio.h>
+#include <string.h>
+#include "jerryscript.h"
+
+static jerry_value_t
+resource_name_handler (const jerry_value_t function_obj,
+                       const jerry_value_t this_val,
+                       const jerry_value_t args_p[],
+                       const jerry_length_t args_count)
+{
+  jerry_value_t undefined_value = jerry_create_undefined ();
+  jerry_value_t resource_name = jerry_get_resource_name (args_count > 0 ? args_p[0] : undefined_value);
+  jerry_release_value (undefined_value);
+
+  return resource_name;
+} /* resource_name_handler */
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t global = jerry_get_global_object ();
+
+  /* Register the "resourceName" method. */
+  {
+    jerry_value_t func = jerry_create_external_function (resource_name_handler);
+    jerry_value_t name = jerry_create_string ((const jerry_char_t *) "resourceName");
+    jerry_value_t result = jerry_set_property (global, name, func);
+    jerry_release_value (result);
+    jerry_release_value (name);
+    jerry_release_value (func);
+  }
+
+  jerry_release_value (global);
+
+  const jerry_char_t source[] = "function myFunction() { return resourceName() }; myFunction()";
+  const jerry_char_t resource[] = "demo.js";
+
+  jerry_value_t program = jerry_parse (resource,
+                                       sizeof (resource) - 1,
+                                       source,
+                                       sizeof (source) - 1,
+                                       JERRY_PARSE_NO_OPTS);
+
+  if (!jerry_value_is_error (program))
+  {
+    /* `run_result` contains "demo.js" */
+    jerry_value_t run_result = jerry_run (program);
+
+    /* usage of `run_result` */
+
+    jerry_release_value (run_result);
+  }
+
+  jerry_release_value (program);
+  jerry_cleanup ();
+
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_create_external_function](#jerry_create_external_function)
+
+
 # ArrayBuffer and TypedArray functions

 These APIs all depend on the ES2015-subset profile.
@@ -7642,7 +7902,7 @@ Get if the ArrayBuffer is detachable.
 **Prototype**

 ```c
-jerry_value_t 
+jerry_value_t
 jerry_is_arraybuffer_detachable (const jerry_value_t value);
 ```

@@ -7683,7 +7943,7 @@ This operation requires the ArrayBuffer to be external that created by
 **Prototype**

 ```c
-jerry_value_t 
+jerry_value_t
 jerry_detach_arraybuffer (const jerry_value_t value);
 ```