From cf87970ef64a204f1b7f813f5e709917359cf2da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=A1szl=C3=B3=20Lang=C3=B3?= Date: Fri, 31 Aug 2018 12:02:17 +0200 Subject: [PATCH] Update the webpage (#2499) 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 --- 01.GETTING-STARTED.md | 10 +- 02.API-REFERENCE.md | 551 +++++++++++++++++++++--------------- 03.API-EXAMPLE.md | 16 +- 05.PORT-API.md | 5 + 07.DEBUGGER.md | 190 ++++++++----- 10.EXT-REFERENCE-HANDLER.md | 4 +- 12.EXT-REFERENCE-MODULE.md | 2 +- 13.DEBUGGER-TRANSPORT.md | 258 +++++++++++++++++ 8 files changed, 722 insertions(+), 314 deletions(-) create mode 100644 13.DEBUGGER-TRANSPORT.md diff --git a/01.GETTING-STARTED.md b/01.GETTING-STARTED.md index ae2a15c5d..9b9c84d21 100644 --- a/01.GETTING-STARTED.md +++ b/01.GETTING-STARTED.md @@ -63,20 +63,20 @@ python tools/build.py --profile=es5.1|es2015-subset|minimal See also the related [README.md](https://github.com/jerryscript-project/jerryscript/blob/master/jerry-core/profiles/README.md). -**Use (jerry, compiler-default, external) libc** +**Use (compiler-default, external) libc** -The default libc is jerry-libc, but you can use compiler-default libc or an external libc: +The default libc is the compiler-default libc but you can use an external libc as well: - compiler-default libc: ```bash -python tools/build.py --jerry-libc=off +python tools/build.py ``` - external libc: ```bash -python tools/build.py --jerry-libc=off --compile-flag="-nostdlib -I/path/to/ext-libc/include" --link-lib="ext-c" +python tools/build.py --compile-flag="-nostdlib -I/path/to/ext-libc/include" --link-lib="ext-c" ``` **Add toolchain file** @@ -96,7 +96,7 @@ python tools/build.py --toolchain=cmake/toolchain_linux_armv7l.cmake **Use system memory allocator** ```bash -python tools/build.py --system-allocator=on --jerry-libc=off +python tools/build.py --system-allocator=on ``` *Note*: System allocator is only supported on 32 bit systems. diff --git a/02.API-REFERENCE.md b/02.API-REFERENCE.md index 92ae85328..3dee895fb 100644 --- a/02.API-REFERENCE.md +++ b/02.API-REFERENCE.md @@ -23,16 +23,17 @@ Enum that contains the following elements: ## jerry_type_t -Enum that contains a set of elements to represent JavaScript type: +Enum that contains JerryScript API value types: - JERRY_TYPE_NONE - no type information - - JERRY_TYPE_UNDEFINED - undefined value - - JERRY_TYPE_NULL - null value - - JERRY_TYPE_BOOLEAN - boolean value - - JERRY_TYPE_NUMBER - number value - - JERRY_TYPE_STRING - string value - - JERRY_TYPE_OBJECT - object value - - JERRY_TYPE_FUNCTION - function value + - JERRY_TYPE_UNDEFINED - undefined type + - JERRY_TYPE_NULL - null type + - JERRY_TYPE_BOOLEAN - boolean type + - JERRY_TYPE_NUMBER - number type + - JERRY_TYPE_STRING - string type + - JERRY_TYPE_OBJECT - object type + - JERRY_TYPE_FUNCTION - function type + - JERRY_TYPE_ERROR - error/abort type ## jerry_error_t @@ -69,6 +70,7 @@ Possible compile time enabled feature types: - JERRY_FEATURE_DATE - Date support - JERRY_FEATURE_REGEXP - RegExp support - JERRY_FEATURE_LINE_INFO - line info available + - JERRY_FEATURE_LOGGING - logging ## jerry_parse_opts_t @@ -78,6 +80,18 @@ Option bits for [jerry_parse](#jerry_parse) and - JERRY_PARSE_NO_OPTS - no options passed - JERRY_PARSE_STRICT_MODE - enable strict mode +## jerry_gc_mode_t + +Set garbage collection operational mode + + - JERRY_GC_SEVERITY_LOW - free unused objects + - JERRY_GC_SEVERITY_HIGH - free as much memory as possible + +The difference between `JERRY_GC_SEVERITY_LOW` and `JERRY_GC_SEVERITY_HIGH` +is that the former keeps memory allocated for performance improvements such +as property hash tables for large objects. The latter frees all possible +memory blocks but the performance may drop after the garbage collection. + ## jerry_generate_snapshot_opts_t Flags for [jerry_generate_snapshot](#jerry_generate_snapshot) and @@ -139,18 +153,6 @@ Jerry's char value typedef uint8_t jerry_char_t; ``` -## jerry_char_ptr_t - -**Summary** - -Pointer to an array of character values - -**Prototype** - -```c -typedef jerry_char_t *jerry_char_ptr_t; -``` - ## jerry_size_t **Summary** @@ -246,6 +248,34 @@ typedef struct } jerry_context_data_manager_t; ``` +## jerry_instance_alloc_t + +**Summary** + +Function type for allocating buffer for JerryScript instance. + +**Prototype** + +```c +typedef void *(*jerry_instance_alloc_t) (size_t size, void *cb_data_p); +``` + +- `size` - allocation size +- `cb_data_p` - pointer to user data + + +## jerry_instance_t + +**Summary** + +An opaque declaration of the JerryScript instance structure which is the header of the context space. + +**Prototype** + +```c +typedef struct jerry_instance_t jerry_instance_t; +``` + ## jerry_property_descriptor_t **Summary** @@ -330,20 +360,6 @@ typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_ const jerry_length_t args_count); ``` -## jerry_object_free_callback_t - -**Summary** - -**Deprecated: Please use jerry_object_native_free_callback_t instead.** - -Native free callback of an object. - -**Prototype** - -```c -typedef void (*jerry_object_free_callback_t) (const uintptr_t native_p); -``` - ## jerry_object_native_free_callback_t **Summary** @@ -360,7 +376,7 @@ typedef void (*jerry_object_native_free_callback_t) (void *native_p); **Summary** -The type infomation of the native pointer. +The type information of the native pointer. It includes the free callback that will be called when associated JavaScript object is garbage collected. It can be left NULL in case it is not needed. Typically, one would create a `static const jerry_object_native_info_t` for @@ -628,7 +644,7 @@ Registers an external magic string array. ```c void -jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p, +jerry_register_magic_strings (const jerry_char_t **ex_str_items_p, uint32_t count, const jerry_length_t *str_lengths_p); ``` @@ -651,12 +667,12 @@ main (void) // must be static, because 'jerry_register_magic_strings' does not copy // the items must be sorted by size at first, then lexicographically - static const jerry_char_ptr_t magic_string_items[] = { - (const jerry_char_ptr_t) "magicstring1", - (const jerry_char_ptr_t) "magicstring2", - (const jerry_char_ptr_t) "magicstring3" - }; - uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_ptr_t)); + static const jerry_char_t *magic_string_items[] = { + (const jerry_char_t *) "magicstring1", + (const jerry_char_t *) "magicstring2", + (const jerry_char_t *) "magicstring3" + }; + uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_t *)); // must be static, because 'jerry_register_magic_strings' does not copy static const jerry_length_t magic_string_lengths[] = { @@ -715,13 +731,30 @@ Performs garbage collection. ```c void -jerry_gc (void); +jerry_gc (jerry_gc_mode_t mode); ``` +- `mode` - operational mode, see [jerry_gc_mode_t](#jerry_gc_mode_t) + **Example** +[doctest]: # () + ```c -jerry_gc (); +#include "jerryscript.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t object_value = jerry_create_object (); + jerry_release_value (object_value); + + jerry_gc (JERRY_GC_SEVERITY_LOW); + + jerry_cleanup (); +} ``` **See also** @@ -950,12 +983,12 @@ Perform JavaScript `eval`. jerry_value_t jerry_eval (const jerry_char_t *source_p, size_t source_size, - bool is_strict); + uint32_t parse_opts); ``` - `source_p` - source code to evaluate, it must be a valid utf8 string. - `source_size` - length of the source code -- `is_strict` - perform `eval` as it is called from "strict mode" code. +- `parse_opts` - any combination of [jerry_parse_opts_t](#jerry_parse_opts_t) flags. - return value - result of eval, may be error value. **Example** @@ -964,7 +997,7 @@ jerry_eval (const jerry_char_t *source_p, { jerry_value_t ret_val = jerry_eval (str_to_eval, strlen (str_to_eval), - false); + JERRY_PARSE_NO_OPTS); } ``` @@ -1611,7 +1644,7 @@ jerry_value_is_undefined (const jerry_value_t value) Returns the JavaScript type for a given value as a [jerry_type_t](#jerry_type_t) enum value. -This is a similar operation as the 'typeof' operator +This is a similar operation to the 'typeof' operator in the standard with an exception that the 'null' value has its own enum value. @@ -1677,6 +1710,125 @@ jerry_is_feature_enabled (const jerry_feature_t feature); # Error manipulation functions +## jerry_create_abort_from_value + +**Summary** + +Create (api) abort from a value. + +This function creates an API abort value from an API value. The second argument defines +whether the input value must be released or not. If it is set to `true`, +then a [`jerry_release_value`](#jerry_release_value) function will be called +for the first argument, so the api value won't be available after the call of +`jerry_create_abort_from_value`. The second argument should be false if both value +and created abort value are needed. + +**Prototype** + +```c +jerry_value_t +jerry_create_abort_from_value (jerry_value_t value, bool release); +``` + +- `value` - api value +- `release` - raw boolean, defines whether input value must be released +- return value - abort (api) value + +**Example 1** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_value_t abort = jerry_create_abort_from_value (value, true); + // using the 'value' variable after release is invalid. + + jerry_release_value (abort); +} +``` + +**Example 2** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_value_t abort = jerry_create_abort_from_value (value, false); + // both 'abort' and 'value' can be used and must be released when they are no longer needed + + jerry_release_value (abort); + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_value_t](#jerry_value_t) +- [jerry_get_value_from_error](#jerry_get_value_from_error) +- [jerry_create_error_from_value](#jerry_create_error_from_value) + +## jerry_create_error_from_value + +**Summary** + +Create (api) error from a value. + +This function creates an API error value from an API value. The second argument defines +whether the input value must be released or not. If it is set to `true`, +then a [`jerry_release_value`](#jerry_release_value) function will be called +for the first argument, so the api value won't be available after the call of +`jerry_create_error_from_value`. The second argument should be false if both value +and created error value are needed. + +**Prototype** + +```c +jerry_value_t +jerry_create_error_from_value (jerry_value_t value, bool release); +``` + +- `value` - api value +- `release` - raw boolean, defines whether input value must be released +- return value - error (api) value + +**Example 1** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_value_t error = jerry_create_error_from_value (value, true); + // using the 'value' variable after release is invalid. + + + jerry_release_value (error); +} +``` + +**Example 2** + +```c +{ + jerry_value_t value; + ... // create or acquire value + + jerry_value_t error = jerry_create_error_from_value (value, false); + // both 'error' and 'value' can be used and must be released when they are no longer needed + + jerry_release_value (error); + jerry_release_value (value); +} +``` + +**See also** + +- [jerry_value_t](#jerry_value_t) +- [jerry_get_value_from_error](#jerry_get_value_from_error) +- [jerry_create_abort_from_value](#jerry_create_abort_from_value + ## jerry_get_error_type **Summary** @@ -1732,7 +1884,7 @@ whether the input error value must be released or not. If it is set to `true`, then a [`jerry_release_value`](#jerry_release_value) function will be called for the first argument, so the error value won't be available after the call of `jerry_get_value_from_error`. The second argument should be false if both error -and its represented value are needed. The first argument is returned unchanged if it is not an error. +and its represented value are needed. *Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it is no longer needed. @@ -1752,14 +1904,14 @@ jerry_get_value_from_error (jerry_value_t value, bool release) ```c { - jerry_value_t error; + jerry_value_t value; ... // create or acquire value - jerry_value_set_error_flag (&error); - jerry_value_t value = jerry_get_value_from_error (error, true); + jerry_value_t error = jerry_create_error_from_value (value, true); + jerry_value_t value_from_error = jerry_get_value_from_error (error, true); // using the 'error' variable after release is invalid. - jerry_release_value (value); + jerry_release_value (value_from_error); } ``` @@ -1767,14 +1919,14 @@ jerry_get_value_from_error (jerry_value_t value, bool release) ```c { - jerry_value_t error; + jerry_value_t value; ... // create or acquire value - jerry_value_set_error_flag (&error); - jerry_value_t value = jerry_get_value_from_error (error, false); - // both 'error' and 'value' can be used and must be released when they are no longer needed + jerry_value_t error = jerry_create_error_from_value (value, true); + jerry_value_t value_from_error = jerry_get_value_from_error (error, false); + // both 'error' and 'value_from_error' can be used and must be released when they are no longer needed - jerry_release_value (value); + jerry_release_value (value_from_error); jerry_release_value (error); } ``` @@ -1782,78 +1934,8 @@ jerry_get_value_from_error (jerry_value_t value, bool release) **See also** - [jerry_value_t](#jerry_value_t) -- [jerry_value_set_error_flag](#jerry_value_set_error_flag) -- [jerry_value_set_abort_flag](#jerry_value_set_abort_flag) - -## jerry_value_set_error_flag - -**Summary** - -Set the error flag. - -**Prototype** - -```c -void -jerry_value_set_error_flag (jerry_value_t *value_p); -``` - -- `value_p` - pointer to an api value - -**Example** - -```c -{ - jerry_value_t value; - ... // create or acquire value - - jerry_value_set_error_flag (&value); - - jerry_release_value (value); -} -``` - -**See also** - -- [jerry_value_t](#jerry_value_t) -- [jerry_get_value_from_error](#jerry_get_value_from_error) -- [jerry_value_set_abort_flag](#jerry_value_set_abort_flag) - - -## jerry_value_set_abort_flag - -**Summary** - -Set both the error and abort flags. - -**Prototype** - -```c -void -jerry_value_set_abort_flag (jerry_value_t *value_p); -``` - -- `value_p` - pointer to an api value - -**Example** - -```c -{ - jerry_value_t value; - ... // create or acquire value - - jerry_value_set_abort_flag (&value); - - jerry_release_value (value); -} -``` - -**See also** - -- [jerry_value_t](#jerry_value_t) -- [jerry_get_value_from_error](#jerry_get_value_from_error) -- [jerry_value_set_error_flag](#jerry_value_set_error_flag) - +- [jerry_create_error_from_value](#jerry_create_error_from_value) +- [jerry_create_abort_from_value](#jerry_create_abort_from_value) # Getter functions of 'jerry_value_t' @@ -2890,7 +2972,7 @@ jerry_create_error (jerry_error_t error_type, - [jerry_value_is_error](#jerry_value_is_error) - [jerry_get_value_from_error](#jerry_get_value_from_error) -- [jerry_value_set_error_flag](#jerry_value_set_error_flag) +- [jerry_create_error_from_value](#jerry_create_error_from_value) ## jerry_create_error_sz @@ -4317,106 +4399,6 @@ jerry_set_prototype (const jerry_value_t obj_val, - [jerry_get_prototype](#jerry_get_prototype) -## jerry_get_object_native_handle - -**Summary** - -**Deprecated: Please use jerry_get_object_native_pointer instead.** - -Get native handle, previously associated with specified object. - -**Prototype** - -```c -bool -jerry_get_object_native_handle (const jerry_value_t obj_val, - uintptr_t *out_handle_p); -``` - -- `obj_val` - object value -- `out_handle_p` - handle value (output parameter). -- return value - - true, if there is handle associated with the object - - false, otherwise - -**Example** - -```c -{ - jerry_value_t object; - uintptr_t handle_set; - - ... // receive or construct object and handle_set value - - jerry_set_object_native_handle (object, handle_set, NULL); - - ... - - uintptr_t handle_get; - bool is_there_associated_handle = jerry_get_object_native_handle (object, &handle_get); -} -``` - -**See also** - -- [jerry_create_object](#jerry_create_object) -- [jerry_set_object_native_handle](#jerry_set_object_native_handle) -- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) - - -## jerry_set_object_native_handle - -**Summary** - -**Deprecated: Please use jerry_set_object_native_pointer instead.** - -Set native handle and an optional free callback for the specified object. - -*Note*: If native handle was already set for the object, its value is updated. - -*Note*: If a non-NULL free callback is specified, it will be called - by the garbage collector when the object is freed. The free - callback always overwrites the previous value, so passing - a NULL value deletes the current free callback. - -**Prototype** - -```c -void -jerry_set_object_native_handle (const jerry_value_t obj_val, - uintptr_t handle_p, - jerry_object_free_callback_t freecb_p); -``` - -- `obj_val` - object value to set handle in -- `handle_p` - handle value -- `freecb_p` - pointer to "free" callback or NULL - -**Example** - -```c -{ - jerry_value_t object; - uintptr_t handle_set; - - ... // receive or construct object and handle_set value - - jerry_set_object_native_handle (object, handle_set, NULL); - - ... - - uintptr_t handle_get; - bool is_there_associated_handle = jerry_get_object_native_handle (object, &handle_get); -} -``` - -**See also** - -- [jerry_create_object](#jerry_create_object) -- [jerry_get_object_native_handle](#jerry_get_object_native_handle) -- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) - - ## jerry_get_object_native_pointer **Summary** @@ -4437,7 +4419,7 @@ The pointer and the type information are previously associated with the object b and dereferencing `out_native_pointer_p`. *Note*: `out_native_pointer_p` and `out_native_info_p` can be NULL, and it means the - caller doesn't want to get the native_pointer or type infomation. + caller doesn't want to get the native_pointer or type information. **Prototype** @@ -4450,7 +4432,7 @@ jerry_get_object_native_pointer (const jerry_value_t obj_val, - `obj_val` - object value to get native pointer from. - `out_native_pointer_p` - native pointer (output parameter). -- `out_native_info_p` - native pointer's type infomation (output parameter). +- `out_native_info_p` - native pointer's type information (output parameter). - return value - true, if there is native pointer associated with the object - false, otherwise @@ -4547,7 +4529,7 @@ jerry_set_object_native_pointer (const jerry_value_t obj_val, - `obj_val` - object to set native pointer in. - `native_p` - native pointer. -- `info_p` - native pointer's type infomation or NULL. When used, this should +- `info_p` - native pointer's type information or NULL. When used, this should be a long-lived pointer, usually a pointer to a `static const jerry_object_native_info_t` makes most sense. @@ -4705,7 +4687,7 @@ bool jerry_objects_foreach_by_native_info (const jerry_object_native_info_t *nat void *user_data_p); ``` -- `native_info_p` - native pointer's type infomation. +- `native_info_p` - native pointer's type information. - return value - `true`, if the search function terminated the traversal by returning `false` - `false`, if the end of the list of objects was reached @@ -4903,6 +4885,105 @@ main (void) - [jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer) +# External context functions + +## jerry_create_instance + +**Summary** + +Creates a JerryScript instance for external context. + +**Prototype** + +```c +jerry_instance_t * +jerry_create_instance (uint32_t heap_size, + jerry_instance_alloc_t alloc, + void *cb_data_p); +``` + +- `heap_size` - requested heap size of the JerryScript instance +- `alloc` - function for allocation +- `cb_data_p` - user data +- return value + - pointer to the newly created JerryScript instance if success + - NULL otherwise. + +**Example** + +[doctest]: # (test="compile") + +```c +#include +#include + +#include "jerryscript.h" +#include "jerryscript-port.h" + +/* A different Thread Local Storage variable for each jerry instance. */ +__thread jerry_instance_t *tls_instance; + +jerry_instance_t * +jerry_port_get_current_instance (void) +{ + /* Returns the instance assigned to the thread. */ + return tls_instance; +} + +/* Allocate JerryScript heap for each thread. */ +static void * +instance_alloc_fn (size_t size, void *cb_data) +{ + (void) cb_data; + return malloc (size); +} + +static void * +thread_function (void *param) +{ + tls_instance = jerry_create_instance (512 * 1024, + instance_alloc_fn, + NULL); + jerry_init (JERRY_INIT_EMPTY); + /* Run the JerryScript instance (e.g.: jerry_parse & jerry_run) */ + jerry_cleanup (); + + /* Deallocate JerryScript instance */ + free (tls_instance); + + return NULL; +} + +#define NUM_OF_THREADS 8 + +int +main (void) +{ + pthread_t threads[NUM_OF_THREADS]; + + /* Create the threads. */ + for (int i = 0; i < NUM_OF_THREADS; i++) + { + pthread_create (&threads[i], NULL, thread_function, (void *) (intptr_t) i); + } + + /* Wait for the threads to complete, and release their resources. */ + for (int i = 0; i < NUM_OF_THREADS; i++) + { + pthread_join (threads[i], NULL); + } + + return 0; +} +``` + +**See also** + +- [jerry_instance_t](#jerry_instance_t) +- [jerry_instance_alloc_t](#jerry_instance_alloc_t) +- [jerry_port_get_current_instance](05.PORT-API.md#jerry_port_get_current_instance) + + # Snapshot functions ## jerry_generate_snapshot diff --git a/03.API-EXAMPLE.md b/03.API-EXAMPLE.md index f87a428cc..d0dbf4f25 100644 --- a/03.API-EXAMPLE.md +++ b/03.API-EXAMPLE.md @@ -115,7 +115,7 @@ main (void) /* Evaluate script1 */ eval_ret = jerry_eval (script_1, strlen ((const char *) script_1), - false); + JERRY_PARSE_NO_OPTS); /* Free JavaScript value, returned by eval */ jerry_release_value (eval_ret); @@ -123,7 +123,7 @@ main (void) /* Evaluate script2 */ eval_ret = jerry_eval (script_2, strlen ((const char *) script_2), - false); + JERRY_PARSE_NO_OPTS); /* Free JavaScript value, returned by eval */ jerry_release_value (eval_ret); @@ -179,7 +179,7 @@ main (void) /* Now starting script that would output value of just initialized field */ jerry_value_t eval_ret = jerry_eval (script, strlen ((const char *) script), - false); + JERRY_PARSE_NO_OPTS); /* Free JavaScript value, returned by eval */ jerry_release_value (eval_ret); @@ -332,7 +332,7 @@ main (void) /* Evaluate entered command */ ret_val = jerry_eval ((const jerry_char_t *) cmd, len, - false); + JERRY_PARSE_NO_OPTS); /* If command evaluated successfully, print value, returned by eval */ if (jerry_value_is_error (ret_val)) @@ -430,7 +430,7 @@ main (void) size_t script_size = strlen ((const char *) script); /* Evaluate script */ - jerry_value_t eval_ret = jerry_eval (script, script_size, false); + jerry_value_t eval_ret = jerry_eval (script, script_size, JERRY_PARSE_NO_OPTS); /* Free JavaScript value, returned by eval */ jerry_release_value (eval_ret); @@ -519,7 +519,7 @@ main (void) /* Evaluate script */ my_js_obj_val = jerry_eval (my_js_object, strlen ((const char *) my_js_object), - false); + JERRY_PARSE_NO_OPTS); /* Create a JS function object and wrap into a jerry value */ jerry_value_t add_func_obj = jerry_create_external_function (add_handler); @@ -542,7 +542,7 @@ main (void) size_t script_size = strlen ((const char *) script); /* Evaluate script */ - jerry_value_t eval_ret = jerry_eval (script, script_size, false); + jerry_value_t eval_ret = jerry_eval (script, script_size, JERRY_PARSE_NO_OPTS); /* Free JavaScript value, returned by eval */ jerry_release_value (eval_ret); @@ -593,7 +593,7 @@ main (void) jerryx_handler_print); /* Evaluate the script */ - jerry_value_t eval_ret = jerry_eval (script, script_size, false); + jerry_value_t eval_ret = jerry_eval (script, script_size, JERRY_PARSE_NO_OPTS); /* Free the JavaScript value returned by eval */ jerry_release_value (eval_ret); diff --git a/05.PORT-API.md b/05.PORT-API.md index d152a57b1..17f5cfd51 100644 --- a/05.PORT-API.md +++ b/05.PORT-API.md @@ -73,6 +73,11 @@ typedef enum * * Example: a libc-based port may implement this with vfprintf(stderr) or * vfprintf(logfile), or both, depending on log level. + * + * Note: + * This port function is called by jerry-core when JERRY_ENABLE_LOGGING is + * defined. It is also common practice though to use this function in + * application code. */ void jerry_port_log (jerry_log_level_t level, const char *fmt, ...); ``` diff --git a/07.DEBUGGER.md b/07.DEBUGGER.md index ee9a0eb54..55834e9da 100644 --- a/07.DEBUGGER.md +++ b/07.DEBUGGER.md @@ -13,24 +13,23 @@ permalink: /debugger/ JerryScript provides a remote debugger which allows debugging JavaScript programs. The debugger has two main components: a server which is part of the JerryScript binary and a -separate client application. Currently two debugger clients -are available in the /jerry-debugger subdirectory: an HTML -and a Python application. These simple applications demonstrate -the communication protocol between the client and server and can -be reused by integrated development environments. +separate client application. Currently a Python-based debugger +client is available in the /jerry-debugger subdirectory. +This simple application demonstrates the communication protocol +between the client and server, and can be reused by integrated +development environments. ## Setting up the debugger server The following arguments must be passed to `tools/build.py`: -`--jerry-debugger=on --jerry-libc=off` +`--jerry-debugger=on` -At the moment only a Websocket-based implementation is provided -by JerryScript which transmits messages over TCP/IP networks. -This implementation requires a socket API which is not yet -supported by jerry-libc so the standard libc is used instead. -In the future any reliable stream or datagram based protocol -can be used for transmitting debugger messages. +The transport layer of the communication protocol is pluggable. +At the moment, a WebSocket-based implementation is provided as a +JerryScript extension, which transmits messages over TCP/IP networks. +If necessary/implemented, any reliable stream or datagram based +protocol can be used for transmitting debugger messages. ## Debugging JavaScript applications @@ -59,8 +58,8 @@ the *Waiting for client connection* message: `--log-level 2` -The HTML client can connect to the IP address of the server with -the `connect` command. The IP address can be localhost +The Python client can connect to the server by specifying its +IP address on the command line. The address can be localhost if the server and the client are running on the same machine. After the connection is established the execution can be @@ -75,9 +74,12 @@ All available commands of the client can be queried by the ## Integrating debugger support into applications using JerryScript -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 using the extension-provided WebSocket transport layer, the +debugger can be enabled by calling `jerryx_debugger_after_connect +(jerryx_debugger_tcp_create (debug_port) && jerryx_debugger_ws_create ())` +after the `jerry_init ()` function. It initializes the debugger and +blocks until a client connects. (Custom transport layers may be +implemented and initialized similarly.) The resource name provided to `jerry_parse ()` is used by the client to identify the resource name of the source code. This resource name @@ -86,7 +88,7 @@ is usually a file name. ## JerryScript debugger C-API interface The following section describes the debugger functions -available for the host application. +available to the host application. ## JerryScript debugger types @@ -117,36 +119,6 @@ typedef jerry_value_t ## JerryScript debugger functions -### jerry_debugger_init - -**Summary** - -Debugger server initialization. Must be called after `jerry_init`. - -**Prototype** - -```c -void -jerry_debugger_init (uint16_t port); -``` - -- `port` - Server port number - - -**Example** - -```c -{ - jerry_init (JERRY_INIT_EMPTY); - jerry_debugger_init (5001); - - // ... - - jerry_cleanup (); -} -``` - - ### jerry_debugger_is_connected **Summary** @@ -162,10 +134,18 @@ jerry_debugger_is_connected (void); **Example** +[doctest]: # (test="link") + ```c +#include "jerryscript.h" +#include "jerryscript-ext/debugger.h" + +int +main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_debugger_init (5001); + jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001) + && jerryx_debugger_ws_create ()); if (jerry_debugger_is_connected ()) { @@ -194,10 +174,18 @@ jerry_debugger_stop (void) **Example** +[doctest]: # (test="link") + ```c +#include "jerryscript.h" +#include "jerryscript-ext/debugger.h" + +int +main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_debugger_init (5001); + jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001) + && jerryx_debugger_ws_create ()); jerry_debugger_stop (); @@ -228,10 +216,18 @@ jerry_debugger_continue (void) **Example** +[doctest]: # (test="link") + ```c +#include "jerryscript.h" +#include "jerryscript-ext/debugger.h" + +int +main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_debugger_init (5001); + jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001) + && jerryx_debugger_ws_create ()); jerry_debugger_continue (); @@ -243,7 +239,7 @@ jerry_debugger_continue (void) - [jerry_debugger_stop](#jerry_debugger_stop) -### jerry_debugger_disable_stop_at_breakpoint +### jerry_debugger_stop_at_breakpoint **Summary** @@ -262,15 +258,26 @@ jerry_debugger_stop_at_breakpoint (bool enable_stop_at_breakpoint) **Example** +[doctest]: # (test="link") + ```c +#include +#include "jerryscript.h" +#include "jerryscript-ext/debugger.h" + +int +main (void) { jerry_init (JERRY_INIT_EMPTY); - jerry_debugger_init (5001); + jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001) + && jerryx_debugger_ws_create ()); jerry_debugger_stop_at_breakpoint (true); // Protected execution of JavaScript code. - jerry_eval (...); + const jerry_char_t script[] = "42"; + size_t script_size = strlen ((const char *) script); + jerry_eval (script, script_size, JERRY_PARSE_NO_OPTS); jerry_debugger_stop_at_breakpoint (false); @@ -298,7 +305,12 @@ jerry_debugger_wait_for_client_source (jerry_debugger_wait_for_source_callback_t **Example** +[doctest]: # (test="link") + ```c +#include "jerryscript.h" +#include "jerryscript-ext/debugger.h" + /** * Runs the source code received by jerry_debugger_wait_for_client_source. */ @@ -325,20 +337,23 @@ wait_for_source_callback (const jerry_char_t *resource_name_p, /**< resource nam return ret_val; } /* wait_for_source_callback */ -int main () +int +main (void) { + jerry_debugger_wait_for_source_status_t receive_status; + do { /* Create a new JerryScript instance when a context reset is * received. Applications usually registers their core bindings * here as well (e.g. print, setTimeout). */ jerry_init (JERRY_INIT_EMPTY); - jerry_debugger_init (5001); + jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001) + && jerryx_debugger_ws_create ()); do { jerry_value_t run_result; - jerry_debugger_wait_for_source_status_t receive_status; receive_status = jerry_debugger_wait_for_client_source (wait_for_source_callback, NULL, @@ -369,20 +384,67 @@ Sends the program's output to the debugger client. **Prototype** ```c - void - jerry_debugger_send_output (jerry_char_t buffer[], jerry_size_t string_size, uint8_t type) +void +jerry_debugger_send_output (const jerry_char_t *buffer, jerry_size_t string_size) ``` **Example** -```c - jerry_init (JERRY_INIT_EMPTY); - jerry_debugger_init (5001); +[doctest]: # (test="link") - jerry_char_t my_output = "Hey, this should be sent too!"; +```c +#include "jerryscript.h" +#include "jerryscript-ext/debugger.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001) + && jerryx_debugger_ws_create ()); + + jerry_char_t my_output[] = "Hey, this should be sent too!"; jerry_size_t my_output_size = sizeof (my_output); - jerry_debugger_send_output (my_output, my_output_size, JERRY_DEBUGGER_OUTPUT_OK); + jerry_debugger_send_output (my_output, my_output_size); jerry_cleanup (); +} +``` + +### jerry_debugger_send_log + +**Summary** + +Sends the program's log to the debugger client. + +**Prototype** + +```c +void +jerry_debugger_send_log (jerry_log_level_t level, const jerry_char_t *buffer, jerry_size_t string_size) +``` + +**Example** + +[doctest]: # (test="link") + +```c +#include "jerryscript.h" +#include "jerryscript-ext/debugger.h" + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + jerryx_debugger_after_connect (jerryx_debugger_tcp_create (5001) + && jerryx_debugger_ws_create ()); + + jerry_char_t my_log[] = "Custom diagnostics"; + jerry_size_t my_log_size = sizeof (my_log); + + jerry_debugger_send_log (JERRY_LOG_LEVEL_DEBUG, my_log, my_log_size); + + jerry_cleanup (); +} ``` diff --git a/10.EXT-REFERENCE-HANDLER.md b/10.EXT-REFERENCE-HANDLER.md index c2e7f7b30..b0b3270d2 100644 --- a/10.EXT-REFERENCE-HANDLER.md +++ b/10.EXT-REFERENCE-HANDLER.md @@ -41,7 +41,9 @@ jerryx_handler_assert (const jerry_value_t func_obj_val, const jerry_value_t thi **Summary** -Expose garbage collector to scripts. +Expose garbage collector to scripts. If the first argument of the function +is logical true, it performs a high severity gc. Otherwise a low severity +gc is performed, which is also the default if no parameters passed. **Prototype** diff --git a/12.EXT-REFERENCE-MODULE.md b/12.EXT-REFERENCE-MODULE.md index beffb16d6..92569533b 100644 --- a/12.EXT-REFERENCE-MODULE.md +++ b/12.EXT-REFERENCE-MODULE.md @@ -192,7 +192,7 @@ load_and_evaluate_js_file (const jerry_value_t name, jerry_value_t *result) { /* We read the file into memory and call jerry_eval (), assigning the result to the out-parameter. */ fread (js_file_contents, file_size, 1, js_file); - (*result) = jerry_eval (js_file_contents, file_size, false); + (*result) = jerry_eval (js_file_contents, file_size, JERRY_PARSE_NO_OPTS); /* We release the memory holding the contents of the file. */ free (js_file_contents); diff --git a/13.DEBUGGER-TRANSPORT.md b/13.DEBUGGER-TRANSPORT.md new file mode 100644 index 000000000..574ecb912 --- /dev/null +++ b/13.DEBUGGER-TRANSPORT.md @@ -0,0 +1,258 @@ +--- +layout: page +title: debugger transport +category: documents +permalink: /debugger-transport/ +--- + +* toc +{:toc} + +# JerryScript debugger transport interface + +The transport interface support allows dynamic selection of transportation +layers which can encode/decode or send/receive messages transmitted between +the debugger client and server. + +# Types + +## jerry_debugger_transport_receive_context_t + +**Summary** + +This context represents the current status of processing received data. +The final state is returned by +[jerry_debugger_transport_receive](#jerry_debugger_transport_receive) +and must be passed to +[jerry_debugger_transport_receive_completed](#jerry_debugger_transport_receive_completed) +after the message is processed. + +**Prototype** + +```c +typedef struct +{ + uint8_t *buffer_p; /**< buffer for storing the received data */ + size_t received_length; /**< number of currently received bytes */ + uint8_t *message_p; /**< start of the received message */ + size_t message_length; /**< length of the received message */ + size_t message_total_length; /**< total length for datagram protocols, + * 0 for stream protocols */ +} jerry_debugger_transport_receive_context_t; +``` + +## jerry_debugger_transport_header_t + +**Summary** + +Shared header for each transport interface. It mostly contains callback functions +used by the JerryScript debugger server. + +**Prototype** + +```c +typedef struct jerry_debugger_transport_layer_t +{ + /* The following fields must be filled before calling jerry_debugger_transport_add(). */ + jerry_debugger_transport_close_t close; /**< close connection callback */ + jerry_debugger_transport_send_t send; /**< send data callback */ + jerry_debugger_transport_receive_t receive; /**< receive data callback */ + + /* The following fields are filled by jerry_debugger_transport_add(). */ + struct jerry_debugger_transport_layer_t *next_p; /**< next transport layer */ +} jerry_debugger_transport_header_t; +``` + +## jerry_debugger_transport_close_t + +**Summary** + +Called when the connection is closed. Must release all resources (including the +memory area for the transport interface) allocated for the transport interface. + +**Prototype** + +```c +typedef void (*jerry_debugger_transport_close_t) (struct jerry_debugger_transport_interface_t *header_p); +``` + +## jerry_debugger_transport_send_t + +**Summary** + +Called when a message needs to be sent. Must either transmit the message or call +the `header_p->next_p->send()` method. + +**Prototype** + +```c +typedef bool (*jerry_debugger_transport_send_t) (struct jerry_debugger_transport_interface_t *header_p, + uint8_t *message_p, size_t message_length); +``` + +## jerry_debugger_transport_receive_t + +**Summary** + +Called during message processing. If messages are available it must return with +the next message. + +**Prototype** + +```c +typedef bool (*jerry_debugger_transport_receive_t) (struct jerry_debugger_transport_interface_t *header_p, + jerry_debugger_transport_receive_context_t *context_p); +``` + +# Transport interface API functions + +## jerry_debugger_transport_malloc + +**Summary** + +Allocates memory for the transport interface. + +**Prototype** + +```c +void * jerry_debugger_transport_malloc (size_t size); +``` + +- `size`: size of the memory block. +- return value: non-NULL pointer, if the memory is successfully allocated, + NULL otherwise. + +## jerry_debugger_transport_free + +**Summary** + +Free memory allocated by [jerry_debugger_transport_malloc](#jerry_debugger_transport_malloc) + +**Prototype** + +```c +void jerry_debugger_transport_free (void *mem_p, size_t size); +``` + +- `header_p`: header of a transporation interface. +- `size`: total size of the transportation interface. + +## jerry_debugger_transport_add + +**Summary** + +Add a new interface to the transporation interface chain. The interface +will be the first item of the interface chain. + +**Prototype** + +```c +void jerry_debugger_transport_add (jerry_debugger_transport_header_t *header_p, + size_t send_message_header_size, size_t max_send_message_size, + size_t receive_message_header_size, size_t max_receive_message_size); +``` + +- `header_p`: header of a transporation interface. +- `send_message_header_size`: size of the outgoing message header, can be 0. +- `max_send_message_size`: maximum outgoing message size supported by the interface. +- `receive_message_header_size`: size of the incoming message header, can be 0. +- `max_receive_message_size`: maximum incoming message size supported by the interface. + +## jerry_debugger_transport_start + +**Summary** + +Starts the communication to the debugger client. Must be called after the +connection is successfully established. + +**Prototype** + +```c +void jerry_debugger_transport_start (void); +``` + +## jerry_debugger_transport_is_connected + +**Summary** + +Tells whether a debugger client is connected to the debugger server. + +**Prototype** + +```c +bool jerry_debugger_transport_is_connected (void); +``` + +- return value: `true`, if a client is connected, `false` otherwise. + +## jerry_debugger_transport_close + +**Summary** + +Disconnect from the current debugger client. It does nothing if a client is +not connected, + +**Prototype** + +```c +void jerry_debugger_transport_close (void); +``` + +## jerry_debugger_transport_send + +**Summary** + +Send message to the client. + +**Prototype** + +```c +bool jerry_debugger_transport_send (const uint8_t *message_p, size_t message_length); +``` + +- `message_p`: message to be sent. +- `message_length`: message length in bytes. +- return value: `true`, if a client is still connected, `false` otherwise. + +## jerry_debugger_transport_receive + +**Summary** + +Receive message from the client. + +**Prototype** + +```c +bool jerry_debugger_transport_receive (jerry_debugger_transport_receive_context_t *context_p); +``` + +- `context_p`: an unused [jerry_debugger_transport_receive_context_t](#jerry_debugger_transport_receive_context_t). +- return value: `true`, if a client is still connected, `false` otherwise. + +## jerry_debugger_transport_receive_completed + +**Summary** + +Must be called after [jerry_debugger_transport_receive](#jerry_debugger_transport_receive) +returns with a valid message. Must not be called otherwise. + +**Prototype** + +```c +void jerry_debugger_transport_receive_completed (jerry_debugger_transport_receive_context_t *context_p); +``` + +- `context_p`: a [jerry_debugger_transport_receive_context_t](#jerry_debugger_transport_receive_context_t) + passed to [jerry_debugger_transport_receive](#jerry_debugger_transport_receive). + +## jerry_debugger_transport_sleep + +**Summary** + +Can be used to wait for incoming messages. Currently the delay is 100ms. + +**Prototype** + +```c +void jerry_debugger_transport_sleep (void); +```