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

4 files changed, 52 insertions, 137 deletions

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index 0c7b9ee1..75023173 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,7 +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**
+**Example 1**
 
 [doctest]: # ()
 
@@ -10242,34 +10244,34 @@ jerry_exec_snapshot (const uint32_t *snapshot_p,
 int
 main (void)
 {
-  static uint32_t global_mode_snapshot_buffer[256];
-  const jerry_char_t script_to_snapshot[] = "(function () { return 'string from snapshot'; }) ();";
+  static uint32_t snapshot_buffer[256];
 
+  /* 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_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
+                                             snapshot_buffer,
+                                             sizeof (snapshot_buffer) / sizeof (uint32_t));
+  /* 'generate_result' variable should be checked whether it contains an error. */
 
-  size_t global_mode_snapshot_size = (size_t) jerry_get_number_value (generate_result);
+  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 res = jerry_exec_snapshot (global_mode_snapshot_buffer,
-                                           global_mode_snapshot_size,
+  jerry_value_t res = jerry_exec_snapshot (snapshot_buffer,
+                                           snapshot_size,
                                            0,
                                            0);
 
-  // check the `res` value for error and process the result.
-
+  /* 'res' now contains 'string from snapshot' */
   jerry_release_value (res);
 
   jerry_cleanup ();
@@ -10277,49 +10279,7 @@ main (void)
 }
 ```
 
-**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 2**
 
 [doctest]: # ()
 
@@ -10330,33 +10290,35 @@ 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;";
 
+  /* 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 (func_src,
-                                                      sizeof (func_src) - 1,
-                                                      func_args,
-                                                      sizeof (func_args) - 1,
+  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_load_function_snapshot (snapshot_buffer,
-                                                     snapshot_size,
-                                                     0,
-                                                     0);
-  /* 'func' can be used now as a function object */
+  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 214c7dd2..244712fe 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 c3796eaa..c984ce54 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 9f992abe..1e628054 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));