From dc124583829f79bcc8c93918567424e25693e95d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=A1szl=C3=B3=20Lang=C3=B3?= Date: Thu, 19 Apr 2018 14:31:04 +0200 Subject: [PATCH] Update the webpage (#2289) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit JerryScript-DCO-1.0-Signed-off-by: László Langó llango.u-szeged@partner.samsung.com --- 02.API-REFERENCE.md | 730 +++++++++++++++++++++++++++++------------ 03.API-EXAMPLE.md | 2 +- 04.INTERNALS.md | 2 +- 05.PORT-API.md | 38 +++ 07.DEBUGGER.md | 21 +- 08.CODING-STANDARDS.md | 2 +- 6 files changed, 577 insertions(+), 218 deletions(-) diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index 74e3ce425..064dfd51d 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -63,6 +63,69 @@ Possible compile time enabled feature types: - JERRY_FEATURE_SNAPSHOT_EXEC - executing snapshot files - JERRY_FEATURE_DEBUGGER - debugging - JERRY_FEATURE_VM_EXEC_STOP - stopping ECMAScript execution + - JERRY_FEATURE_JSON - JSON support + - JERRY_FEATURE_PROMISE - promise support + - JERRY_FEATURE_TYPEDARRAY - Typedarray support + - JERRY_FEATURE_DATE - Date support + - JERRY_FEATURE_REGEXP - RegExp support + - JERRY_FEATURE_LINE_INFO - line info available + +## jerry_parse_opts_t + +Option bits for [jerry_parse](#jerry_parse) and +[jerry_parse_function](#jerry_parse_function) functions: + + - JERRY_PARSE_NO_OPTS - no options passed + - JERRY_PARSE_STRICT_MODE - enable strict mode + +## jerry_generate_snapshot_opts_t + +Flags for [jerry_generate_snapshot](#jerry_generate_snapshot) and +[jerry_generate_function_snapshot](#jerry_generate_function_snapshot) functions: + + - JERRY_SNAPSHOT_SAVE_STATIC - generate static snapshot (see below) + - JERRY_SNAPSHOT_SAVE_STRICT - strict source code provided + +**Generate static snapshots** +Snapshots contain literal pools, and these literal pools contain references +to constant literals (strings, numbers, etc.). When a snapshot is executed, +these literals are converted to jerry values and the literal pool entries +are changed to their corresponding jerry value. To support this conversion, +the literals and literal pools are copied into RAM even if the +`JERRY_SNAPSHOT_EXEC_COPY_DATA` option is passed to +[jerry_exec_snapshot](#jerry_exec_snapshot). This non-negligible memory +consumption can be avoided by using static snapshots. The literals of +these snapshots are limited to magic strings and 28 bit signed integers, +so their constant pools do not need to be loaded into the memory. +Hence these snapshots can be executed from ROM. + +***Important note:*** The [jerry_exec_snapshot](#jerry_exec_snapshot) +function rejects static snaphots unless the `JERRY_SNAPSHOT_EXEC_ALLOW_STATIC` +option bit is set. The caller must also ensure that the same magic +strings are set by [jerry_register_magic_strings](#jerry_register_magic_strings) +when the snapshot is generated and executed. Furthermore the +`JERRY_SNAPSHOT_EXEC_COPY_DATA` option is not allowed. + +## jerry_exec_snapshot_opts_t + +Flags for [jerry_exec_snapshot](#jerry_exec_snapshot) and +[jerry_load_function_snapshot](#jerry_load_function_snapshot) functions: + + - JERRY_SNAPSHOT_EXEC_COPY_DATA - copy snapshot data into memory (see below) + - JERRY_SNAPSHOT_EXEC_ALLOW_STATIC - allow executing static snapshots + +**Copy snapshot data into memory** + +By default the snapshot buffer is expected to be present in memory until +[jerry_cleanup](#jerry_cleanup) is called. For example `static const` buffers +compiled into the application binary satisfy this requirement. + +If the snapshot buffer is freed after [jerry_exec_snapshot](#jerry_exec_snapshot) +is called the `JERRY_SNAPSHOT_EXEC_COPY_DATA` must be passed to copy the necessary +parts of the snapshot buffer into memory. + +The `JERRY_SNAPSHOT_EXEC_COPY_DATA` option is not allowed for static snapshots. + ## jerry_char_t @@ -132,17 +195,54 @@ typedef uint32_t jerry_value_t; **Summary** Structure that defines how a context data item will be initialized and deinitialized. JerryScript zeroes out the memory -for the item by default, and if the `init_cb` field is not NULL, it will be called with the pointer to the memory as -an additional custom initializer. +for the item by default, and if the `init_cb` field is not NULL, it will be called with the pointer to the memory as +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. **Prototype** ```c typedef struct { - void (*init_cb) (void *); /**< callback responsible for initializing a context item, or NULL */ - void (*deinit_cb) (void *); /**< callback responsible for deinitializing a context item */ - size_t bytes_needed; /**< number of bytes to allocate for this manager */ + /** + * Callback responsible for initializing a context item, or NULL to zero out the memory. This is called lazily, the + * first time jerry_get_context_data () is called with this manager. + * + * @param [in] data The buffer that JerryScript allocated for the manager. The buffer is zeroed out. The size is + * determined by the bytes_needed field. The buffer is kept alive until jerry_cleanup () is called. + */ + void (*init_cb) (void *data); + + /** + * Callback responsible for deinitializing a context item, or NULL. This is called as part of jerry_cleanup (), + * right *before* the VM has been cleaned up. This is a good place to release strong references to jerry_value_t's + * that the manager may be holding. + * Note: because the VM has not been fully cleaned up yet, jerry_object_native_info_t free_cb's can still get called + * *after* all deinit_cb's have been run. See finalize_cb for a callback that is guaranteed to run *after* all + * free_cb's have been run. + * + * @param [in] data The buffer that JerryScript allocated for the manager. + */ + void (*deinit_cb) (void *data); + + /** + * Callback responsible for finalizing a context item, or NULL. This is called as part of jerry_cleanup (), + * right *after* the VM has been cleaned up and destroyed and jerry_... APIs cannot be called any more. At this point, + * all values in the VM have been cleaned up. This is a good place to clean up native state that can only be cleaned + * up at the very end when there are no more VM values around that may need to access that state. + * + * @param [in] data The buffer that JerryScript allocated for the manager. After returning from this callback, + * the data pointer may no longer be used. + */ + void (*finalize_cb) (void *data); + + /** + * Number of bytes to allocate for this manager. This is the size of the buffer that JerryScript will allocate on + * behalf of the manager. The pointer to this buffer is passed into init_cb, deinit_cb and finalize_cb. It is also + * returned from the jerry_get_context_data () API. + */ + size_t bytes_needed; } jerry_context_data_manager_t; ``` @@ -300,6 +400,33 @@ typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_na void *user_data_p); ``` +## jerry_objects_foreach_t + +**Summary** + +Function type applied for each object in the engine + +**Prototype** + +```c +typedef bool (*jerry_objects_foreach_t) (const jerry_value_t object, + void *user_data_p); +``` + +## jerry_objects_foreach_by_native_info_t + +**Summary** + +Function type applied for each matching object in the engine + +**Prototype** + +```c +typedef bool (*jerry_objects_foreach_by_native_info_t) (const jerry_value_t object, + void *object_data_p, + void *user_data_p); +``` + ## jerry_vm_exec_stop_callback_t **Summary** @@ -698,8 +825,9 @@ main (void) **Summary** -Parse script and construct an EcmaScript function. The -lexical environment is set to the global lexical environment. +Parse script and construct an EcmaScript function. The lexical environment is +set to the global lexical environment. The resource name can be used by +debugging systems to provide line / backtrace info. *Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. @@ -708,14 +836,18 @@ is no longer needed. ```c jerry_value_t -jerry_parse (const jerry_char_t *source_p, +jerry_parse (const jerry_char_t *resource_name_p, /**< resource name (usually a file name) */ + size_t resource_name_length, /**< length of resource name */ + const jerry_char_t *source_p, size_t source_size, - bool is_strict); + uint32_t parse_opts); ``` +- `resource_name_p` - resource name, usually a file name (must be a valid UTF8 string). +- `resource_name_length` - size of the resource name, in bytes. - `source_p` - string, containing source code to parse (must be a valid UTF8 string). - `source_size` - size of the string, in bytes. -- `is_strict` - defines strict mode. +- `parse_opts` - any combination of [jerry_parse_opts_t](#jerry_parse_opts_t) flags. - return value - function object value, if script was parsed successfully, - thrown error, otherwise @@ -736,7 +868,7 @@ main (void) const jerry_char_t script[] = "print ('Hello, World!');"; size_t script_size = strlen ((const char *) script); - jerry_value_t parsed_code = jerry_parse (script, script_size, false); + jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS); jerry_release_value (parsed_code); jerry_cleanup (); @@ -747,40 +879,6 @@ main (void) - [jerry_run](#jerry_run) -## jerry_parse_named_resource - -**Summary** - -Parse script and construct an ECMAScript function. The lexical -environment is set to the global lexical environment. The resource -name (usually a file name) is also passed to this function which is -used by the debugger to find the source code. - -*Note*: The returned value must be freed with [jerry_release_value](#jerry_release_value) when it -is no longer needed. - -**Prototype** - -```c -jerry_value_t -jerry_parse_named_resource (const jerry_char_t *resource_name_p, /**< resource name (usually a file name) */ - size_t resource_name_length, /**< length of resource name */ - const jerry_char_t *source_p, /**< script source */ - size_t source_size, /**< script source size */ - bool is_strict) /**< strict mode */ -``` - -- `resource_name_p` - resource name, usually a file name (must be a valid UTF8 string). -- `resource_name_length` - size of the resource name, in bytes. -- `source_p` - string, containing source code to parse (must be a valid UTF8 string). -- `source_size` - size of the string, in bytes. -- `is_strict` - defines strict mode. -- return value - - function object value, if script was parsed successfully, - - thrown error, otherwise - -This function is identical to [jerry_parse](#jerry_parse), except that an additional filename parameter has been added. - ## jerry_parse_function **Summary** @@ -805,7 +903,7 @@ jerry_parse_function (const jerry_char_t *resource_name_p, /**< resource name (u size_t arg_list_size, /**< script source size */ const jerry_char_t *source_p, /**< script source */ size_t source_size, /**< script source size */ - bool is_strict) /**< strict mode */ + uint32_t parse_opts) /**< strict mode */ ``` - `resource_name_p` - resource name, usually a file name (must be a valid UTF8 string). @@ -814,7 +912,7 @@ jerry_parse_function (const jerry_char_t *resource_name_p, /**< resource name (u - `arg_list_size` - size of the argument list, in bytes. - `source_p` - string, containing source code to parse (must be a valid UTF8 string). - `source_size` - size of the string, in bytes. -- `is_strict` - defines strict mode. +- `parse_opts` - any combination of [jerry_parse_opts_t](#jerry_parse_opts_t) flags. - return value - function object value, if script was parsed successfully, - thrown error, otherwise @@ -857,7 +955,7 @@ main (void) jerry_init (JERRY_INIT_EMPTY); /* Setup Global scope code */ - jerry_value_t parsed_code = jerry_parse (script, script_size, false); + jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS); if (!jerry_value_has_error_flag (parsed_code)) { @@ -947,7 +1045,7 @@ main (void) const jerry_char_t script[] = "new Promise(function(f,r) { f('Hello, World!'); }).then(function(x) { print(x); });"; size_t script_size = strlen ((const char *) script); - jerry_value_t parsed_code = jerry_parse (script, script_size, false); + jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS); jerry_value_t script_value = jerry_run (parsed_code); jerry_value_t job_value = jerry_run_all_enqueued_jobs (); @@ -4573,6 +4671,187 @@ bool foreach_function (const jerry_value_t prop_name, - [jerry_object_property_foreach_t](#jerry_object_property_foreach_t) +## jerry_objects_foreach + +**Summary** + +Iterate over objects. + +*Note*: Values obtained in `foreach_p` must be retained using [jerry_acquire_value](#jerry_acquire_value). + +**Prototype** + +```c +bool jerry_objects_foreach (jerry_objects_foreach_t foreach_p, + void *user_data_p); +``` + +- `foreach_p` - function that will be invoked for each object. +- `user_data_p` - User data to pass to the function. +- return value + - `true`, if the search function terminated the traversal by returning `false` + - `false`, if the end of the list of objects was reached + +**Example** + +```c +typedef struct +{ + jerry_value_t property_name; + jerry_value_t result; +} find_my_object_info_t; + +/* + * Find the first object with the given property. + */ +static bool +find_my_object(const jerry_value_t candidate, + void *user_data_p) +{ + find_my_object_info_t *info_p = (find_my_object_info_t *) user_data_p; + jerry_value_t has_property = jerry_object_has_property (candidate, info_p->property_name); + bool keep_searching = (jerry_value_has_error_flag (has_property) || !jerry_get_boolean_value ()); + if (!keep_searching) + { + /* We found it, so we acquire the value and record it. */ + info_p->result = jerry_acquire_value (candidate); + } + jerry_release_value (has_property); + return keep_searching; +} /* find_my_object */ + +{ + find_my_object_info_t search_info = + { + .property_name = jerry_create_string ("desired_property") + }; + + if (jerry_object_foreach (find_my_object, &search_info)) + { + /* The search was successful. Do something useful with search_info.result. */ + ... + + /* Release the found object after we're done using it. */ + jerry_release_value (search_info.result); + } + else + { + /* The search has failed. */ + } + + jerry_release_value (search_info.desired_property); +} +``` +**See also** + +- [jerry_objects_foreach_t](#jerry_objects_foreach_t) + +## jerry_objects_foreach_by_native_info + +**Summary** + +Iterate over objects matching a certain native data type. + +*Note*: Values obtained in `foreach_p` must be retained using [jerry_acquire_value](#jerry_acquire_value). + +**Prototype** + +```c +bool jerry_objects_foreach_by_native_info (const jerry_object_native_info_t *native_info_p, + jerry_objects_foreach_by_native_info_t foreach_p, + void *user_data_p); +``` + +- `native_info_p` - native pointer's type infomation. +- return value + - `true`, if the search function terminated the traversal by returning `false` + - `false`, if the end of the list of objects was reached + +**Example** + +```c +typedef struct +{ + int foo; + bool bar; +} native_obj_t; + +typedef struct +{ + jerry_value_t found_object; + void *match_data_p; +} find_object_data_t; + +static void native_freecb (void *native_p) +{ + ... // free the native pointer +} /* native_freecb */ + +// NOTE: The address (!) of type_info acts as a way to uniquely "identify" the +// C type `native_obj_t *`. +static const jerry_object_native_info_t native_obj_type_info = +{ + .free_cb = native_freecb +}; + +// Function creating JS object that is "backed" by a native_obj_t *: +{ + ... + + // construct object and native_set value: + jerry_value_t object = ...; + native_obj_t *native_obj_p = malloc (sizeof (*native_obj_p)); + jerry_set_object_native_pointer (object, native_obj_p, &native_obj_type_info); + + ... +} + +// Native method that retrieves the JavaScript object by way of its native data: +static bool find_object (const jerry_value_t candidate, void *data_p, void *user_data_p) +{ + find_object_data_t *find_data_p = (find_object_data_t *) user_data_p; + + if (find_data_p->match_data_p == data_p) + { + // If the object was found, acquire it and store it in the user data. + find_data_p->found_object = jerry_acquire_value (candidate); + + // Stop traversing over the objects. + return false; + } + + // Indicate that the object was not found, so traversal must continue. + return true; +} /* find_object */ +... +{ + find_object_data_t find_data = + { + .match_data = native_obj + }; + + if (jerry_objects_foreach_by_native_info (&native_obj_type_info, find_object, &find_data)) + { + // The object was found and is now stored in find_data.found_object. After using it, it must be released. + ... + jerry_release_value (find_data.found_object); + } + else + { + // The object was not found. + } + ... +} +``` + +**See also** + +- [jerry_create_object](#jerry_create_object) +- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) +- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) +- [jerry_object_native_info_t](#jerry_object_native_info_t) +- [jerry_objects_foreach](#jerry_objects_foreach) + # Input validator functions @@ -4683,7 +4962,7 @@ main (void) # Snapshot functions -## jerry_parse_and_save_snapshot +## jerry_generate_snapshot **Summary** @@ -4692,26 +4971,28 @@ Generate snapshot from the specified source code. **Prototype** ```c -size_t -jerry_parse_and_save_snapshot (const jerry_char_t *source_p, - size_t source_size, - bool is_for_global, - bool is_strict, - uint32_t *buffer_p, - size_t buffer_size); +jerry_value_t +jerry_generate_snapshot (const jerry_char_t *resource_name_p, + size_t resource_name_length, + const jerry_char_t *source_p, + size_t source_size, + uint32_t generate_snapshot_opts, + uint32_t *buffer_p, + size_t buffer_size); ``` +- `resource_name_p` - resource (file) name of the source code. Currently unused, the debugger may use it in the future. +- `resource_name_length` - length of resource name. - `source_p` - script source, it must be a valid utf8 string. - `source_size` - script source size, in bytes. -- `is_for_global` - snapshot would be executed as global (true) or eval (false). -- `is_strict` - strict mode +- `generate_snapshot_opts` - any combination of [jerry_generate_snapshot_opts_t](#jerry_generate_snapshot_opts_t) flags. - `buffer_p` - buffer to save snapshot to. - `buffer_size` - the buffer's size. - return value - - the size of snapshot, if it was generated succesfully (i.e. there are no syntax errors in source - code, buffer size is sufficient, and snapshot support is enabled in current configuration through - JERRY_ENABLE_SNAPSHOT_SAVE) - - 0 otherwise. + - the size of the snapshot as a number value, if it was generated succesfully (i.e. there are no syntax + errors in source code, buffer size is sufficient, and snapshot support is enabled in current configuration + through JERRY_ENABLE_SNAPSHOT_SAVE) + - thrown error, otherwise. **Example** @@ -4729,12 +5010,17 @@ main (void) static uint32_t global_mode_snapshot_buffer[256]; const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();"; - size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p, - strlen ((const char *) code_to_snapshot_p), - true, - false, - global_mode_snapshot_buffer, - sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t)); + jerry_value_t generate_result; + generate_result = jerry_generate_snapshot (NULL, + 0, + code_to_snapshot_p, + strlen ((const char *) code_to_snapshot_p), + 0, + global_mode_snapshot_buffer, + sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t)); + + size_t snapshot_size = (size_t) jerry_get_number_value (generate_result); + jerry_release_value (generate_result); jerry_cleanup (); } @@ -4744,10 +5030,11 @@ main (void) - [jerry_init](#jerry_init) - [jerry_cleanup](#jerry_cleanup) +- [jerry_generate_function_snapshot](#jerry_generate_function_snapshot) - [jerry_exec_snapshot](#jerry_exec_snapshot) -## jerry_parse_and_save_function_snapshot +## jerry_generate_function_snapshot **Summary** @@ -4760,28 +5047,32 @@ passed as separated arguments. **Prototype** ```c -size_t -jerry_parse_and_save_function_snapshot (const jerry_char_t *source_p, - size_t source_size, - const jerry_char_t *args_p, - size_t args_size, - bool is_strict, - uint32_t *buffer_p, - size_t buffer_size) +jerry_value_t +jerry_generate_function_snapshot (const jerry_char_t *resource_name_p, + size_t resource_name_length, + const jerry_char_t *source_p, + size_t source_size, + const jerry_char_t *args_p, + size_t args_size, + uint32_t generate_snapshot_opts, + uint32_t *buffer_p, + size_t buffer_size) ``` +- `resource_name_p` - resource (file) name of the source code. Currently unused, the debugger may use it in the future. +- `resource_name_length` - length of resource name. - `source_p` - script source, it must be a valid utf8 string. - `source_size` - script source size, in bytes. - `args_p` - function arguments, it must be a valid utf8 string. - `args_size` - function argument size, in bytes. -- `is_strict` - strict mode +- `generate_snapshot_opts` - any combination of [jerry_generate_snapshot_opts_t](#jerry_generate_snapshot_opts_t) flags. - `buffer_p` - buffer to save snapshot to. - `buffer_size` - the buffer's size. - return value - - the size of snapshot, if it was generated succesfully (i.e. there are no syntax errors in source - code, buffer size is sufficient, and snapshot support is enabled in current configuration through - JERRY_ENABLE_SNAPSHOT_SAVE) - - 0 otherwise. + - the size of the snapshot as a number value, if it was generated succesfully (i.e. there are no syntax + errors in source code, buffer size is sufficient, and snapshot support is enabled in current configuration + through JERRY_ENABLE_SNAPSHOT_SAVE) + - thrown error, otherwise. **Example** @@ -4800,13 +5091,19 @@ main (void) const jerry_char_t *args_p = (const jerry_char_t *) "a, b"; const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;"; - size_t func_snapshot_size = jerry_parse_and_save_function_snapshot (src_p, - strlen ((const char *) src_p), - args_p, - strlen ((const char *) args_p), - false, - func_snapshot_buffer, - sizeof (func_snapshot_buffer) / sizeof (uint32_t)); + jerry_value_t generate_result; + generate_result = jerry_generate_function_snapshot (NULL, + 0, + src_p, + strlen ((const char *) src_p), + args_p, + strlen ((const char *) args_p), + 0, + func_snapshot_buffer, + sizeof (func_snapshot_buffer) / sizeof (uint32_t)); + + size_t snapshot_size = (size_t) jerry_get_number_value (generate_result); + jerry_release_value (generate_result); jerry_cleanup (); } @@ -4816,6 +5113,7 @@ main (void) - [jerry_init](#jerry_init) - [jerry_cleanup](#jerry_cleanup) +- [jerry_generate_snapshot](#jerry_generate_snapshot) - [jerry_load_function_snapshot_at](#jerry_load_function_snapshot_at) @@ -4834,15 +5132,14 @@ is no longer needed. jerry_value_t jerry_exec_snapshot (const uint32_t *snapshot_p, size_t snapshot_size, - bool copy_bytecode); + size_t func_index, + uint32_t exec_snapshot_opts); ``` - `snapshot_p` - pointer to snapshot - `snapshot_size` - size of snapshot -- `copy_bytecode` - flag, indicating whether the passed snapshot buffer should be copied to the - engine's memory. If set the engine should not reference the buffer after the function returns - (in this case, the passed buffer could be freed after the call). Otherwise (if the flag is not - set) - the buffer could only be freed after the engine stops (i.e. after call to jerry_cleanup). +- `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 @@ -4862,19 +5159,27 @@ main (void) const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();"; jerry_init (JERRY_INIT_EMPTY); - size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p, - strlen ((const char *) code_to_snapshot_p), - true, - false, - global_mode_snapshot_buffer, - sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t)); + + jerry_value_t generate_result; + generate_result = jerry_generate_snapshot (NULL, + 0, + code_to_snapshot_p, + strlen ((const char *) code_to_snapshot_p), + 0, + global_mode_snapshot_buffer, + sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t)); + + size_t global_mode_snapshot_size = (size_t) jerry_get_number_value (generate_result); + jerry_release_value (generate_result); + jerry_cleanup (); jerry_init (JERRY_INIT_EMPTY); jerry_value_t res = jerry_exec_snapshot (global_mode_snapshot_buffer, global_mode_snapshot_size, - false); + 0, + 0); jerry_release_value (res); jerry_cleanup (); @@ -4885,89 +5190,10 @@ main (void) - [jerry_init](#jerry_init) - [jerry_cleanup](#jerry_cleanup) -- [jerry_exec_snapshot_at](#jerry_exec_snapshot_at) - [jerry_parse_and_save_snapshot](#jerry_parse_and_save_snapshot) -## jerry_exec_snapshot_at - -**Summary** - -Execute the selected snapshot function from the specified buffer. - -Same function as [jerry_exec_snapshot](#jerry_exec_snapshot) except -the executed function index can be specified. - -*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it -is no longer needed. - -**Prototype** - -```c -jerry_value_t -jerry_exec_snapshot_at (const uint32_t *snapshot_p, - size_t snapshot_size, - size_t func_index, - bool copy_bytecode); -``` - -- `snapshot_p` - pointer to snapshot -- `snapshot_size` - size of snapshot -- `func_index` - index of executed function -- `copy_bytecode` - flag, indicating whether the passed snapshot buffer should be copied to the - engine's memory. If set the engine should not reference the buffer after the function returns - (in this case, the passed buffer could be freed after the call). Otherwise (if the flag is not - set) - the buffer could only be freed after the engine stops (i.e. after call to jerry_cleanup). -- return value - - result of bytecode, if run was successful - - thrown error, otherwise - -**Example** - -[doctest]: # () - -```c -#include -#include "jerryscript.h" - -int -main (void) -{ - static uint32_t global_mode_snapshot_buffer[256]; - const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();"; - - jerry_init (JERRY_INIT_EMPTY); - size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p, - strlen ((const char *) code_to_snapshot_p), - true, - false, - global_mode_snapshot_buffer, - sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t)); - jerry_cleanup (); - - jerry_init (JERRY_INIT_EMPTY); - - jerry_value_t res = jerry_exec_snapshot_at (global_mode_snapshot_buffer, - global_mode_snapshot_size, - 0, - false); - - jerry_release_value (res); - - jerry_cleanup (); - return 0; -} -``` - -**See also** - -- [jerry_init](#jerry_init) -- [jerry_cleanup](#jerry_cleanup) -- [jerry_exec_snapshot](#jerry_exec_snapshot) -- [jerry_parse_and_save_snapshot](#jerry_parse_and_save_snapshot) - - -## jerry_load_function_snapshot_at +## jerry_load_function_snapshot **Summary** @@ -4982,19 +5208,16 @@ is no longer needed. ```c jerry_value_t -jerry_load_function_snapshot_at (const uint32_t *snapshot_p, - size_t snapshot_size, - size_t func_index, - bool copy_bytecode); +jerry_load_function_snapshot (const uint32_t *snapshot_p, + size_t snapshot_size, + size_t func_index, + uint32_t exec_snapshot_opts); ``` - `snapshot_p` - pointer to snapshot - `snapshot_size` - size of snapshot - `func_index` - index of function to load -- `copy_bytecode` - flag, indicating whether the passed snapshot buffer should be copied to the - engine's memory. If set the engine should not reference the buffer after the function returns - (in this case, the passed buffer could be freed after the call). Otherwise (if the flag is not - set) - the buffer could only be freed after the engine stops (i.e. after call to jerry_cleanup). +- `exec_snapshot_opts` - any combination of [jerry_exec_snapshot_opts_t](#jerry_exec_snapshot_opts_t) flags. - return value - function object built from the snapshot - thrown error, otherwise @@ -5015,21 +5238,29 @@ main (void) const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;"; jerry_init (JERRY_INIT_EMPTY); - size_t snapshot_size = jerry_parse_and_save_function_snapshot (src_p, - strlen ((const char *) src_p), - args_p, - strlen ((const char *) args_p), - false, - snapshot_buffer, - sizeof (snapshot_buffer) / sizeof (uint32_t)); + + jerry_value_t generate_result; + generate_result = jerry_generate_function_snapshot (NULL, + 0, + src_p, + strlen ((const char *) src_p), + args_p, + strlen ((const char *) args_p), + false, + snapshot_buffer, + sizeof (snapshot_buffer) / sizeof (uint32_t)); + + size_t snapshot_size = (size_t) jerry_get_number_value (generate_result); + jerry_release_value (generate_result); + jerry_cleanup (); jerry_init (JERRY_INIT_EMPTY); - jerry_value_t func = jerry_load_function_snapshot_at (snapshot_buffer, - snapshot_size, - 0, - false); + jerry_value_t func = jerry_load_function_snapshot (snapshot_buffer, + snapshot_size, + 0, + 0); /* 'func' can be used now as a function object */ jerry_value_t this_value = jerry_create_undefined (); @@ -5199,7 +5430,7 @@ main (void) // Inifinte loop. const char *src_p = "while(true) {}"; - jerry_value_t src = jerry_parse ((jerry_char_t *) src_p, strlen (src_p), false); + jerry_value_t src = jerry_parse (NULL, 0, (jerry_char_t *) src_p, strlen (src_p), JERRY_PARSE_NO_OPTS); jerry_release_value (jerry_run (src)); jerry_release_value (src); jerry_cleanup (); @@ -5214,6 +5445,31 @@ main (void) - [jerry_run](#jerry_run) - [jerry_vm_exec_stop_callback_t](#jerry_vm_exec_stop_callback_t) +## jerry_get_backtrace + +**Summary** + +Get backtrace. The backtrace is an array of strings where +each string contains the position of the corresponding frame. +The array length is zero if the backtrace is not available. + +This function is typically called from native callbacks. + +**Prototype** + +```c +jerry_value_t +jerry_get_backtrace (uint32_t max_depth); +``` + +- `max_depth` - backtrace collection stops after reaching this value, 0 = unlimited +- return value + - a new array + +**See also** + +- [jerry_create_external_function](#jerry_create_external_function) + # ArrayBuffer and TypedArray functions @@ -5570,3 +5826,73 @@ jerry_value_t jerry_get_typedarray_buffer (jerry_value_t value, **See also** - [jerry_create_typedarray](#jerry_create_typedarray) + +# JSON functions + +## jerry_json_parse + +**Summary** + +Returns the same result as JSON.parse ecmascript function. + +**Prototype** + +```c +jerry_value_t jerry_json_parse (const jerry_char_t *string_p, jerry_size_t string_size) +``` + +- `string_p` - a JSON string +- `string_size` - size of the string +- return + - jerry_value_t containing the same as json.parse() + - jerry_value_t containing error massage + +**Example** + +```c +{ + const char *data = "{\"name\": \"John\", \"age\": 5}"; + jerry_size_t str_length = (jerry_size_t)strlen (data); + jerry_value_t parsed_json = jerry_json_parse ((jerry_char_t*)data, str_length); + + // parsed_json now conatins all data stored in data_in_json + + jerry_release_value (parsed_json); +} +``` + +## jerry_stringify + + **Summary** + + Returns the same value as JSON.stringify() ecmascript function. + + **Prototype** + +```c +jerry_value_t jerry_json_stringfy (const jerry_value_t object_to_stringify) +``` + +- `object_to_stringify` - a jerry_value_t object to stringify +- return + - jerry_value_t containing the same as json.stringify() + - jerry_value_t containing error massage + +**Example** + +```c +{ + jerry_value_t obj = jerry_create_object (); + jerry_value_t key = jerry_create_string ((const jerry_char_t *) "name"); + jerry_value_t value = jerry_create_string ((const jerry_char_t *) "John"); + jerry_set_property (obj, key, value); + jerry_value_t stringified = jerry_json_stringfy (obj); + + //stringified now contains a json formated string + + jerry_release_value (obj); + jerry_release_value (key); + jerry_release_value (value); + jerry_release_value (stringified); +} +``` diff --git a/03.API-EXAMPLE.md b/03.API-EXAMPLE.md index d08111481..373e6ec1d 100644 --- a/03.API-EXAMPLE.md +++ b/03.API-EXAMPLE.md @@ -65,7 +65,7 @@ main (void) jerryx_handler_print); /* Setup Global scope code */ - jerry_value_t parsed_code = jerry_parse (script, script_size, false); + jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS); if (!jerry_value_has_error_flag (parsed_code)) { diff --git a/04.INTERNALS.md b/04.INTERNALS.md index 2199e6a98..5f365d52f 100644 --- a/04.INTERNALS.md +++ b/04.INTERNALS.md @@ -41,7 +41,7 @@ The interactions between the major components shown on the following figure. # Byte-code -This section describes the compact byte-code (CBC) byte-code representation. The key focus is reducing memory consumption of the byte-code representation without sacrificing considerable performance. Other byte-code representations often focus on performance only so inventing this representation is an original research. +This section describes the compact byte-code (CBC) representation. The key focus is reducing memory consumption of the byte-code representation without sacrificing considerable performance. Other byte-code representations often focus on performance only so inventing this representation is an original research. CBC is a CISC like instruction set which assigns shorter instructions for frequent operations. Many instructions represent multiple atomic tasks which reduces the byte code size. This technique is basically a data compression method. diff --git a/05.PORT-API.md b/05.PORT-API.md index 80aff0252..2c0728586 100644 --- a/05.PORT-API.md +++ b/05.PORT-API.md @@ -122,6 +122,15 @@ Allow user to provide external buffer for jerry instance (which includes an isol struct jerry_instance_t *jerry_port_get_current_instance (void); ``` +## Sleep + +```c +/** + * Makes the process sleep for a given time. + */ +void jerry_port_sleep (uint32_t sleep_time); +``` + # How to port JerryScript This section describes a basic port implementation which was created for Unix based systems. @@ -241,3 +250,32 @@ jerry_port_get_current_instance (void) return current_instance_p; } /* jerry_port_get_current_instance */ ``` + +## Sleep + +```c +#include "jerryscript-port.h" +#include "jerryscript-port-default.h" + +#ifdef HAVE_TIME_H +#include +#elif defined (HAVE_UNISTD_H) +#include +#endif /* HAVE_TIME_H */ + +#ifdef JERRY_DEBUGGER +void jerry_port_sleep (uint32_t sleep_time) +{ +#ifdef HAVE_TIME_H + nanosleep (&(const struct timespec) + { + sleep_time / 1000, (sleep_time % 1000) * 1000000L /* Seconds, nanoseconds */ + } + , NULL); +#elif defined (HAVE_UNISTD_H) + usleep ((useconds_t) sleep_time * 1000); +#endif /* HAVE_TIME_H */ + (void) sleep_time; +} /* jerry_port_sleep */ +#endif /* JERRY_DEBUGGER */ +``` diff --git a/07.DEBUGGER.md b/07.DEBUGGER.md index 2130cee95..2f4cb0a47 100644 --- a/07.DEBUGGER.md +++ b/07.DEBUGGER.md @@ -79,14 +79,9 @@ The debugger can be enabled by calling the `jerry_debugger_init (uint16_t port)` function after the `jerry_init ()` function. It initializes the debugger and blocks until a client connects. -When the debugger is enabled it is recommended to use -`jerry_parse_named_resource ()` instead of `jerry_parse ()` because -the resource name (usually a file name) is also passed to this -function. This resource name is used by the client to identify -the corresponding resource. In general it is always recommended to -use `jerry_parse_named_resource ()` when the resource name is -available because it silently ignores the resource name if the -debugger is disabled. +The resource name provided to `jerry_parse ()` is used by the client +to identify the resource name of the source code. This resource name +is usually a file name. ## JerryScript debugger C-API interface @@ -314,11 +309,11 @@ wait_for_source_callback (const jerry_char_t *resource_name_p, /**< resource nam size_t source_size, /**< source code size */ void *user_p __attribute__((unused))) /**< user pointer */ { - jerry_value_t ret_val = jerry_parse_named_resource (resource_name_p, - resource_name_size, - source_p, - source_size, - false); + jerry_value_t ret_val = jerry_parse (resource_name_p, + resource_name_size, + source_p, + source_size, + JERRY_PARSE_NO_OPTS); if (!jerry_value_has_error_flag (ret_val)) { diff --git a/08.CODING-STANDARDS.md b/08.CODING-STANDARDS.md index f20064d04..f7bd84883 100644 --- a/08.CODING-STANDARDS.md +++ b/08.CODING-STANDARDS.md @@ -714,7 +714,7 @@ typedef struct /* Field descriptions do not start with capital letters * and there is no full stop at the end. */ field1_t field1; /**< description of field 1 */ - field2_t field2; /**< description of field 1 */ + field2_t field2; /**< description of field 2 */ field_n_t field_n; /**< description of field n */ } structure_name_t;