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 ();