diff options
author | Zoltan Herczeg <zherczeg.u-szeged@partner.samsung.com> | 2021-04-13 16:26:38 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2021-04-13 16:26:38 +0200 |
commit | 7b6743403fe2cfcd20473c9456cfc3fdd60ab07b (patch) | |
tree | 581214f4dd20bee3ddf19fe55901f0e219d33f7c /docs/02.API-REFERENCE.md | |
parent | 05a4e45ecea0ca056e0eb3f8e96d6c3a9d6c4149 (diff) |
Support native modules (#4649)
JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com
Diffstat (limited to 'docs/02.API-REFERENCE.md')
-rw-r--r-- | docs/02.API-REFERENCE.md | 219 |
1 files changed, 218 insertions, 1 deletions
diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md index b567814e..e9b2fcf9 100644 --- a/docs/02.API-REFERENCE.md +++ b/docs/02.API-REFERENCE.md @@ -786,7 +786,6 @@ An enum representing the current status of a module - JERRY_MODULE_STATE_EVALUATING - Module is currently being evaluated - JERRY_MODULE_STATE_EVALUATED - Module has been evaluated (its source code has been executed) - JERRY_MODULE_STATE_ERROR - An error has been encountered before the evaluated state is reached - - JERRY_MODULE_STATE_NATIVE - Module is native module *New in version [[NEXT_RELEASE]]*. @@ -821,6 +820,32 @@ typedef jerry_value_t (*jerry_module_resolve_callback_t) (const jerry_value_t sp - [jerry_module_link](#jerry_module_link) - [jerry_get_global_object](#jerry_get_global_object) +## jerry_native_module_evaluate_callback_t + +**Summary** + +Callback which is called by [jerry_module_evaluate](#jerry_module_evaluate) to evaluate the native module. + +Note: + - Native pointers can be used to assign private data to a native module, + see [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) + +**Prototype** + +```c +typedef jerry_value_t (*jerry_native_module_evaluate_callback_t) (const jerry_value_t native_module); +``` + +- `native_module` - a native module +- return value + - any non-error value - if the module is evaluated successfully + - an error - otherwise + +*New in version [[NEXT_RELEASE]]*. + +**See also** +- [jerry_module_evaluate](#jerry_module_evaluate) + ## jerry_backtrace_callback_t **Summary** @@ -4743,6 +4768,198 @@ main (void) - [jerry_module_link](#jerry_module_link) - [jerry_module_evaluate](#jerry_module_evaluate) +## jerry_native_module_create + +Creates a native module with a list of exports. The initial state of the module is linked. + +*Notes*: +- Returned value must be freed with [jerry_release_value](#jerry_release_value) + when it is no longer needed. +- Native pointers can be used to assign private data to a native module, + see [jerry_set_object_native_pointer](#jerry_set_object_native_pointer) +- When `callback` is `NULL`, no function is called when the module is evaluated, + only its state is changed to evaluated. +- This API depends on a build option (`JERRY_MODULE_SYSTEM`) and can be checked + in runtime with the `JERRY_FEATURE_MODULE` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + +**Prototype** + +```c +jerry_value_t +jerry_native_module_create (jerry_native_module_evaluate_callback_t callback, + const jerry_value_t * const exports_p, + size_t number_of_exports); +``` + +- `callback` - a [jerry_native_module_evaluate_callback_t](#jerry_native_module_evaluate_callback_t) callback + which is called by [jerry_module_evaluate](#jerry_module_evaluate) to evaluate the native module. +- `exports_p` - list of the exported bindings of the module, must be valid string identifiers. +- `number_of_exports` - number of exports in the `exports_p` list. +- return + - a native module, if the module is successfully created + - error, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # (test="compile") + +```c +#include <jerryscript.h> + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t exports[2] = + { + jerry_create_string ((const jerry_char_t *) "first_export"), + jerry_create_string ((const jerry_char_t *) "second_export") + }; + + jerry_value_t native_module = jerry_native_module_create (NULL, exports, 2); + + jerry_release_value (exports[0]); + jerry_release_value (exports[1]); + jerry_release_value (native_module); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_module_link](#jerry_module_link) +- [jerry_module_evaluate](#jerry_module_evaluate) +- [jerry_native_module_get_export](#jerry_native_module_get_export) +- [jerry_native_module_set_export](#jerry_native_module_set_export) + +## jerry_native_module_get_export + +Gets the value of an export binding which belongs to a native module. + +*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_MODULE_SYSTEM`) and can be checked + in runtime with the `JERRY_FEATURE_MODULE` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + +**Prototype** + +```c +jerry_value_t +jerry_native_module_get_export (const jerry_value_t native_module_val, + const jerry_value_t export_name_val); +``` + +- `module_val` - a native module object. +- `export_name_val` - string identifier of the export. +- return + - value of the export, if success + - error, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # (test="compile") + +```c +#include <jerryscript.h> + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t export = jerry_create_string ((const jerry_char_t *) "an_export"); + + jerry_value_t native_module = jerry_native_module_create (NULL, &export, 1); + + jerry_value_t value = jerry_native_module_get_export (native_module, export); + jerry_release_value (value); + + jerry_release_value (export); + jerry_release_value (native_module); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_native_module_create](#jerry_native_module_create) +- [jerry_native_module_set_export](#jerry_native_module_set_export) + +## jerry_native_module_set_export + +Sets the value of an export binding which belongs to a native module. + +*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_MODULE_SYSTEM`) and can be checked + in runtime with the `JERRY_FEATURE_MODULE` feature enum value, + see: [jerry_is_feature_enabled](#jerry_is_feature_enabled). + +**Prototype** + +```c +jerry_value_t +jerry_value_t jerry_native_module_set_export (const jerry_value_t native_mmodule_val, + const jerry_value_t export_name_val, + const jerry_value_t value_to_set) +``` + +- `module_val` - a native module object. +- `export_name_val` - string identifier of the export. +- `value_to_set` - new value of the export. +- return + - true, if success + - error, otherwise + +*New in version [[NEXT_RELEASE]]*. + +**Example** + +[doctest]: # (test="compile") + +```c +#include <jerryscript.h> + +int +main (void) +{ + jerry_init (JERRY_INIT_EMPTY); + + jerry_value_t export = jerry_create_string ((const jerry_char_t *) "an_export"); + + jerry_value_t native_module = jerry_native_module_create (NULL, &export, 1); + + jerry_value_t number = jerry_create_number (3.5); + jerry_value_t value = jerry_native_module_set_export (native_module, export, number); + jerry_release_value (value); + jerry_release_value (number); + + jerry_release_value (export); + jerry_release_value (native_module); + + jerry_cleanup (); + return 0; +} +``` + +**See also** + +- [jerry_native_module_create](#jerry_native_module_create) +- [jerry_native_module_get_export](#jerry_native_module_get_export) + # Functions for promise objects These APIs all depend on the es.next profile (or on some build options). |