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

Update the webpage (#2549)

Browse Source 
JerryScript-DCO-1.0-Signed-off-by: Zsolt Borbély zsborbely.u-szeged@partner.samsung.com
This commit is contained in:
Zsolt Borbély
2018-10-04 11:04:17 +02:00
committed by Akos Kiss
parent cf87970ef6
commit c846c4ab73
6 changed files with 231 additions and 199 deletions
Download Patch File Download Diff File Expand all files Collapse all files
02.API-REFERENCE.md
+155 -117
View File
@@ -248,32 +248,32 @@ typedef struct
} jerry_context_data_manager_t;
```
## jerry_instance_alloc_t
## jerry_context_alloc_t
**Summary**
Function type for allocating buffer for JerryScript instance.
Function type for allocating buffer for JerryScript context.
**Prototype**
```c
typedef void *(*jerry_instance_alloc_t) (size_t size, void *cb_data_p);
typedef void *(*jerry_context_alloc_t) (size_t size, void *cb_data_p);
```
- `size` - allocation size
- `cb_data_p` - pointer to user data
## jerry_instance_t
## jerry_context_t
**Summary**
An opaque declaration of the JerryScript instance structure which is the header of the context space.
An opaque declaration of the JerryScript context structure.
**Prototype**
```c
typedef struct jerry_instance_t jerry_instance_t;
typedef struct jerry_context_t jerry_context_t;
```
## jerry_property_descriptor_t
@@ -644,7 +644,7 @@ Registers an external magic string array.
```c
void
jerry_register_magic_strings (const jerry_char_t **ex_str_items_p,
jerry_register_magic_strings (const jerry_char_t * const *ex_str_items_p,
uint32_t count,
const jerry_length_t *str_lengths_p);
```
@@ -667,11 +667,11 @@ main (void)
// must be static, because 'jerry_register_magic_strings' does not copy
// the items must be sorted by size at first, then lexicographically
static const jerry_char_t *magic_string_items[] = {
(const jerry_char_t *) "magicstring1",
(const jerry_char_t *) "magicstring2",
(const jerry_char_t *) "magicstring3"
};
static const jerry_char_t * const magic_string_items[] = {
(const jerry_char_t *) "magicstring1",
(const jerry_char_t *) "magicstring2",
(const jerry_char_t *) "magicstring3"
};
uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_t *));
// must be static, because 'jerry_register_magic_strings' does not copy
@@ -688,7 +688,7 @@ main (void)
- [jerry_init](#jerry_init)
- [jerry_cleanup](#jerry_cleanup)
- [jerry_parse_and_save_literals](#jerry_parse_and_save_literals)
- [jerry_get_literals_from_snapshot](#jerry_get_literals_from_snapshot)
## jerry_get_memory_stats
@@ -793,15 +793,14 @@ jerry_run_simple (const jerry_char_t *script_source_p,
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
const jerry_char_t *script = (const jerry_char_t *) "print ('Hello, World!');";
const jerry_char_t script[] = "print ('Hello, World!');";
jerry_run_simple (script, strlen ((const char *) script), JERRY_INIT_EMPTY);
jerry_run_simple (script, sizeof (script) - 1, JERRY_INIT_EMPTY);
}
```
@@ -849,7 +848,6 @@ jerry_parse (const jerry_char_t *resource_name_p, /**< resource name (usually a
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
@@ -858,9 +856,8 @@ main (void)
jerry_init (JERRY_INIT_EMPTY);
const jerry_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
jerry_release_value (parsed_code);
jerry_cleanup ();
@@ -934,20 +931,18 @@ jerry_run (const jerry_value_t func_val);
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
const jerry_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
/* Initialize engine */
jerry_init (JERRY_INIT_EMPTY);
/* Setup Global scope code */
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
if (!jerry_value_is_error (parsed_code))
{
@@ -1026,7 +1021,6 @@ jerry_run_all_enqueued_jobs (void)
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
@@ -1035,9 +1029,8 @@ main (void)
jerry_init (JERRY_INIT_EMPTY);
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 (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
jerry_value_t script_value = jerry_run (parsed_code);
jerry_value_t job_value = jerry_run_all_enqueued_jobs ();
@@ -2999,10 +2992,10 @@ jerry_create_error_sz (jerry_error_t error_type,
```c
{
const jerry_char_t *message = "error";
const jerry_char_t message[] = "error";
jerry_value_t error_obj = jerry_create_error_sz (JERRY_ERROR_COMMON,
message,
strlen ((const char *) message));
sizeof (message) - 1);
... // usage of error_obj
@@ -3330,7 +3323,7 @@ jerry_create_string_sz (const jerry_char_t *str_p,
{
const jerry_char_t char_array[] = "a string";
jerry_value_t string_value = jerry_create_string_sz (char_array,
strlen ((const char *) char_array));
sizeof (char_array) - 1);
... // usage of string_value
@@ -3408,7 +3401,7 @@ jerry_create_string_sz (const jerry_char_t *str_p,
{
const jerry_char_t char_array[] = "a string";
jerry_value_t string_value = jerry_create_string_sz_from_utf8 (char_array,
strlen ((const char *) char_array));
sizeof (char_array) - 1);
... // usage of string_value
@@ -4802,16 +4795,15 @@ jerry_is_valid_utf8_string (const jerry_char_t *utf8_buf_p, /**< UTF-8 string */
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
const jerry_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
const jerry_size_t script_size = sizeof (script) - 1;
if (jerry_is_valid_utf8_string (script, (jerry_size_t) script_size))
if (jerry_is_valid_utf8_string (script, script_size))
{
jerry_run_simple (script, script_size, JERRY_INIT_EMPTY);
}
@@ -4850,7 +4842,6 @@ jerry_is_valid_cesu8_string (const jerry_char_t *cesu8_buf_p, /**< CESU-8 string
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
@@ -4859,12 +4850,12 @@ main (void)
jerry_init (JERRY_INIT_EMPTY);
const jerry_char_t script[] = "Hello, World!";
size_t script_size = strlen ((const char *) script);
const jerry_size_t script_size = sizeof (script) - 1;
if (jerry_is_valid_cesu8_string (script, (jerry_size_t) script_size))
if (jerry_is_valid_cesu8_string (script, script_size))
{
jerry_value_t string_value = jerry_create_string_sz (script,
(jerry_size_t) script_size);
script_size);
// usage of string_value
@@ -4885,28 +4876,74 @@ main (void)
- [jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer)
# External context functions
# Dynamic memory management functions
## jerry_create_instance
## jerry_heap_alloc
**Summary**
Creates a JerryScript instance for external context.
Allocate memory on the engine's heap.
*Note*: This function may take away memory from the executed JavaScript code.
If any other dynamic memory allocation API is available (e.g., libc malloc), it
should be used instead.
**Prototype**
```c
jerry_instance_t *
jerry_create_instance (uint32_t heap_size,
jerry_instance_alloc_t alloc,
void *cb_data_p);
void *jerry_heap_alloc (size_t size);
```
- `heap_size` - requested heap size of the JerryScript instance
- `size`: size of the memory block.
- return value: non-NULL pointer, if the memory is successfully allocated,
NULL otherwise.
**See also**
- [jerry_heap_free](#jerry_heap_free)
## jerry_heap_free
**Summary**
Free memory allocated on the engine's heap.
**Prototype**
```c
void jerry_heap_free (void *mem_p, size_t size);
```
- `mem_p`: value returned by `jerry_heap_alloc`.
- `size`: same size as passed to `jerry_heap_alloc`.
**See also**
- [jerry_heap_alloc](#jerry_heap_alloc)
# External context functions
## jerry_create_context
**Summary**
Create an external JerryScript engine context.
**Prototype**
```c
jerry_context_t *
jerry_create_context (uint32_t heap_size,
jerry_context_alloc_t alloc,
void *cb_data_p);
```
- `heap_size` - requested heap size of the JerryScript context
- `alloc` - function for allocation
- `cb_data_p` - user data
- return value
- pointer to the newly created JerryScript instance if success
- pointer to the newly created JerryScript context if success
- NULL otherwise.
**Example**
@@ -4920,19 +4957,19 @@ jerry_create_instance (uint32_t heap_size,
#include "jerryscript.h"
#include "jerryscript-port.h"
/* A different Thread Local Storage variable for each jerry instance. */
__thread jerry_instance_t *tls_instance;
/* A different Thread Local Storage variable for each jerry context. */
__thread jerry_context_t *tls_context;
jerry_instance_t *
jerry_port_get_current_instance (void)
jerry_context_t *
jerry_port_get_current_context (void)
{
/* Returns the instance assigned to the thread. */
return tls_instance;
/* Returns the context assigned to the thread. */
return tls_context;
}
/* Allocate JerryScript heap for each thread. */
static void *
instance_alloc_fn (size_t size, void *cb_data)
context_alloc_fn (size_t size, void *cb_data)
{
(void) cb_data;
return malloc (size);
@@ -4941,15 +4978,15 @@ instance_alloc_fn (size_t size, void *cb_data)
static void *
thread_function (void *param)
{
tls_instance = jerry_create_instance (512 * 1024,
instance_alloc_fn,
NULL);
tls_context = jerry_create_context (512 * 1024,
context_alloc_fn,
NULL);
jerry_init (JERRY_INIT_EMPTY);
/* Run the JerryScript instance (e.g.: jerry_parse & jerry_run) */
/* Run JerryScript in the context (e.g.: jerry_parse & jerry_run) */
jerry_cleanup ();
/* Deallocate JerryScript instance */
free (tls_instance);
/* Deallocate JerryScript context */
free (tls_context);
return NULL;
}
@@ -4979,9 +5016,9 @@ main (void)
**See also**
- [jerry_instance_t](#jerry_instance_t)
- [jerry_instance_alloc_t](#jerry_instance_alloc_t)
- [jerry_port_get_current_instance](05.PORT-API.md#jerry_port_get_current_instance)
- [jerry_context_t](#jerry_context_t)
- [jerry_context_alloc_t](#jerry_context_alloc_t)
- [jerry_port_get_current_context](05.PORT-API.md#jerry_port_get_current_context)
# Snapshot functions
@@ -5023,7 +5060,6 @@ jerry_generate_snapshot (const jerry_char_t *resource_name_p,
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
@@ -5032,13 +5068,13 @@ 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 from snapshot'; }) ();";
const jerry_char_t script_to_snapshot[] = "(function () { return 'string from snapshot'; }) ();";
jerry_value_t generate_result;
generate_result = jerry_generate_snapshot (NULL,
0,
code_to_snapshot_p,
strlen ((const char *) code_to_snapshot_p),
script_to_snapshot,
sizeof (script_to_snapshot) - 1,
0,
global_mode_snapshot_buffer,
sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
@@ -5103,7 +5139,6 @@ jerry_generate_function_snapshot (const jerry_char_t *resource_name_p,
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
@@ -5112,16 +5147,16 @@ main (void)
jerry_init (JERRY_INIT_EMPTY);
static uint32_t func_snapshot_buffer[256];
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;";
const jerry_char_t args[] = "a, b";
const jerry_char_t src[] = "return a + b;";
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),
src,
sizeof (src) - 1,
args,
sizeof (args) - 1,
0,
func_snapshot_buffer,
sizeof (func_snapshot_buffer) / sizeof (uint32_t));
@@ -5173,22 +5208,21 @@ jerry_exec_snapshot (const uint32_t *snapshot_p,
[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'; }) ();";
const jerry_char_t script_to_snapshot[] = "(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),
script_to_snapshot,
sizeof (script_to_snapshot) - 1,
0,
global_mode_snapshot_buffer,
sizeof (global_mode_snapshot_buffer) / sizeof (uint32_t));
@@ -5251,25 +5285,24 @@ jerry_load_function_snapshot (const uint32_t *snapshot_p,
[doctest]: # ()
```c
#include <string.h>
#include "jerryscript.h"
int
main (void)
{
static uint32_t snapshot_buffer[256];
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;";
const jerry_char_t func_args[] = "a, b";
const jerry_char_t func_src[] = "return a + b;";
jerry_init (JERRY_INIT_EMPTY);
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),
func_src,
sizeof (func_src) - 1,
func_args,
sizeof (func_args) - 1,
false,
snapshot_buffer,
sizeof (snapshot_buffer) / sizeof (uint32_t));
@@ -5313,30 +5346,28 @@ main (void)
- [jerry_parse_and_save_function_snapshot](#jerry_parse_and_save_function_snapshot)
## jerry_parse_and_save_literals
## jerry_get_literals_from_snapshot
**Summary**
Collect the used literals from the given source code and save them into a specific file in a list or C format.
These literals are generated by the parser, they are valid identifiers and none of them are magic string.
Collect the used literals from the given snapshot and save them into a buffer in list or C format.
None of these literals are magic strings. In C format only valid identifiers are collected.
**Prototype**
```c
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_get_literals_from_snapshot (const uint32_t *snapshot_p,
size_t snapshot_size,
jerry_char_t *lit_buf_p,
size_t lit_buf_size,
bool is_c_format);
```
- `source_p` - script source, it must be a valid utf8 string.
- `source_size` - script source size, in bytes.
- `is_strict` - strict mode.
- `buffer_p` - buffer to save literals to.
- `buffer_size` - the buffer's size.
- `snapshot_p` - input snapshot buffer.
- `snapshot_size` - snapshot size, in bytes.
- `lit_buf_p` - buffer to save literals to.
- `lit_buf_size` - the buffer's size.
- `is_c_format` - the output format would be C-style (true) or a simple list (false).
- return value
- the size of the literal-list, if it was generated succesfully (i.e. the list of literals isn't empty,
@@ -5349,7 +5380,6 @@ jerry_parse_and_save_literals (const jerry_char_t *source_p,
```c
#include <stdio.h>
#include <string.h>
#include "jerryscript.h"
int
@@ -5357,20 +5387,30 @@ main (void)
{
jerry_init (JERRY_INIT_EMPTY);
static uint32_t save_literal_buffer[256];
const jerry_char_t *code_for_literal_save_p = (const jerry_char_t *) "var obj = { a:'aa', bb:'Bb' }";
static jerry_char_t literal_buffer[256];
static uint32_t snapshot_buffer[256];
const jerry_char_t script_for_literal_save[] = "var obj = { a:'aa', bb:'Bb' }";
size_t literal_sizes = jerry_parse_and_save_literals (code_for_literal_save_p,
strlen ((const char *) code_for_literal_save_p),
false,
save_literal_buffer,
sizeof (save_literal_buffer) / sizeof (uint32_t),
true);
jerry_value_t generate_result = jerry_generate_snapshot (NULL,
0,
script_for_literal_save,
sizeof (script_for_literal_save) - 1,
0,
snapshot_buffer,
256);
size_t snapshot_size = (size_t) jerry_get_number_value (generate_result);
jerry_release_value (generate_result);
if (literal_sizes != 0)
const size_t literal_size = jerry_get_literals_from_snapshot (snapshot_buffer,
snapshot_size,
literal_buffer,
256,
true);
if (literal_size != 0)
{
FILE *literal_file_p = fopen ("literals.txt", "w");
fwrite (save_literal_buffer, sizeof (uint8_t), literal_sizes, literal_file_p);
FILE *literal_file_p = fopen ("literals.h", "wb");
fwrite (literal_buffer, sizeof (uint8_t), literal_size, literal_file_p);
fclose (literal_file_p);
}
@@ -5426,7 +5466,6 @@ jerry_set_vm_exec_stop_callback (jerry_vm_exec_stop_callback_t stop_cb,
[doctest]: # (test="link")
```c
#include <string.h>
#include "jerryscript.h"
static int countdown = 10;
@@ -5452,11 +5491,11 @@ main (void)
jerry_set_vm_exec_stop_callback (vm_exec_stop_callback, &countdown, 16);
// Inifinte loop.
const char *src_p = "while(true) {}";
const jerry_char_t script[] = "while(true) {}";
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_value_t parsed_code = jerry_parse (NULL, 0, script, sizeof (script) - 1, JERRY_PARSE_NO_OPTS);
jerry_release_value (jerry_run (parsed_code));
jerry_release_value (parsed_code);
jerry_cleanup ();
}
```
@@ -5875,9 +5914,8 @@ jerry_value_t jerry_json_parse (const jerry_char_t *string_p, jerry_size_t strin
```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);
const jerry_char_t data[] = "{\"name\": \"John\", \"age\": 5}";
jerry_value_t parsed_json = jerry_json_parse (data, sizeof (data) - 1);
// parsed_json now conatins all data stored in data_in_json