Support native modules (#4649)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com
2021-04-13 16:26:38 +02:00
parent 05a4e45ece
commit 7b6743403f
15 changed files with 770 additions and 100 deletions
@@ -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).