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

Rework snapshot execution api. (#2270)

Browse Source 
The _at functions replaces the original functions.

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com
This commit is contained in:
Zoltan Herczeg
2018-04-11 03:39:58 +02:00
committed by yichoi
parent 46309b1502
commit 5c0c21b26a
5 changed files with 125 additions and 219 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/02.API-REFERENCE.md
+49 -117
View File
@@ -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 ();
jerry-core/api/jerry-snapshot.c
+37 -72
View File
@@ -875,27 +875,30 @@ jerry_generate_snapshot (const jerry_char_t *resource_name_p, /**< script resour
* thrown error - otherwise
*/
static jerry_value_t
jerry_snapshot_result_at (const uint32_t *snapshot_p, /**< snapshot */
size_t snapshot_size, /**< size of snapshot */
size_t func_index, /**< index of primary function */
bool 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). */
bool as_function) /** < specify if the loaded snapshot should be returned as a function */
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_ASSERT (snapshot_p != NULL);
uint32_t allowed_opts = (JERRY_SNAPSHOT_EXEC_COPY_DATA | JERRY_SNAPSHOT_EXEC_ALLOW_STATIC);
if ((exec_snapshot_opts & ~(allowed_opts)) != 0)
{
ecma_raise_range_error (ECMA_ERR_MSG ("Unsupported exec snapshot flags specified."));
return ecma_create_error_reference_from_context ();
}
static const char * const invalid_version_error_p = "Invalid snapshot version or unsupported features present";
static const char * const invalid_format_error_p = "Invalid snapshot format";
const uint8_t *snapshot_data_p = (uint8_t *) snapshot_p;
if (snapshot_size <= sizeof (jerry_snapshot_header_t))
{
return ecma_raise_type_error (invalid_format_error_p);
ecma_raise_type_error (invalid_format_error_p);
return ecma_create_error_reference_from_context ();
}
const jerry_snapshot_header_t *header_p = (const jerry_snapshot_header_t *) snapshot_data_p;
@@ -927,7 +930,13 @@ jerry_snapshot_result_at (const uint32_t *snapshot_p, /**< snapshot */
if (bytecode_p->status_flags & CBC_CODE_FLAGS_STATIC_FUNCTION)
{
if (copy_bytecode)
if (!(exec_snapshot_opts & JERRY_SNAPSHOT_EXEC_ALLOW_STATIC))
{
ecma_raise_common_error (ECMA_ERR_MSG ("Static snapshots not allowed"));
return ecma_create_error_reference_from_context ();
}
if (exec_snapshot_opts & JERRY_SNAPSHOT_EXEC_COPY_DATA)
{
ecma_raise_common_error (ECMA_ERR_MSG ("Static snapshots cannot be copied into memory"));
return ecma_create_error_reference_from_context ();
@@ -939,7 +948,7 @@ jerry_snapshot_result_at (const uint32_t *snapshot_p, /**< snapshot */
bytecode_p = snapshot_load_compiled_code ((const uint8_t *) bytecode_p,
literal_base_p,
copy_bytecode);
(exec_snapshot_opts & JERRY_SNAPSHOT_EXEC_COPY_DATA) != 0);
if (bytecode_p == NULL)
{
@@ -976,42 +985,9 @@ jerry_snapshot_result_at (const uint32_t *snapshot_p, /**< snapshot */
}
return ret_val;
} /* jerry_snapshot_result_at */
} /* jerry_snapshot_result */
#endif /* JERRY_ENABLE_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_at (const uint32_t *snapshot_p, /**< snapshot */
size_t snapshot_size, /**< size of snapshot */
size_t func_index, /**< index of primary function */
bool 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). */
{
#ifdef JERRY_ENABLE_SNAPSHOT_EXEC
return jerry_snapshot_result_at (snapshot_p, snapshot_size, func_index, copy_bytecode, false);
#else /* !JERRY_ENABLE_SNAPSHOT_EXEC */
JERRY_UNUSED (snapshot_p);
JERRY_UNUSED (snapshot_size);
JERRY_UNUSED (func_index);
JERRY_UNUSED (copy_bytecode);
return ECMA_VALUE_FALSE;
#endif /* JERRY_ENABLE_SNAPSHOT_EXEC */
} /* jerry_exec_snapshot_at */
/**
* Execute snapshot from specified buffer
*
@@ -1024,20 +1000,16 @@ jerry_exec_snapshot_at (const uint32_t *snapshot_p, /**< snapshot */
jerry_value_t
jerry_exec_snapshot (const uint32_t *snapshot_p, /**< snapshot */
size_t snapshot_size, /**< size of snapshot */
bool 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). */
size_t func_index, /**< index of primary function */
uint32_t exec_snapshot_opts) /**< jerry_exec_snapshot_opts_t option bits */
{
#ifdef JERRY_ENABLE_SNAPSHOT_EXEC
return jerry_exec_snapshot_at (snapshot_p, snapshot_size, 0, copy_bytecode);
return jerry_snapshot_result (snapshot_p, snapshot_size, func_index, exec_snapshot_opts, false);
#else /* !JERRY_ENABLE_SNAPSHOT_EXEC */
JERRY_UNUSED (snapshot_p);
JERRY_UNUSED (snapshot_size);
JERRY_UNUSED (copy_bytecode);
JERRY_UNUSED (func_index);
JERRY_UNUSED (exec_snapshot_opts);
return ECMA_VALUE_FALSE;
#endif /* JERRY_ENABLE_SNAPSHOT_EXEC */
@@ -1841,27 +1813,20 @@ jerry_generate_function_snapshot (const jerry_char_t *resource_name_p, /**< scri
* @return result of bytecode - if run was successful
* thrown error - otherwise
*/
jerry_value_t jerry_load_function_snapshot_at (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 */
bool 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). */
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 */
{
#ifdef JERRY_ENABLE_SNAPSHOT_EXEC
return jerry_snapshot_result_at (function_snapshot_p, function_snapshot_size, func_index, copy_bytecode, true);
return jerry_snapshot_result (function_snapshot_p, function_snapshot_size, func_index, exec_snapshot_opts, true);
#else /* !JERRY_ENABLE_SNAPSHOT_EXEC */
JERRY_UNUSED (function_snapshot_p);
JERRY_UNUSED (function_snapshot_size);
JERRY_UNUSED (func_index);
JERRY_UNUSED (copy_bytecode);
JERRY_UNUSED (exec_snapshot_opts);
return ECMA_VALUE_FALSE;
#endif /* JERRY_ENABLE_SNAPSHOT_EXEC */
} /* jerry_load_function_snapshot_at */
} /* jerry_load_function_snapshot */
jerry-core/include/jerryscript-snapshot.h
+15 -7
View File
@@ -36,6 +36,15 @@ typedef enum
JERRY_SNAPSHOT_SAVE_STRICT = (1u << 1), /**< strict mode code */
} jerry_generate_snapshot_opts_t;
/**
* Flags for jerry_exec_snapshot_at and jerry_load_function_snapshot_at.
*/
typedef enum
{
JERRY_SNAPSHOT_EXEC_COPY_DATA = (1u << 0), /**< copy snashot data */
JERRY_SNAPSHOT_EXEC_ALLOW_STATIC = (1u << 1), /**< static snapshots allowed */
} jerry_exec_snapshot_opts_t;
/**
* Snapshot functions.
*/
@@ -48,17 +57,16 @@ jerry_value_t jerry_generate_function_snapshot (const jerry_char_t *resource_nam
uint32_t generate_snapshot_opts, uint32_t *buffer_p,
size_t buffer_size);
jerry_value_t jerry_exec_snapshot (const uint32_t *snapshot_p, size_t snapshot_size, bool copy_bytecode);
jerry_value_t jerry_exec_snapshot_at (const uint32_t *snapshot_p, size_t snapshot_size,
size_t func_index, bool copy_bytecode);
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);
size_t jerry_parse_and_save_literals (const jerry_char_t *source_p, size_t source_size, bool is_strict,
uint32_t *buffer_p, size_t buffer_size, bool is_c_format);
jerry_value_t jerry_load_function_snapshot_at (const uint32_t *function_snapshot_p,
const size_t function_snapshot_size,
size_t func_index,
bool copy_bytecode);
/**
* @}
*/
jerry-main/main-unix.c
+4 -4
View File
@@ -565,10 +565,10 @@ main (int argc,
}
else
{
ret_value = jerry_exec_snapshot_at (snapshot_p,
snapshot_size,
exec_snapshot_file_indices[i],
true);
ret_value = jerry_exec_snapshot (snapshot_p,
snapshot_size,
exec_snapshot_file_indices[i],
JERRY_SNAPSHOT_EXEC_COPY_DATA);
}
if (jerry_value_has_error_flag (ret_value))
tests/unit-core/test-snapshot.c
+20 -19
View File
@@ -82,10 +82,10 @@ static void test_function_snapshot (void)
jerry_init (flags);
jerry_value_t function_obj = jerry_load_function_snapshot_at (function_snapshot_buffer,
function_snapshot_size,
0,
false);
jerry_value_t function_obj = jerry_load_function_snapshot (function_snapshot_buffer,
function_snapshot_size,
0,
0);
TEST_ASSERT (!jerry_value_has_error_flag (function_obj));
TEST_ASSERT (jerry_value_is_function (function_obj));
@@ -110,12 +110,10 @@ static void test_function_snapshot (void)
jerry_cleanup ();
} /* test_function_snapshot */
static void arguments_test_exec_snapshot (uint32_t *snapshot_p, size_t snapshot_size, bool copy_bytecode)
static void arguments_test_exec_snapshot (uint32_t *snapshot_p, size_t snapshot_size, uint32_t exec_snapshot_flags)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_value_t res = jerry_exec_snapshot (snapshot_p,
snapshot_size,
copy_bytecode);
jerry_value_t res = jerry_exec_snapshot (snapshot_p, snapshot_size, 0, exec_snapshot_flags);
TEST_ASSERT (!jerry_value_has_error_flag (res));
TEST_ASSERT (jerry_value_is_number (res));
double raw_value = jerry_get_number_value (res);
@@ -158,12 +156,12 @@ static void test_function_arguments_snapshot (void)
jerry_cleanup ();
arguments_test_exec_snapshot (arguments_snapshot_buffer, snapshot_size, false);
arguments_test_exec_snapshot (arguments_snapshot_buffer, snapshot_size, true);
arguments_test_exec_snapshot (arguments_snapshot_buffer, snapshot_size, 0);
arguments_test_exec_snapshot (arguments_snapshot_buffer, snapshot_size, JERRY_SNAPSHOT_EXEC_COPY_DATA);
}
} /* test_function_arguments_snapshot */
static void test_exec_snapshot (uint32_t *snapshot_p, size_t snapshot_size, bool copy_bytecode)
static void test_exec_snapshot (uint32_t *snapshot_p, size_t snapshot_size, uint32_t exec_snapshot_flags)
{
char string_data[32];
@@ -173,9 +171,7 @@ static void test_exec_snapshot (uint32_t *snapshot_p, size_t snapshot_size, bool
sizeof (magic_string_lengths) / sizeof (jerry_length_t),
magic_string_lengths);
jerry_value_t res = jerry_exec_snapshot (snapshot_p,
snapshot_size,
copy_bytecode);
jerry_value_t res = jerry_exec_snapshot (snapshot_p, snapshot_size, 0, exec_snapshot_flags);
TEST_ASSERT (!jerry_value_has_error_flag (res));
TEST_ASSERT (jerry_value_is_string (res));
@@ -238,8 +234,8 @@ main (void)
jerry_cleanup ();
test_exec_snapshot (snapshot_buffer, snapshot_size, false);
test_exec_snapshot (snapshot_buffer, snapshot_size, true);
test_exec_snapshot (snapshot_buffer, snapshot_size, 0);
test_exec_snapshot (snapshot_buffer, snapshot_size, JERRY_SNAPSHOT_EXEC_COPY_DATA);
}
/* Static snapshot */
@@ -271,9 +267,14 @@ main (void)
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
jerry_release_value (generate_result);
/* Static snapshots are not supported by default. */
jerry_value_t exec_result = jerry_exec_snapshot (snapshot_buffer, snapshot_size, 0, 0);
TEST_ASSERT (jerry_value_has_error_flag (exec_result));
jerry_release_value (exec_result);
jerry_cleanup ();
test_exec_snapshot (snapshot_buffer, snapshot_size, false);
test_exec_snapshot (snapshot_buffer, snapshot_size, JERRY_SNAPSHOT_EXEC_ALLOW_STATIC);
}
/* Merge snapshot */
@@ -342,12 +343,12 @@ main (void)
jerry_init (JERRY_INIT_EMPTY);
jerry_value_t res = jerry_exec_snapshot_at (merged_snapshot_buffer, merged_size, 0, false);
jerry_value_t res = jerry_exec_snapshot (merged_snapshot_buffer, merged_size, 0, 0);
TEST_ASSERT (!jerry_value_has_error_flag (res));
TEST_ASSERT (jerry_get_number_value (res) == 123);
jerry_release_value (res);
res = jerry_exec_snapshot_at (merged_snapshot_buffer, merged_size, 1, false);
res = jerry_exec_snapshot (merged_snapshot_buffer, merged_size, 1, 0);
TEST_ASSERT (!jerry_value_has_error_flag (res));
TEST_ASSERT (jerry_get_number_value (res) == 456);
jerry_release_value (res);