Rework snapshot execution api. (#2270)

The _at functions replaces the original functions.

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com

1 files changed, 49 insertions, 117 deletions

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index 307ef532..56d8ef8b 100644
--- a/docs/02.API-REFERENCE.md
+++ b/docs/02.API-REFERENCE.md
@@ -72,19 +72,40 @@ Snapshots contain literal pools, and these literal pools contain references
 to constant literals (strings, numbers, etc.). When a snapshot is executed,
 these literals are converted to jerry values and the literal pool entries
 are changed to their corresponding jerry value. To support this conversion,
-the literals and literal pools are copied into RAM even if the `copy_bytecode`
-flag passed to [jerry_exec_snapshot_at](#jerry_exec_snapshot_at) is set to
-`false`. This non-negligible memory consumption can be avoided by using
-static snapshots. The literals of these snapshots are limited to magic
-strings, and 28 bit signed integers, so their constant pools do not need
-to be loaded into the memory. Hence these snapshots can be executed from
-ROM.
+the literals and literal pools are copied into RAM even if the
+`JERRY_SNAPSHOT_EXEC_COPY_DATA` option is passed to
+[jerry_exec_snapshot](#jerry_exec_snapshot). This non-negligible memory
+consumption can be avoided by using static snapshots. The literals of
+these snapshots are limited to magic strings and 28 bit signed integers,
+so their constant pools do not need to be loaded into the memory.
+Hence these snapshots can be executed from ROM.
 
-***Important note:*** the magic strings set by
-[jerry_register_magic_strings](#jerry_register_magic_strings) must be the
-same when the snapshot is generated and executed. Furthermore the
-`copy_bytecode` flag of [jerry_exec_snapshot_at](#jerry_exec_snapshot_at)
-must be set to `false`.
+***Important note:*** The [jerry_exec_snapshot](#jerry_exec_snapshot)
+function rejects static snaphots unless the `JERRY_SNAPSHOT_EXEC_ALLOW_STATIC`
+option bit is set. The caller must also ensure that the same magic
+strings are set by [jerry_register_magic_strings](#jerry_register_magic_strings)
+when the snapshot is generated and executed. Furthermore the
+`JERRY_SNAPSHOT_EXEC_COPY_DATA` option is not allowed.
+
+## jerry_exec_snapshot_opts_t
+
+Flags for [jerry_exec_snapshot](#jerry_exec_snapshot) and
+[jerry_load_function_snapshot](#jerry_load_function_snapshot) functions:
+
+ - JERRY_SNAPSHOT_EXEC_COPY_DATA - copy snapshot data into memory (see below)
+ - JERRY_SNAPSHOT_EXEC_ALLOW_STATIC - allow executing static snapshots
+
+**Copy snapshot data into memory**
+
+By default the snapshot buffer is expected to be present in memory until
+[jerry_cleanup](#jerry_cleanup) is called. For example `static const` buffers
+compiled into the application binary satisfy this requirement.
+
+If the snapshot buffer is freed after [jerry_exec_snapshot](#jerry_exec_snapshot)
+is called the `JERRY_SNAPSHOT_EXEC_COPY_DATA` must be passed to copy the necessary
+parts of the snapshot buffer into memory.
+
+The `JERRY_SNAPSHOT_EXEC_COPY_DATA` option is not allowed for static snapshots.
 
 
 ## jerry_char_t
@@ -5121,15 +5142,14 @@ is no longer needed.
 jerry_value_t
 jerry_exec_snapshot (const uint32_t *snapshot_p,
                      size_t snapshot_size,
-                     bool copy_bytecode);
+                     size_t func_index,
+                     uint32_t exec_snapshot_opts);
 ```
 
 - `snapshot_p` - pointer to snapshot
 - `snapshot_size` - size of snapshot
-- `copy_bytecode` - flag, indicating whether the passed snapshot buffer should be copied to the
-   engine's memory. If set the engine should not reference the buffer after the function returns
-   (in this case, the passed buffer could be freed after the call). Otherwise (if the flag is not
-   set) - the buffer could only be freed after the engine stops (i.e. after call to jerry_cleanup).
+- `func_index` - index of executed function
+- `exec_snapshot_opts` - any combination of [jerry_exec_snapshot_opts_t](#jerry_exec_snapshot_opts_t) flags.
 - return value
   - result of bytecode, if run was successful
   - thrown error, otherwise
@@ -5168,7 +5188,8 @@ main (void)
 
   jerry_value_t res = jerry_exec_snapshot (global_mode_snapshot_buffer,
                                            global_mode_snapshot_size,
-                                           false);
+                                           0,
+                                           0);
   jerry_release_value (res);
 
   jerry_cleanup ();
@@ -5179,96 +5200,10 @@ main (void)
 
 - [jerry_init](#jerry_init)
 - [jerry_cleanup](#jerry_cleanup)
-- [jerry_exec_snapshot_at](#jerry_exec_snapshot_at)
-- [jerry_parse_and_save_snapshot](#jerry_parse_and_save_snapshot)
-
-
-## jerry_exec_snapshot_at
-
-**Summary**
-
-Execute the selected snapshot function from the specified buffer.
-
-Same function as [jerry_exec_snapshot](#jerry_exec_snapshot) except
-the executed function index can be specified.
-
-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
-is no longer needed.
-
-**Prototype**
-
-```c
-jerry_value_t
-jerry_exec_snapshot_at (const uint32_t *snapshot_p,
-                        size_t snapshot_size,
-                        size_t func_index,
-                        bool copy_bytecode);
-```
-
-- `snapshot_p` - pointer to snapshot
-- `snapshot_size` - size of snapshot
-- `func_index` - index of executed function
-- `copy_bytecode` - flag, indicating whether the passed snapshot buffer should be copied to the
-   engine's memory. If set the engine should not reference the buffer after the function returns
-   (in this case, the passed buffer could be freed after the call). Otherwise (if the flag is not
-   set) - the buffer could only be freed after the engine stops (i.e. after call to jerry_cleanup).
-- return value
-  - result of bytecode, if run was successful
-  - thrown error, otherwise
-
-**Example**
-
-[doctest]: # ()
-
-```c
-#include <string.h>
-#include "jerryscript.h"
-
-int
-main (void)
-{
-  static uint32_t global_mode_snapshot_buffer[256];
-  const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
-
-  jerry_init (JERRY_INIT_EMPTY);
-
-  jerry_value_t generate_result;
-  generate_result = jerry_generate_snapshot (NULL,
-                                             0,
-                                             code_to_snapshot_p,
-                                             strlen ((const char *) code_to_snapshot_p),
-                                             0,
-                                             global_mode_snapshot_buffer,
-                                             sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
-
-  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_at (global_mode_snapshot_buffer,
-                                              global_mode_snapshot_size,
-                                              0,
-                                              false);
-
-  jerry_release_value (res);
-
-  jerry_cleanup ();
-  return 0;
-}
-```
-
-**See also**
-
-- [jerry_init](#jerry_init)
-- [jerry_cleanup](#jerry_cleanup)
-- [jerry_exec_snapshot](#jerry_exec_snapshot)
 - [jerry_parse_and_save_snapshot](#jerry_parse_and_save_snapshot)
 
 
-## jerry_load_function_snapshot_at
+## jerry_load_function_snapshot
 
 **Summary**
 
@@ -5283,19 +5218,16 @@ is no longer needed.
 
 ```c
 jerry_value_t
-jerry_load_function_snapshot_at (const uint32_t *snapshot_p,
-                                 size_t snapshot_size,
-                                 size_t func_index,
-                                 bool copy_bytecode);
+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
 - `func_index` - index of function to load
-- `copy_bytecode` - flag, indicating whether the passed snapshot buffer should be copied to the
-   engine's memory. If set the engine should not reference the buffer after the function returns
-   (in this case, the passed buffer could be freed after the call). Otherwise (if the flag is not
-   set) - the buffer could only be freed after the engine stops (i.e. after call to jerry_cleanup).
+- `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
@@ -5335,10 +5267,10 @@ main (void)
 
   jerry_init (JERRY_INIT_EMPTY);
 
-  jerry_value_t func = jerry_load_function_snapshot_at (snapshot_buffer,
-                                                        snapshot_size,
-                                                        0,
-                                                        false);
+  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 this_value = jerry_create_undefined ();