Rework snapshot generation API. (#2259)

Also remove eval context support. It provides no practical advantage.

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

1 files changed, 129 insertions, 207 deletions

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index 8ca2c622..307ef532 100644
--- a/docs/02.API-REFERENCE.md
+++ b/docs/02.API-REFERENCE.md
@@ -59,6 +59,34 @@ Possible compile time enabled feature types:
  - JERRY_FEATURE_DATE - Date support
  - JERRY_FEATURE_REGEXP - RegExp support
 
+## jerry_generate_snapshot_opts_t
+
+Flags for [jerry_generate_snapshot](#jerry_generate_snapshot) and
+[jerry_generate_function_snapshot](#jerry_generate_function_snapshot) functions:
+
+ - JERRY_SNAPSHOT_SAVE_STATIC - generate static snapshot (see below)
+ - JERRY_SNAPSHOT_SAVE_STRICT - strict source code provided
+
+**Generate static snapshots**
+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.
+
+***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`.
+
+
 ## jerry_char_t
 
 **Summary**
@@ -4923,7 +4951,7 @@ main (void)
 
 # Snapshot functions
 
-## jerry_parse_and_save_snapshot
+## jerry_generate_snapshot
 
 **Summary**
 
@@ -4932,26 +4960,28 @@ Generate snapshot from the specified source code.
 **Prototype**
 
 ```c
-size_t
-jerry_parse_and_save_snapshot (const jerry_char_t *source_p,
-                               size_t source_size,
-                               bool is_for_global,
-                               bool is_strict,
-                               uint32_t *buffer_p,
-                               size_t buffer_size);
+jerry_value_t
+jerry_generate_snapshot (const jerry_char_t *resource_name_p,
+                         size_t resource_name_length,
+                         const jerry_char_t *source_p,
+                         size_t source_size,
+                         uint32_t generate_snapshot_opts,
+                         uint32_t *buffer_p,
+                         size_t buffer_size);
 ```
 
+- `resource_name_p` - resource (file) name of the source code. Currently unused, the debugger may use it in the future.
+- `resource_name_length` - length of resource name.
 - `source_p` - script source, it must be a valid utf8 string.
 - `source_size` - script source size, in bytes.
-- `is_for_global` - snapshot would be executed as global (true) or eval (false).
-- `is_strict` - strict mode
+- `generate_snapshot_opts` - any combination of [jerry_generate_snapshot_opts_t](#jerry_generate_snapshot_opts_t) flags.
 - `buffer_p` - buffer to save snapshot to.
 - `buffer_size` - the buffer's size.
 - return value
-  - the size of snapshot, if it was generated succesfully (i.e. there are no syntax errors in source
-    code, buffer size is sufficient, and snapshot support is enabled in current configuration through
-    JERRY_ENABLE_SNAPSHOT_SAVE)
-  - 0 otherwise.
+  - the size of the snapshot as a number value, if it was generated succesfully (i.e. there are no syntax
+    errors in source code, buffer size is sufficient, and snapshot support is enabled in current configuration
+    through JERRY_ENABLE_SNAPSHOT_SAVE)
+  - thrown error, otherwise.
 
 **Example**
 
@@ -4969,82 +4999,17 @@ 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'; }) ();";
 
-  size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p,
-                                                                    strlen ((const char *) code_to_snapshot_p),
-                                                                    true,
-                                                                    false,
-                                                                    global_mode_snapshot_buffer,
-                                                                    sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
+  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));
 
-  jerry_cleanup ();
-}
-```
-
-**See also**
-
-- [jerry_init](#jerry_init)
-- [jerry_cleanup](#jerry_cleanup)
-- [jerry_exec_snapshot](#jerry_exec_snapshot)
-- [jerry_parse_and_save_static_snapshot](#jerry_parse_and_save_static_snapshot)
-
-
-## jerry_parse_and_save_static_snapshot
-
-**Summary**
-
-Generate static snapshot from the specified source code.
-
-Unlike normal snaphots static snaphots are fully executed from ROM. Not
-even their header is loaded into the RAM. However they can only depend
-on magic strings and 28 bit integer numbers. Regular expression literals
-are not supported as well.
-
-**Prototype**
-
-```c
-size_t
-jerry_parse_and_save_static_snapshot (const jerry_char_t *source_p,
-                                      size_t source_size,
-                                      bool is_for_global,
-                                      bool is_strict,
-                                      uint32_t *buffer_p,
-                                      size_t buffer_size);
-```
-
-- `source_p` - script source, it must be a valid utf8 string.
-- `source_size` - script source size, in bytes.
-- `is_for_global` - snapshot would be executed as global (true) or eval (false).
-- `is_strict` - strict mode
-- `buffer_p` - buffer to save snapshot to.
-- `buffer_size` - the buffer's size.
-- return value
-  - the size of snapshot, if it was generated succesfully (i.e. there are no syntax errors in source
-    code, buffer size is sufficient, only magic strings are used by the snapshot, and snapshot support
-    is enabled in current configuration through JERRY_ENABLE_SNAPSHOT_SAVE)
-  - 0 otherwise.
-
-**Example**
-
-[doctest]: # ()
-
-```c
-#include <string.h>
-#include "jerryscript.h"
-
-int
-main (void)
-{
-  jerry_init (JERRY_INIT_EMPTY);
-
-  static uint32_t global_mode_snapshot_buffer[256];
-  const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string'; }) ();";
-
-  size_t global_mode_snapshot_size = jerry_parse_and_save_static_snapshot (code_to_snapshot_p,
-                                                                           strlen ((const char *) code_to_snapshot_p),
-                                                                           true,
-                                                                           false,
-                                                                           global_mode_snapshot_buffer,
-                                                                           sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
+  size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
+  jerry_release_value (generate_result);
 
   jerry_cleanup ();
 }
@@ -5054,11 +5019,11 @@ main (void)
 
 - [jerry_init](#jerry_init)
 - [jerry_cleanup](#jerry_cleanup)
+- [jerry_generate_function_snapshot](#jerry_generate_function_snapshot)
 - [jerry_exec_snapshot](#jerry_exec_snapshot)
-- [jerry_parse_and_save_snapshot](#jerry_parse_and_save_snapshot)
 
 
-## jerry_parse_and_save_function_snapshot
+## jerry_generate_function_snapshot
 
 **Summary**
 
@@ -5071,28 +5036,32 @@ passed as separated arguments.
 **Prototype**
 
 ```c
-size_t
-jerry_parse_and_save_function_snapshot (const jerry_char_t *source_p,
-                                        size_t source_size,
-                                        const jerry_char_t *args_p,
-                                        size_t args_size,
-                                        bool is_strict,
-                                        uint32_t *buffer_p,
-                                        size_t buffer_size)
-```
-
+jerry_value_t
+jerry_generate_function_snapshot (const jerry_char_t *resource_name_p,
+                                  size_t resource_name_length,
+                                  const jerry_char_t *source_p,
+                                  size_t source_size,
+                                  const jerry_char_t *args_p,
+                                  size_t args_size,
+                                  uint32_t generate_snapshot_opts,
+                                  uint32_t *buffer_p,
+                                  size_t buffer_size)
+```
+
+- `resource_name_p` - resource (file) name of the source code. Currently unused, the debugger may use it in the future.
+- `resource_name_length` - length of resource name.
 - `source_p` - script source, it must be a valid utf8 string.
 - `source_size` - script source size, in bytes.
 - `args_p` - function arguments, it must be a valid utf8 string.
 - `args_size` - function argument size, in bytes.
-- `is_strict` - strict mode
+- `generate_snapshot_opts` - any combination of [jerry_generate_snapshot_opts_t](#jerry_generate_snapshot_opts_t) flags.
 - `buffer_p` - buffer to save snapshot to.
 - `buffer_size` - the buffer's size.
 - return value
-  - the size of snapshot, if it was generated succesfully (i.e. there are no syntax errors in source
-    code, buffer size is sufficient, and snapshot support is enabled in current configuration through
-    JERRY_ENABLE_SNAPSHOT_SAVE)
-  - 0 otherwise.
+  - the size of the snapshot as a number value, if it was generated succesfully (i.e. there are no syntax
+    errors in source code, buffer size is sufficient, and snapshot support is enabled in current configuration
+    through JERRY_ENABLE_SNAPSHOT_SAVE)
+  - thrown error, otherwise.
 
 **Example**
 
@@ -5111,88 +5080,19 @@ main (void)
   const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
   const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";
 
-  size_t func_snapshot_size = jerry_parse_and_save_function_snapshot (src_p,
-                                                                      strlen ((const char *) src_p),
-                                                                      args_p,
-                                                                      strlen ((const char *) args_p),
-                                                                      false,
-                                                                      func_snapshot_buffer,
-                                                                      sizeof (func_snapshot_buffer) / sizeof (uint32_t));
-
-  jerry_cleanup ();
-}
-```
-
-**See also**
-
-- [jerry_init](#jerry_init)
-- [jerry_cleanup](#jerry_cleanup)
-- [jerry_load_function_snapshot_at](#jerry_load_function_snapshot_at)
-- [jerry_parse_and_save_static_function_snapshot](#jerry_parse_and_save_static_function_snapshot)
-
-
-## jerry_parse_and_save_static_function_snapshot
-
-**Summary**
+  jerry_value_t generate_result;
+  generate_result = jerry_generate_function_snapshot (NULL,
+                                                      0,
+                                                      src_p,
+                                                      strlen ((const char *) src_p),
+                                                      args_p,
+                                                      strlen ((const char *) args_p),
+                                                      0,
+                                                      func_snapshot_buffer,
+                                                      sizeof (func_snapshot_buffer) / sizeof (uint32_t));
 
-Generate static function snapshot from the specified source code
-with the given function body and arguments.
-
-Unlike normal snaphots static snaphots are fully executed from ROM. Not
-even their header is loaded into the RAM. However they can only depend
-on magic strings and 28 bit integer numbers. Regular expression literals
-are not supported as well.
-
-**Prototype**
-
-```c
-size_t
-jerry_parse_and_save_static_function_snapshot (const jerry_char_t *source_p,
-                                               size_t source_size,
-                                               const jerry_char_t *args_p,
-                                               size_t args_size,
-                                               bool is_strict,
-                                               uint32_t *buffer_p,
-                                               size_t buffer_size)
-```
-
-- `source_p` - script source, it must be a valid utf8 string.
-- `source_size` - script source size, in bytes.
-- `args_p` - function arguments, it must be a valid utf8 string.
-- `args_size` - function argument size, in bytes.
-- `is_strict` - strict mode
-- `buffer_p` - buffer to save snapshot to.
-- `buffer_size` - the buffer's size.
-- return value
-  - the size of snapshot, if it was generated succesfully (i.e. there are no syntax errors in source
-    code, buffer size is sufficient, only magic strings are used by the snapshot, and snapshot support
-    is enabled in current configuration through JERRY_ENABLE_SNAPSHOT_SAVE)
-  - 0 otherwise.
-
-**Example**
-
-[doctest]: # ()
-
-```c
-#include <string.h>
-#include "jerryscript.h"
-
-int
-main (void)
-{
-  jerry_init (JERRY_INIT_EMPTY);
-
-  static uint32_t func_snapshot_buffer[256];
-  const jerry_char_t *args_p = (const jerry_char_t *) "string, bind";
-  const jerry_char_t *src_p = (const jerry_char_t *) "return bind(string)";
-
-  size_t func_snapshot_size = jerry_parse_and_save_static_function_snapshot (src_p,
-                                                                             strlen ((const char *) src_p),
-                                                                             args_p,
-                                                                             strlen ((const char *) args_p),
-                                                                             false,
-                                                                             func_snapshot_buffer,
-                                                                             sizeof (func_snapshot_buffer) / sizeof (uint32_t));
+  size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
+  jerry_release_value (generate_result);
 
   jerry_cleanup ();
 }
@@ -5202,8 +5102,8 @@ 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_and_save_function_snapshot](#jerry_parse_and_save_function_snapshot)
 
 
 ## jerry_exec_snapshot
@@ -5249,12 +5149,19 @@ main (void)
   const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
 
   jerry_init (JERRY_INIT_EMPTY);
-  size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p,
-                                                                    strlen ((const char *) code_to_snapshot_p),
-                                                                    true,
-                                                                    false,
-                                                                    global_mode_snapshot_buffer,
-                                                                    sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
+
+  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);
@@ -5324,12 +5231,19 @@ main (void)
   const jerry_char_t *code_to_snapshot_p = (const jerry_char_t *) "(function () { return 'string from snapshot'; }) ();";
 
   jerry_init (JERRY_INIT_EMPTY);
-  size_t global_mode_snapshot_size = jerry_parse_and_save_snapshot (code_to_snapshot_p,
-                                                                    strlen ((const char *) code_to_snapshot_p),
-                                                                    true,
-                                                                    false,
-                                                                    global_mode_snapshot_buffer,
-                                                                    sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
+
+  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);
@@ -5402,13 +5316,21 @@ main (void)
   const jerry_char_t *src_p = (const jerry_char_t *) "return a + b;";
 
   jerry_init (JERRY_INIT_EMPTY);
-  size_t snapshot_size = jerry_parse_and_save_function_snapshot (src_p,
-                                                                 strlen ((const char *) src_p),
-                                                                 args_p,
-                                                                 strlen ((const char *) args_p),
-                                                                 false,
-                                                                 snapshot_buffer,
-                                                                 sizeof (snapshot_buffer) / sizeof (uint32_t));
+
+  jerry_value_t generate_result;
+  generate_result = jerry_generate_function_snapshot (NULL,
+                                                      0,
+                                                      src_p,
+                                                      strlen ((const char *) src_p),
+                                                      args_p,
+                                                      strlen ((const char *) args_p),
+                                                      false,
+                                                      snapshot_buffer,
+                                                      sizeof (snapshot_buffer) / sizeof (uint32_t));
+
+  size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
+  jerry_release_value (generate_result);
+
   jerry_cleanup ();
 
   jerry_init (JERRY_INIT_EMPTY);