YourWishes/jerryscript
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rework snapshot generation API. (#2259)

Browse Source 
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
This commit is contained in:
Zoltan Herczeg
2018-04-05 13:43:55 +02:00
committed by GitHub
parent 35926f3f85
commit 7b226f53e0
8 changed files with 477 additions and 569 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/02.API-REFERENCE.md
+129 -207
View File
@@ -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,12 +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));
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
jerry_release_value (generate_result);
jerry_cleanup ();
}
@@ -4984,81 +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_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));
jerry_cleanup ();
}
```
**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_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,13 +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_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));
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
jerry_release_value (generate_result);
jerry_cleanup ();
}
@@ -5127,83 +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_static_function_snapshot](#jerry_parse_and_save_static_function_snapshot)
## jerry_parse_and_save_static_function_snapshot
**Summary**
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));
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_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);