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

Update the webpage (#2289)

Browse Source 
JerryScript-DCO-1.0-Signed-off-by: László Langó llango.u-szeged@partner.samsung.com
This commit is contained in:
László Langó
2018-04-19 14:31:04 +02:00
committed by Zoltan Herczeg
parent 41fa2aa172
commit dc12458382
6 changed files with 577 additions and 218 deletions
Download Patch File Download Diff File Expand all files Collapse all files
02.API-REFERENCE.md
+528 -202
View File
@@ -63,6 +63,69 @@ Possible compile time enabled feature types:
- JERRY_FEATURE_SNAPSHOT_EXEC - executing snapshot files
- JERRY_FEATURE_DEBUGGER - debugging
- JERRY_FEATURE_VM_EXEC_STOP - stopping ECMAScript execution
- JERRY_FEATURE_JSON - JSON support
- JERRY_FEATURE_PROMISE - promise support
- JERRY_FEATURE_TYPEDARRAY - Typedarray support
- JERRY_FEATURE_DATE - Date support
- JERRY_FEATURE_REGEXP - RegExp support
- JERRY_FEATURE_LINE_INFO - line info available
## jerry_parse_opts_t
Option bits for [jerry_parse](#jerry_parse) and
[jerry_parse_function](#jerry_parse_function) functions:
- JERRY_PARSE_NO_OPTS - no options passed
- JERRY_PARSE_STRICT_MODE - enable strict mode
## 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
`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 [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
@@ -132,17 +195,54 @@ typedef uint32_t jerry_value_t;
**Summary**
Structure that defines how a context data item will be initialized and deinitialized. JerryScript zeroes out the memory
for the item by default, and if the `init_cb` field is not NULL, it will be called with the pointer to the memory as
an additional custom initializer.
for the item by default, and if the `init_cb` field is not NULL, it will be called with the pointer to the memory as
an additional custom initializer. The `deinit_cb` (if non-`NULL`) is called during a call to `jerry_cleanup ()` to run
any custom deinitialization *before* the VM has been fully cleaned up. The `finalize_cb` (if non-`NULL`) is also called
during a call to `jerry_cleanup ()` to run any custom deinitialization *after* the VM has been fully cleaned up.
**Prototype**
```c
typedef struct
{
void (*init_cb) (void *); /**< callback responsible for initializing a context item, or NULL */
void (*deinit_cb) (void *); /**< callback responsible for deinitializing a context item */
size_t bytes_needed; /**< number of bytes to allocate for this manager */
/**
* Callback responsible for initializing a context item, or NULL to zero out the memory. This is called lazily, the
* first time jerry_get_context_data () is called with this manager.
*
* @param [in] data The buffer that JerryScript allocated for the manager. The buffer is zeroed out. The size is
* determined by the bytes_needed field. The buffer is kept alive until jerry_cleanup () is called.
*/
void (*init_cb) (void *data);
/**
* Callback responsible for deinitializing a context item, or NULL. This is called as part of jerry_cleanup (),
* right *before* the VM has been cleaned up. This is a good place to release strong references to jerry_value_t's
* that the manager may be holding.
* Note: because the VM has not been fully cleaned up yet, jerry_object_native_info_t free_cb's can still get called
* *after* all deinit_cb's have been run. See finalize_cb for a callback that is guaranteed to run *after* all
* free_cb's have been run.
*
* @param [in] data The buffer that JerryScript allocated for the manager.
*/
void (*deinit_cb) (void *data);
/**
* Callback responsible for finalizing a context item, or NULL. This is called as part of jerry_cleanup (),
* right *after* the VM has been cleaned up and destroyed and jerry_... APIs cannot be called any more. At this point,
* all values in the VM have been cleaned up. This is a good place to clean up native state that can only be cleaned
* up at the very end when there are no more VM values around that may need to access that state.
*
* @param [in] data The buffer that JerryScript allocated for the manager. After returning from this callback,
* the data pointer may no longer be used.
*/
void (*finalize_cb) (void *data);
/**
* Number of bytes to allocate for this manager. This is the size of the buffer that JerryScript will allocate on
* behalf of the manager. The pointer to this buffer is passed into init_cb, deinit_cb and finalize_cb. It is also
* returned from the jerry_get_context_data () API.
*/
size_t bytes_needed;
} jerry_context_data_manager_t;
```
@@ -300,6 +400,33 @@ typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_na
void *user_data_p);
```
## jerry_objects_foreach_t
**Summary**
Function type applied for each object in the engine
**Prototype**
```c
typedef bool (*jerry_objects_foreach_t) (const jerry_value_t object,
void *user_data_p);
```
## jerry_objects_foreach_by_native_info_t
**Summary**
Function type applied for each matching object in the engine
**Prototype**
```c
typedef bool (*jerry_objects_foreach_by_native_info_t) (const jerry_value_t object,
void *object_data_p,
void *user_data_p);
```
## jerry_vm_exec_stop_callback_t
**Summary**
@@ -698,8 +825,9 @@ main (void)
**Summary**
Parse script and construct an EcmaScript function. The
lexical environment is set to the global lexical environment.
Parse script and construct an EcmaScript function. The lexical environment is
set to the global lexical environment. The resource name can be used by
debugging systems to provide line / backtrace info.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
@@ -708,14 +836,18 @@ is no longer needed.
```c
jerry_value_t
jerry_parse (const jerry_char_t *source_p,
jerry_parse (const jerry_char_t *resource_name_p, /**< resource name (usually a file name) */
size_t resource_name_length, /**< length of resource name */
const jerry_char_t *source_p,
size_t source_size,
bool is_strict);
uint32_t parse_opts);
```
- `resource_name_p` - resource name, usually a file name (must be a valid UTF8 string).
- `resource_name_length` - size of the resource name, in bytes.
- `source_p` - string, containing source code to parse (must be a valid UTF8 string).
- `source_size` - size of the string, in bytes.
- `is_strict` - defines strict mode.
- `parse_opts` - any combination of [jerry_parse_opts_t](#jerry_parse_opts_t) flags.
- return value
- function object value, if script was parsed successfully,
- thrown error, otherwise
@@ -736,7 +868,7 @@ main (void)
const jerry_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
jerry_value_t parsed_code = jerry_parse (script, script_size, false);
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
jerry_release_value (parsed_code);
jerry_cleanup ();
@@ -747,40 +879,6 @@ main (void)
- [jerry_run](#jerry_run)
## jerry_parse_named_resource
**Summary**
Parse script and construct an ECMAScript function. The lexical
environment is set to the global lexical environment. The resource
name (usually a file name) is also passed to this function which is
used by the debugger to find the source code.
*Note*: The returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
**Prototype**
```c
jerry_value_t
jerry_parse_named_resource (const jerry_char_t *resource_name_p, /**< resource name (usually a file name) */
size_t resource_name_length, /**< length of resource name */
const jerry_char_t *source_p, /**< script source */
size_t source_size, /**< script source size */
bool is_strict) /**< strict mode */
```
- `resource_name_p` - resource name, usually a file name (must be a valid UTF8 string).
- `resource_name_length` - size of the resource name, in bytes.
- `source_p` - string, containing source code to parse (must be a valid UTF8 string).
- `source_size` - size of the string, in bytes.
- `is_strict` - defines strict mode.
- return value
- function object value, if script was parsed successfully,
- thrown error, otherwise
This function is identical to [jerry_parse](#jerry_parse), except that an additional filename parameter has been added.
## jerry_parse_function
**Summary**
@@ -805,7 +903,7 @@ jerry_parse_function (const jerry_char_t *resource_name_p, /**< resource name (u
size_t arg_list_size, /**< script source size */
const jerry_char_t *source_p, /**< script source */
size_t source_size, /**< script source size */
bool is_strict) /**< strict mode */
uint32_t parse_opts) /**< strict mode */
```
- `resource_name_p` - resource name, usually a file name (must be a valid UTF8 string).
@@ -814,7 +912,7 @@ jerry_parse_function (const jerry_char_t *resource_name_p, /**< resource name (u
- `arg_list_size` - size of the argument list, in bytes.
- `source_p` - string, containing source code to parse (must be a valid UTF8 string).
- `source_size` - size of the string, in bytes.
- `is_strict` - defines strict mode.
- `parse_opts` - any combination of [jerry_parse_opts_t](#jerry_parse_opts_t) flags.
- return value
- function object value, if script was parsed successfully,
- thrown error, otherwise
@@ -857,7 +955,7 @@ main (void)
jerry_init (JERRY_INIT_EMPTY);
/* Setup Global scope code */
jerry_value_t parsed_code = jerry_parse (script, script_size, false);
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
if (!jerry_value_has_error_flag (parsed_code))
{
@@ -947,7 +1045,7 @@ main (void)
const jerry_char_t script[] = "new Promise(function(f,r) { f('Hello, World!'); }).then(function(x) { print(x); });";
size_t script_size = strlen ((const char *) script);
jerry_value_t parsed_code = jerry_parse (script, script_size, false);
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
jerry_value_t script_value = jerry_run (parsed_code);
jerry_value_t job_value = jerry_run_all_enqueued_jobs ();
@@ -4573,6 +4671,187 @@ bool foreach_function (const jerry_value_t prop_name,
- [jerry_object_property_foreach_t](#jerry_object_property_foreach_t)
## jerry_objects_foreach
**Summary**
Iterate over objects.
*Note*: Values obtained in `foreach_p` must be retained using [jerry_acquire_value](#jerry_acquire_value).
**Prototype**
```c
bool jerry_objects_foreach (jerry_objects_foreach_t foreach_p,
void *user_data_p);
```
- `foreach_p` - function that will be invoked for each object.
- `user_data_p` - User data to pass to the function.
- return value
- `true`, if the search function terminated the traversal by returning `false`
- `false`, if the end of the list of objects was reached
**Example**
```c
typedef struct
{
jerry_value_t property_name;
jerry_value_t result;
} find_my_object_info_t;
/*
* Find the first object with the given property.
*/
static bool
find_my_object(const jerry_value_t candidate,
void *user_data_p)
{
find_my_object_info_t *info_p = (find_my_object_info_t *) user_data_p;
jerry_value_t has_property = jerry_object_has_property (candidate, info_p->property_name);
bool keep_searching = (jerry_value_has_error_flag (has_property) || !jerry_get_boolean_value ());
if (!keep_searching)
{
/* We found it, so we acquire the value and record it. */
info_p->result = jerry_acquire_value (candidate);
}
jerry_release_value (has_property);
return keep_searching;
} /* find_my_object */
{
find_my_object_info_t search_info =
{
.property_name = jerry_create_string ("desired_property")
};
if (jerry_object_foreach (find_my_object, &search_info))
{
/* The search was successful. Do something useful with search_info.result. */
...
/* Release the found object after we're done using it. */
jerry_release_value (search_info.result);
}
else
{
/* The search has failed. */
}
jerry_release_value (search_info.desired_property);
}
```
**See also**
- [jerry_objects_foreach_t](#jerry_objects_foreach_t)
## jerry_objects_foreach_by_native_info
**Summary**
Iterate over objects matching a certain native data type.
*Note*: Values obtained in `foreach_p` must be retained using [jerry_acquire_value](#jerry_acquire_value).
**Prototype**
```c
bool jerry_objects_foreach_by_native_info (const jerry_object_native_info_t *native_info_p,
jerry_objects_foreach_by_native_info_t foreach_p,
void *user_data_p);
```
- `native_info_p` - native pointer's type infomation.
- return value
- `true`, if the search function terminated the traversal by returning `false`
- `false`, if the end of the list of objects was reached
**Example**
```c
typedef struct
{
int foo;
bool bar;
} native_obj_t;
typedef struct
{
jerry_value_t found_object;
void *match_data_p;
} find_object_data_t;
static void native_freecb (void *native_p)
{
... // free the native pointer
} /* native_freecb */
// NOTE: The address (!) of type_info acts as a way to uniquely "identify" the
// C type `native_obj_t *`.
static const jerry_object_native_info_t native_obj_type_info =
{
.free_cb = native_freecb
};
// Function creating JS object that is "backed" by a native_obj_t *:
{
...
// construct object and native_set value:
jerry_value_t object = ...;
native_obj_t *native_obj_p = malloc (sizeof (*native_obj_p));
jerry_set_object_native_pointer (object, native_obj_p, &native_obj_type_info);
...
}
// Native method that retrieves the JavaScript object by way of its native data:
static bool find_object (const jerry_value_t candidate, void *data_p, void *user_data_p)
{
find_object_data_t *find_data_p = (find_object_data_t *) user_data_p;
if (find_data_p->match_data_p == data_p)
{
// If the object was found, acquire it and store it in the user data.
find_data_p->found_object = jerry_acquire_value (candidate);
// Stop traversing over the objects.
return false;
}
// Indicate that the object was not found, so traversal must continue.
return true;
} /* find_object */
...
{
find_object_data_t find_data =
{
.match_data = native_obj
};
if (jerry_objects_foreach_by_native_info (&native_obj_type_info, find_object, &find_data))
{
// The object was found and is now stored in find_data.found_object. After using it, it must be released.
...
jerry_release_value (find_data.found_object);
}
else
{
// The object was not found.
}
...
}
```
**See also**
- [jerry_create_object](#jerry_create_object)
- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer)
- [jerry_object_native_info_t](#jerry_object_native_info_t)
- [jerry_objects_foreach](#jerry_objects_foreach)
# Input validator functions
@@ -4683,7 +4962,7 @@ main (void)
# Snapshot functions
## jerry_parse_and_save_snapshot
## jerry_generate_snapshot
**Summary**
@@ -4692,26 +4971,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**
@@ -4729,12 +5010,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 ();
}
@@ -4744,10 +5030,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_function_snapshot
## jerry_generate_function_snapshot
**Summary**
@@ -4760,28 +5047,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**
@@ -4800,13 +5091,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 ();
}
@@ -4816,6 +5113,7 @@ 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)
@@ -4834,15 +5132,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
@@ -4862,19 +5159,27 @@ 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);
jerry_value_t res = jerry_exec_snapshot (global_mode_snapshot_buffer,
global_mode_snapshot_size,
false);
0,
0);
jerry_release_value (res);
jerry_cleanup ();
@@ -4885,89 +5190,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);
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_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**
@@ -4982,19 +5208,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
@@ -5015,21 +5238,29 @@ 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);
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 ();
@@ -5199,7 +5430,7 @@ main (void)
// Inifinte loop.
const char *src_p = "while(true) {}";
jerry_value_t src = jerry_parse ((jerry_char_t *) src_p, strlen (src_p), false);
jerry_value_t src = jerry_parse (NULL, 0, (jerry_char_t *) src_p, strlen (src_p), JERRY_PARSE_NO_OPTS);
jerry_release_value (jerry_run (src));
jerry_release_value (src);
jerry_cleanup ();
@@ -5214,6 +5445,31 @@ main (void)
- [jerry_run](#jerry_run)
- [jerry_vm_exec_stop_callback_t](#jerry_vm_exec_stop_callback_t)
## jerry_get_backtrace
**Summary**
Get backtrace. The backtrace is an array of strings where
each string contains the position of the corresponding frame.
The array length is zero if the backtrace is not available.
This function is typically called from native callbacks.
**Prototype**
```c
jerry_value_t
jerry_get_backtrace (uint32_t max_depth);
```
- `max_depth` - backtrace collection stops after reaching this value, 0 = unlimited
- return value
- a new array
**See also**
- [jerry_create_external_function](#jerry_create_external_function)
# ArrayBuffer and TypedArray functions
@@ -5570,3 +5826,73 @@ jerry_value_t jerry_get_typedarray_buffer (jerry_value_t value,
**See also**
- [jerry_create_typedarray](#jerry_create_typedarray)
# JSON functions
## jerry_json_parse
**Summary**
Returns the same result as JSON.parse ecmascript function.
**Prototype**
```c
jerry_value_t jerry_json_parse (const jerry_char_t *string_p, jerry_size_t string_size)
```
- `string_p` - a JSON string
- `string_size` - size of the string
- return
- jerry_value_t containing the same as json.parse()
- jerry_value_t containing error massage
**Example**
```c
{
const char *data = "{\"name\": \"John\", \"age\": 5}";
jerry_size_t str_length = (jerry_size_t)strlen (data);
jerry_value_t parsed_json = jerry_json_parse ((jerry_char_t*)data, str_length);
// parsed_json now conatins all data stored in data_in_json
jerry_release_value (parsed_json);
}
```
## jerry_stringify
**Summary**
Returns the same value as JSON.stringify() ecmascript function.
**Prototype**
```c
jerry_value_t jerry_json_stringfy (const jerry_value_t object_to_stringify)
```
- `object_to_stringify` - a jerry_value_t object to stringify
- return
- jerry_value_t containing the same as json.stringify()
- jerry_value_t containing error massage
**Example**
```c
{
jerry_value_t obj = jerry_create_object ();
jerry_value_t key = jerry_create_string ((const jerry_char_t *) "name");
jerry_value_t value = jerry_create_string ((const jerry_char_t *) "John");
jerry_set_property (obj, key, value);
jerry_value_t stringified = jerry_json_stringfy (obj);
//stringified now contains a json formated string
jerry_release_value (obj);
jerry_release_value (key);
jerry_release_value (value);
jerry_release_value (stringified);
}
```
03.API-EXAMPLE.md
+1 -1
View File
@@ -65,7 +65,7 @@ main (void)
jerryx_handler_print);
/* Setup Global scope code */
jerry_value_t parsed_code = jerry_parse (script, script_size, false);
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
if (!jerry_value_has_error_flag (parsed_code))
{
04.INTERNALS.md
+1 -1
View File
@@ -41,7 +41,7 @@ The interactions between the major components shown on the following figure.
# Byte-code
This section describes the compact byte-code (CBC) byte-code representation. The key focus is reducing memory consumption of the byte-code representation without sacrificing considerable performance. Other byte-code representations often focus on performance only so inventing this representation is an original research.
This section describes the compact byte-code (CBC) representation. The key focus is reducing memory consumption of the byte-code representation without sacrificing considerable performance. Other byte-code representations often focus on performance only so inventing this representation is an original research.
CBC is a CISC like instruction set which assigns shorter instructions for frequent operations. Many instructions represent multiple atomic tasks which reduces the byte code size. This technique is basically a data compression method.
05.PORT-API.md
+38
View File
@@ -122,6 +122,15 @@ Allow user to provide external buffer for jerry instance (which includes an isol
struct jerry_instance_t *jerry_port_get_current_instance (void);
```
## Sleep
```c
/**
* Makes the process sleep for a given time.
*/
void jerry_port_sleep (uint32_t sleep_time);
```
# How to port JerryScript
This section describes a basic port implementation which was created for Unix based systems.
@@ -241,3 +250,32 @@ jerry_port_get_current_instance (void)
return current_instance_p;
} /* jerry_port_get_current_instance */
```
## Sleep
```c
#include "jerryscript-port.h"
#include "jerryscript-port-default.h"
#ifdef HAVE_TIME_H
#include <time.h>
#elif defined (HAVE_UNISTD_H)
#include <unistd.h>
#endif /* HAVE_TIME_H */
#ifdef JERRY_DEBUGGER
void jerry_port_sleep (uint32_t sleep_time)
{
#ifdef HAVE_TIME_H
nanosleep (&(const struct timespec)
{
sleep_time / 1000, (sleep_time % 1000) * 1000000L /* Seconds, nanoseconds */
}
, NULL);
#elif defined (HAVE_UNISTD_H)
usleep ((useconds_t) sleep_time * 1000);
#endif /* HAVE_TIME_H */
(void) sleep_time;
} /* jerry_port_sleep */
#endif /* JERRY_DEBUGGER */
```
07.DEBUGGER.md
+8 -13
View File
@@ -79,14 +79,9 @@ The debugger can be enabled by calling the `jerry_debugger_init (uint16_t port)`
function after the `jerry_init ()` function. It initializes the debugger
and blocks until a client connects.
When the debugger is enabled it is recommended to use
`jerry_parse_named_resource ()` instead of `jerry_parse ()` because
the resource name (usually a file name) is also passed to this
function. This resource name is used by the client to identify
the corresponding resource. In general it is always recommended to
use `jerry_parse_named_resource ()` when the resource name is
available because it silently ignores the resource name if the
debugger is disabled.
The resource name provided to `jerry_parse ()` is used by the client
to identify the resource name of the source code. This resource name
is usually a file name.
## JerryScript debugger C-API interface
@@ -314,11 +309,11 @@ wait_for_source_callback (const jerry_char_t *resource_name_p, /**< resource nam
size_t source_size, /**< source code size */
void *user_p __attribute__((unused))) /**< user pointer */
{
jerry_value_t ret_val = jerry_parse_named_resource (resource_name_p,
resource_name_size,
source_p,
source_size,
false);
jerry_value_t ret_val = jerry_parse (resource_name_p,
resource_name_size,
source_p,
source_size,
JERRY_PARSE_NO_OPTS);
if (!jerry_value_has_error_flag (ret_val))
{
08.CODING-STANDARDS.md
+1 -1
View File
@@ -714,7 +714,7 @@ typedef struct
/* Field descriptions do not start with capital letters
* and there is no full stop at the end. */
field1_t field1; /**< description of field 1 */
field2_t field2; /**< description of field 1 */
field2_t field2; /**< description of field 2 */
field_n_t field_n; /**< description of field n */
} structure_name_t;