From 9ff25dbc1220097b9dc04746bdf07a3b66c2e2d4 Mon Sep 17 00:00:00 2001 From: Zoltan Herczeg Date: Fri, 16 Jul 2021 16:09:51 +0200 Subject: [PATCH] Replace jerry_load_function_snapshot function with a flag (#4719) JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com --- docs/02.API-REFERENCE.md | 185 +++++++++------------- jerry-core/api/jerry-snapshot.c | 66 ++------ jerry-core/include/jerryscript-snapshot.h | 4 +- tests/unit-core/test-snapshot.c | 8 +- 4 files changed, 89 insertions(+), 174 deletions(-) diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md index 0c7b9ee1b..750231737 100644 --- a/docs/02.API-REFERENCE.md +++ b/docs/02.API-REFERENCE.md @@ -305,11 +305,14 @@ when the snapshot is generated and executed. Furthermore the ## jerry_exec_snapshot_opts_t -Flags for [jerry_exec_snapshot](#jerry_exec_snapshot) and -[jerry_load_function_snapshot](#jerry_load_function_snapshot) functions: +Flags for [jerry_exec_snapshot](#jerry_exec_snapshot) functions: - JERRY_SNAPSHOT_EXEC_COPY_DATA - copy snapshot data into memory (see below) - JERRY_SNAPSHOT_EXEC_ALLOW_STATIC - allow executing static snapshots + - JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION - load snapshot as function instead of executing it + +*Changed in version [[NEXT_RELEASE]]*: The `JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION` value is added, + which replaces the `jerry_load_function_snapshot` function. **Copy snapshot data into memory** @@ -10195,7 +10198,6 @@ 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) - [jerry_parse_options_t](#jerry_parse_options_t) @@ -10203,7 +10205,7 @@ main (void) **Summary** -Execute snapshot from the specified buffer. +Execute/load snapshot from the specified buffer. *Notes*: - Returned value must be freed with [jerry_release_value](#jerry_release_value) when it @@ -10232,94 +10234,7 @@ jerry_exec_snapshot (const uint32_t *snapshot_p, *Changed in version 2.0*: Added `func_index` and `exec_snapshot_opts` arguments. Removed the `copy_bytecode` last argument. -**Example** - -[doctest]: # () - -```c -#include "jerryscript.h" - -int -main (void) -{ - static uint32_t global_mode_snapshot_buffer[256]; - const jerry_char_t script_to_snapshot[] = "(function () { return 'string from snapshot'; }) ();"; - - jerry_init (JERRY_INIT_EMPTY); - - jerry_value_t generate_result; - generate_result = jerry_generate_snapshot (script_to_snapshot, - sizeof (script_to_snapshot) - 1, - NULL, - 0, - global_mode_snapshot_buffer, - sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t)); - // generate_result should be checked if it is an error or not - - size_t global_mode_snapshot_size = (size_t) jerry_get_number_value (generate_result); - jerry_release_value (generate_result); - - jerry_cleanup (); - - jerry_init (JERRY_INIT_EMPTY); - - jerry_value_t res = jerry_exec_snapshot (global_mode_snapshot_buffer, - global_mode_snapshot_size, - 0, - 0); - - // check the `res` value for error and process the result. - - jerry_release_value (res); - - jerry_cleanup (); - return 0; -} -``` - -**See also** - -- [jerry_init](#jerry_init) -- [jerry_cleanup](#jerry_cleanup) -- [jerry_parse_and_save_snapshot](#jerry_parse_and_save_snapshot) - - -## jerry_load_function_snapshot - -**Summary** - -Load the selected snapshot function from the specified buffer as a function object. - -The lexical environment of the loaded function is always the global lexical environment. - -*Notes*: -- Returned value must be freed with [jerry_release_value](#jerry_release_value) when it - is no longer needed. -- This API depends on a build option (`JERRY_SNAPSHOT_EXEC`) and can be checked in runtime with - the `JERRY_FEATURE_SNAPSHOT_EXEC` feature enum value, see [jerry_is_feature_enabled](#jerry_is_feature_enabled). - If the feature is not enabled the function will return an error. - -**Prototype** - -```c -jerry_value_t -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 in bytes. -- `func_index` - index of function to load from the snapshot. -- `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. - -*New in version 2.0*. - -**Example** +**Example 1** [doctest]: # () @@ -10330,33 +10245,80 @@ int main (void) { static uint32_t snapshot_buffer[256]; - const jerry_char_t func_args[] = "a, b"; - const jerry_char_t func_src[] = "return a + b;"; + /* 1st example: global mode snapshot. */ jerry_init (JERRY_INIT_EMPTY); + const jerry_char_t script_to_snapshot[] = "(function () { return 'string from snapshot'; }) ();"; + jerry_value_t generate_result; - generate_result = jerry_generate_function_snapshot (func_src, - sizeof (func_src) - 1, - func_args, - sizeof (func_args) - 1, - NULL, - 0, - snapshot_buffer, - sizeof (snapshot_buffer) / sizeof (uint32_t)); + generate_result = jerry_generate_snapshot (script_to_snapshot, + sizeof (script_to_snapshot) - 1, + NULL, + 0, + snapshot_buffer, + sizeof (snapshot_buffer) / sizeof (uint32_t)); + /* 'generate_result' variable should be checked whether it contains an error. */ 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 (snapshot_buffer, - snapshot_size, - 0, - 0); - /* 'func' can be used now as a function object */ + jerry_value_t res = jerry_exec_snapshot (snapshot_buffer, + snapshot_size, + 0, + 0); + + /* 'res' now contains 'string from snapshot' */ + jerry_release_value (res); + + jerry_cleanup (); + return 0; +} +``` + +**Example 2** + +[doctest]: # () + +```c +#include "jerryscript.h" + +int +main (void) +{ + static uint32_t snapshot_buffer[256]; + + /* 2nd example: function snapshot. */ + jerry_init (JERRY_INIT_EMPTY); + + const jerry_char_t function_to_snapshot_args[] = "a, b"; + const jerry_char_t function_to_snapshot[] = "return a + b;"; + + jerry_value_t generate_result; + generate_result = jerry_generate_function_snapshot (function_to_snapshot, + sizeof (function_to_snapshot) - 1, + function_to_snapshot_args, + sizeof (function_to_snapshot_args) - 1, + NULL, + 0, + snapshot_buffer, + sizeof (snapshot_buffer) / sizeof (uint32_t)); + /* 'generate_result' variable should be checked whether it contains an error. */ + + 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_exec_snapshot (snapshot_buffer, + snapshot_size, + 0, + JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION); + /* 'func' can be used now as a function object. */ jerry_value_t this_value = jerry_create_undefined (); jerry_value_t args[2]; @@ -10365,8 +10327,8 @@ main (void) jerry_value_t res = jerry_call_function (func, this_value, args, 2); - /* 'res' now contains the value 3 as a jerry_value_t */ - + /* 'res' now contains the value 3 as a jerry_value_t. */ + jerry_release_value (res); jerry_release_value (args[0]); jerry_release_value (args[1]); jerry_release_value (this_value); @@ -10381,7 +10343,8 @@ main (void) - [jerry_init](#jerry_init) - [jerry_cleanup](#jerry_cleanup) -- [jerry_parse_and_save_function_snapshot](#jerry_parse_and_save_function_snapshot) +- [jerry_generate_snapshot](#jerry_generate_snapshot) +- [jerry_generate_function_snapshot](#jerry_generate_function_snapshot) ## jerry_get_literals_from_snapshot diff --git a/jerry-core/api/jerry-snapshot.c b/jerry-core/api/jerry-snapshot.c index 214c7dd2e..244712fe0 100644 --- a/jerry-core/api/jerry-snapshot.c +++ b/jerry-core/api/jerry-snapshot.c @@ -917,7 +917,6 @@ jerry_generate_snapshot (const jerry_char_t *source_p, /**< script source */ #endif /* JERRY_SNAPSHOT_SAVE */ } /* jerry_generate_snapshot */ -#if JERRY_SNAPSHOT_EXEC /** * Execute/load snapshot from specified buffer * @@ -927,16 +926,18 @@ jerry_generate_snapshot (const jerry_char_t *source_p, /**< script source */ * @return result of bytecode - if run was successful * thrown error - otherwise */ -static jerry_value_t -jerry_snapshot_result (const uint32_t *snapshot_p, /**< snapshot */ - size_t snapshot_size, /**< size of snapshot */ - size_t func_index, /**< index of primary function */ - uint32_t exec_snapshot_opts, /**< jerry_exec_snapshot_opts_t option bits */ - bool as_function) /** < specify if the loaded snapshot should be returned as a function */ +jerry_value_t +jerry_exec_snapshot (const uint32_t *snapshot_p, /**< snapshot */ + size_t snapshot_size, /**< size of snapshot */ + size_t func_index, /**< index of primary function */ + uint32_t exec_snapshot_opts) /**< jerry_exec_snapshot_opts_t option bits */ { +#if JERRY_SNAPSHOT_EXEC JERRY_ASSERT (snapshot_p != NULL); - uint32_t allowed_opts = (JERRY_SNAPSHOT_EXEC_COPY_DATA | JERRY_SNAPSHOT_EXEC_ALLOW_STATIC); + uint32_t allowed_opts = (JERRY_SNAPSHOT_EXEC_COPY_DATA + | JERRY_SNAPSHOT_EXEC_ALLOW_STATIC + | JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION); if ((exec_snapshot_opts & ~(allowed_opts)) != 0) { @@ -1018,7 +1019,7 @@ jerry_snapshot_result (const uint32_t *snapshot_p, /**< snapshot */ ecma_value_t ret_val; - if (as_function) + if (exec_snapshot_opts & JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION) { ecma_object_t *global_object_p = ecma_builtin_get_global (); @@ -1057,26 +1058,6 @@ jerry_snapshot_result (const uint32_t *snapshot_p, /**< snapshot */ } return ret_val; -} /* jerry_snapshot_result */ -#endif /* JERRY_SNAPSHOT_EXEC */ - -/** - * Execute snapshot from specified buffer - * - * Note: - * returned value must be freed with jerry_release_value, when it is no longer needed. - * - * @return result of bytecode - if run was successful - * thrown error - otherwise - */ -jerry_value_t -jerry_exec_snapshot (const uint32_t *snapshot_p, /**< snapshot */ - size_t snapshot_size, /**< size of snapshot */ - size_t func_index, /**< index of primary function */ - uint32_t exec_snapshot_opts) /**< jerry_exec_snapshot_opts_t option bits */ -{ -#if JERRY_SNAPSHOT_EXEC - return jerry_snapshot_result (snapshot_p, snapshot_size, func_index, exec_snapshot_opts, false); #else /* !JERRY_SNAPSHOT_EXEC */ JERRY_UNUSED (snapshot_p); JERRY_UNUSED (snapshot_size); @@ -1833,30 +1814,3 @@ jerry_generate_function_snapshot (const jerry_char_t *source_p, /**< script sour return jerry_create_error (JERRY_ERROR_COMMON, (const jerry_char_t *) "Snapshot save is not supported"); #endif /* JERRY_SNAPSHOT_SAVE */ } /* jerry_generate_function_snapshot */ - -/** - * Load function from specified snapshot buffer - * - * Note: - * returned value must be freed with jerry_release_value, when it is no longer needed. - * - * @return result of bytecode - if run was successful - * thrown error - otherwise - */ -jerry_value_t -jerry_load_function_snapshot (const uint32_t *function_snapshot_p, /**< snapshot of the function(s) */ - const size_t function_snapshot_size, /**< size of the snapshot */ - size_t func_index, /**< index of the function to load */ - uint32_t exec_snapshot_opts) /**< jerry_exec_snapshot_opts_t option bits */ -{ -#if JERRY_SNAPSHOT_EXEC - return jerry_snapshot_result (function_snapshot_p, function_snapshot_size, func_index, exec_snapshot_opts, true); -#else /* !JERRY_SNAPSHOT_EXEC */ - JERRY_UNUSED (function_snapshot_p); - JERRY_UNUSED (function_snapshot_size); - JERRY_UNUSED (func_index); - JERRY_UNUSED (exec_snapshot_opts); - - return jerry_create_error (JERRY_ERROR_COMMON, (const jerry_char_t *) "Snapshot execution is not supported"); -#endif /* JERRY_SNAPSHOT_EXEC */ -} /* jerry_load_function_snapshot */ diff --git a/jerry-core/include/jerryscript-snapshot.h b/jerry-core/include/jerryscript-snapshot.h index c3796eaa7..c984ce547 100644 --- a/jerry-core/include/jerryscript-snapshot.h +++ b/jerry-core/include/jerryscript-snapshot.h @@ -47,6 +47,7 @@ typedef enum { JERRY_SNAPSHOT_EXEC_COPY_DATA = (1u << 0), /**< copy snashot data */ JERRY_SNAPSHOT_EXEC_ALLOW_STATIC = (1u << 1), /**< static snapshots allowed */ + JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION = (1u << 2), /**< load snapshot as function instead of executing it */ } jerry_exec_snapshot_opts_t; /** @@ -63,9 +64,6 @@ jerry_value_t jerry_generate_function_snapshot (const jerry_char_t *source_p, si jerry_value_t jerry_exec_snapshot (const uint32_t *snapshot_p, size_t snapshot_size, size_t func_index, uint32_t exec_snapshot_opts); -jerry_value_t jerry_load_function_snapshot (const uint32_t *function_snapshot_p, - const size_t function_snapshot_size, - size_t func_index, uint32_t exec_snapshot_opts); size_t jerry_merge_snapshots (const uint32_t **inp_buffers_p, size_t *inp_buffer_sizes_p, size_t number_of_snapshots, uint32_t *out_buffer_p, size_t out_buffer_size, const char **error_p); diff --git a/tests/unit-core/test-snapshot.c b/tests/unit-core/test-snapshot.c index 9f992abe3..1e628054f 100644 --- a/tests/unit-core/test-snapshot.c +++ b/tests/unit-core/test-snapshot.c @@ -86,10 +86,10 @@ static void test_function_snapshot (void) jerry_init (flags); - jerry_value_t function_obj = jerry_load_function_snapshot (function_snapshot_buffer, - function_snapshot_size, - 0, - 0); + jerry_value_t function_obj = jerry_exec_snapshot (function_snapshot_buffer, + function_snapshot_size, + 0, + JERRY_SNAPSHOT_EXEC_LOAD_AS_FUNCTION); TEST_ASSERT (!jerry_value_is_error (function_obj)); TEST_ASSERT (jerry_value_is_function (function_obj));