From 09af6e670e4c19a1a5ac3e63ff8f3b965638ec93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zsolt=20Borb=C3=A9ly?= Date: Tue, 1 Oct 2019 20:06:28 +0200 Subject: [PATCH] Update the webpage (#3183) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com --- 01.CONFIGURATION.md | 15 ++++++++ 02.API-REFERENCE.md | 68 ++++++++++++++++++++++++--------- 03.API-EXAMPLE.md | 35 +++++++++++------ 07.DEBUGGER.md | 4 +- 10.EXT-REFERENCE-HANDLER.md | 3 ++ 11.EXT-REFERENCE-AUTORELEASE.md | 2 +- 12.EXT-REFERENCE-MODULE.md | 3 +- 7 files changed, 99 insertions(+), 31 deletions(-) diff --git a/01.CONFIGURATION.md b/01.CONFIGURATION.md index b19286c79..23f9e04cb 100644 --- a/01.CONFIGURATION.md +++ b/01.CONFIGURATION.md @@ -206,6 +206,21 @@ The default value is 512. | CMake: | `--DJERRY_GLOBAL_HEAP_SIZE=(int)` | | Python: | `--heap-size=(int)` | +### Garbage collection limit + +This option can be used to adjust the maximum allowed heap usage increase until triggering the next garbage collection, in bytes. +When the total allocated memory size reaches the current gc limit, garbage collection will be triggered to try and reduce clutter from unreachable objects. +If the total allocated memory can't be reduced below the current limit, then the limit will be increased by the amount specified via this option. +Similarly, when the total allocated memory goes well below the current gc limit, the limit is reduced by this amount. +The default value is 1/32 of the total heap size, but not greater than 8192 bytes. +A value of 0 will use the default value. + +| Options | | +|---------|----------------------------------------------| +| C: | `-DJERRY_GC_LIMIT=(int)` | +| CMake: | `-DJERRY_GC_LIMIT=(int)` | +| Python: | `--gc-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. diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index 29a8ac0db..da088d6cb 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -234,6 +234,7 @@ for the item by default, and if the `init_cb` field is not NULL, it will be call an additional custom initializer. The `deinit_cb` (if non-`NULL`) is called during a call to `jerry_cleanup ()` to run any custom deinitialization *before* the VM has been fully cleaned up. The `finalize_cb` (if non-`NULL`) is also called during a call to `jerry_cleanup ()` to run any custom deinitialization *after* the VM has been fully cleaned up. +If bytes_needed field is 0, no buffer is allocated for the manager, callback functions are called with NULL pointer. **Prototype** @@ -2800,7 +2801,7 @@ main (void) // Read the string into a byte buffer. jerry_size_t string_size = jerry_get_string_size (value); - jerry_char_t *string_buffer_p = (jerry_char_t *) malloc (sizeof (jerry_char_t) * string_size); + jerry_char_t *string_buffer_p = (jerry_char_t *) malloc (sizeof (jerry_char_t) * (string_size + 1)); jerry_size_t copied_bytes = jerry_string_to_char_buffer (value, string_buffer_p, string_size); string_buffer_p[copied_bytes] = '\0'; @@ -6434,7 +6435,7 @@ jerry_create_context (uint32_t heap_size, **Example** -[doctest]: # (test="compile") +[doctest]: # (test="compile", name="02.API-REFERENCE-create-context.c") ```c #include @@ -6515,8 +6516,12 @@ main (void) Generate snapshot from the specified source code. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it -is no longer needed. +*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_SNAPSHOT_SAVE`) and can be checked in runtime with + the `JERRY_FEATURE_SNAPSHOT_SAVE` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled). + If the feature is not enabled the function will return an error. **Prototype** @@ -6570,7 +6575,11 @@ main (void) global_mode_snapshot_buffer, sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t)); - size_t snapshot_size = (size_t) jerry_get_number_value (generate_result); + if (!jerry_value_is_error (generate_result)) + { + size_t snapshot_size = (size_t) jerry_get_number_value (generate_result); + } + jerry_release_value (generate_result); jerry_cleanup (); @@ -6596,8 +6605,12 @@ with the given arguments. The function arguments and function body are passed as separated arguments. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it -is no longer needed. +*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_SNAPSHOT_SAVE`) and can be checked in runtime with + the `JERRY_FEATURE_SNAPSHOT_SAVE` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled). + If the feature is not enabled the function will return an error. **Prototype** @@ -6658,7 +6671,11 @@ main (void) func_snapshot_buffer, sizeof (func_snapshot_buffer) / sizeof (uint32_t)); - size_t snapshot_size = (size_t) jerry_get_number_value (generate_result); + if (!jerry_value_is_error (generate_result)) + { + size_t snapshot_size = (size_t) jerry_get_number_value (generate_result); + } + jerry_release_value (generate_result); jerry_cleanup (); @@ -6680,8 +6697,12 @@ main (void) Execute snapshot from the specified buffer. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it -is no longer needed. +*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_SNAPSHOT_EXEC`) and can be checked in runtime with + the `JERRY_FEATURE_SNAPSHOT_EXEC` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled). + If the feature is not enabled the function will return an error. **Prototype** @@ -6693,13 +6714,13 @@ jerry_exec_snapshot (const uint32_t *snapshot_p, uint32_t exec_snapshot_opts); ``` -- `snapshot_p` - pointer to snapshot -- `snapshot_size` - size of snapshot in bytes -- `func_index` - index of executed function +- `snapshot_p` - pointer to snapshot. +- `snapshot_size` - size of snapshot in bytes. +- `func_index` - index of executed function. - `exec_snapshot_opts` - any combination of [jerry_exec_snapshot_opts_t](#jerry_exec_snapshot_opts_t) flags. - return value - - result of bytecode, if run was successful - - thrown error, otherwise + - result of bytecode, if run was successful. + - thrown error, otherwise (an error is reported if the snapshot execution feature is not enabled). *Changed in version 2.0*: Added `func_index` and `exec_snapshot_opts` arguments. Removed the `copy_bytecode` last argument. @@ -6726,6 +6747,7 @@ main (void) 0, global_mode_snapshot_buffer, sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t)); + // generate_result should be checked if it is an error or not size_t global_mode_snapshot_size = (size_t) jerry_get_number_value (generate_result); jerry_release_value (generate_result); @@ -6738,6 +6760,9 @@ main (void) global_mode_snapshot_size, 0, 0); + + // check the `res` value for error and process the result. + jerry_release_value (res); jerry_cleanup (); @@ -6760,8 +6785,12 @@ Load the selected snapshot function from the specified buffer as a function obje The lexical environment of the loaded function is always the global lexical environment. -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it -is no longer needed. +*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_SNAPSHOT_EXEC`) and can be checked in runtime with + the `JERRY_FEATURE_SNAPSHOT_EXEC` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled). + If the feature is not enabled the function will return an error. **Prototype** @@ -6856,6 +6885,11 @@ main (void) Collect the used literals from the given snapshot and save them into a buffer in list or C format. None of these literals are magic strings. In C format only valid identifiers are collected. +*Note*: +- This API depends on a build option (`JERRY_SNAPSHOT_SAVE`) and can be checked in runtime with + the `JERRY_FEATURE_SNAPSHOT_SAVE` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled). + If the feature is not enabled the function will return zero. + **Prototype** ```c diff --git a/03.API-EXAMPLE.md b/03.API-EXAMPLE.md index bfbb741d1..0f4b84293 100644 --- a/03.API-EXAMPLE.md +++ b/03.API-EXAMPLE.md @@ -644,14 +644,21 @@ print_value (const jerry_value_t jsvalue) /* String value */ else if (jerry_value_is_string (value)) { + jerry_char_t str_buf_p[256]; + /* Determining required buffer size */ jerry_size_t req_sz = jerry_get_string_size (value); - jerry_char_t str_buf_p[req_sz + 1]; - jerry_string_to_char_buffer (value, str_buf_p, req_sz); - str_buf_p[req_sz] = '\0'; - - printf ("%s", (const char *) str_buf_p); + if (req_sz <= 255) + { + jerry_string_to_char_buffer (value, str_buf_p, req_sz); + str_buf_p[req_sz] = '\0'; + printf ("%s", (const char *) str_buf_p); + } + else + { + printf ("error: buffer isn't big enough"); + } } /* Object reference */ else if (jerry_value_is_object (value)) @@ -731,14 +738,21 @@ print_value (const jerry_value_t jsvalue) /* String value */ else if (jerry_value_is_string (value)) { + jerry_char_t str_buf_p[256]; + /* Determining required buffer size */ jerry_size_t req_sz = jerry_get_string_size (value); - jerry_char_t str_buf_p[req_sz + 1]; - jerry_string_to_char_buffer (value, str_buf_p, req_sz); - str_buf_p[req_sz] = '\0'; - - printf ("%s", (const char *) str_buf_p); + if (req_sz <= 255) + { + jerry_string_to_char_buffer (value, str_buf_p, req_sz); + str_buf_p[req_sz] = '\0'; + printf ("%s", (const char *) str_buf_p); + } + else + { + printf ("error: buffer isn't big enough"); + } } /* Object reference */ else if (jerry_value_is_object (value)) @@ -747,7 +761,6 @@ print_value (const jerry_value_t jsvalue) } printf ("\n"); - jerry_release_value (value); } diff --git a/07.DEBUGGER.md b/07.DEBUGGER.md index fb36224ec..9c342b968 100644 --- a/07.DEBUGGER.md +++ b/07.DEBUGGER.md @@ -320,8 +320,10 @@ wait_for_source_callback (const jerry_char_t *resource_name_p, /**< resource nam size_t resource_name_size, /**< size of resource name */ const jerry_char_t *source_p, /**< source code */ size_t source_size, /**< source code size */ - void *user_p __attribute__((unused))) /**< user pointer */ + void *user_p /**< user pointer */) { + (void) user_p; + jerry_value_t ret_val = jerry_parse (resource_name_p, resource_name_size, source_p, diff --git a/10.EXT-REFERENCE-HANDLER.md b/10.EXT-REFERENCE-HANDLER.md index d46961cc5..9bca3e918 100644 --- a/10.EXT-REFERENCE-HANDLER.md +++ b/10.EXT-REFERENCE-HANDLER.md @@ -431,6 +431,9 @@ For example usage see [jerryx_set_properties](#jerryx_set_properties). Hard assert for scripts. The routine calls `jerry_port_fatal` on assertion failure. +If the `JERRY_FEATURE_LINE_INFO` runtime feature is enabled (build option: `JERRY_LINE_INFO`) +a backtrace is also printed out. + **Prototype** ```c diff --git a/11.EXT-REFERENCE-AUTORELEASE.md b/11.EXT-REFERENCE-AUTORELEASE.md index f46970504..b0392e0ec 100644 --- a/11.EXT-REFERENCE-AUTORELEASE.md +++ b/11.EXT-REFERENCE-AUTORELEASE.md @@ -22,7 +22,7 @@ using the `__cleanup__` variable attribute. For other compilers, no support has **Example** -[doctest]: # (test="compile") +[doctest]: # (test="compile", name="11.EXT-REFERENCE-AUTORELEASE.c") ```c #include "jerryscript.h" diff --git a/12.EXT-REFERENCE-MODULE.md b/12.EXT-REFERENCE-MODULE.md index 92569533b..fd29f4dda 100644 --- a/12.EXT-REFERENCE-MODULE.md +++ b/12.EXT-REFERENCE-MODULE.md @@ -47,7 +47,8 @@ resolved using the native JerryScript module resolver `jerryx_module_native_reso `jerryx_module_resolve()`. Native modules are registered during application startup and by calling `dlopen()` by means of library constructors, support for which can be turned on using the `FEATURE_INIT_FINI` build flag. In the absence of such a flag, the module registration and unregistration functions are exposed as global symbols which can be called -explicitly. +explicitly. Note: `FEATURE_INIT_FINI` build flag isn't supported on Windows, because Microsoft Visual C/C++ Compiler +doesn't support library constructors and destructors. ## jerryx_module_resolve