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

Update the webpage (#2499)

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-08-31 12:02:17 +02:00
committed by Akos Kiss
parent 2ce27a189a
commit cf87970ef6
8 changed files with 722 additions and 314 deletions
Download Patch File Download Diff File Expand all files Collapse all files
02.API-REFERENCE.md
+316 -235
View File
@@ -23,16 +23,17 @@ Enum that contains the following elements:
## jerry_type_t
Enum that contains a set of elements to represent JavaScript type:
Enum that contains JerryScript API value types:
- JERRY_TYPE_NONE - no type information
- JERRY_TYPE_UNDEFINED - undefined value
- JERRY_TYPE_NULL - null value
- JERRY_TYPE_BOOLEAN - boolean value
- JERRY_TYPE_NUMBER - number value
- JERRY_TYPE_STRING - string value
- JERRY_TYPE_OBJECT - object value
- JERRY_TYPE_FUNCTION - function value
- JERRY_TYPE_UNDEFINED - undefined type
- JERRY_TYPE_NULL - null type
- JERRY_TYPE_BOOLEAN - boolean type
- JERRY_TYPE_NUMBER - number type
- JERRY_TYPE_STRING - string type
- JERRY_TYPE_OBJECT - object type
- JERRY_TYPE_FUNCTION - function type
- JERRY_TYPE_ERROR - error/abort type
## jerry_error_t
@@ -69,6 +70,7 @@ Possible compile time enabled feature types:
- JERRY_FEATURE_DATE - Date support
- JERRY_FEATURE_REGEXP - RegExp support
- JERRY_FEATURE_LINE_INFO - line info available
- JERRY_FEATURE_LOGGING - logging
## jerry_parse_opts_t
@@ -78,6 +80,18 @@ Option bits for [jerry_parse](#jerry_parse) and
- JERRY_PARSE_NO_OPTS - no options passed
- JERRY_PARSE_STRICT_MODE - enable strict mode
## jerry_gc_mode_t
Set garbage collection operational mode
- JERRY_GC_SEVERITY_LOW - free unused objects
- JERRY_GC_SEVERITY_HIGH - free as much memory as possible
The difference between `JERRY_GC_SEVERITY_LOW` and `JERRY_GC_SEVERITY_HIGH`
is that the former keeps memory allocated for performance improvements such
as property hash tables for large objects. The latter frees all possible
memory blocks but the performance may drop after the garbage collection.
## jerry_generate_snapshot_opts_t
Flags for [jerry_generate_snapshot](#jerry_generate_snapshot) and
@@ -139,18 +153,6 @@ Jerry's char value
typedef uint8_t jerry_char_t;
```
## jerry_char_ptr_t
**Summary**
Pointer to an array of character values
**Prototype**
```c
typedef jerry_char_t *jerry_char_ptr_t;
```
## jerry_size_t
**Summary**
@@ -246,6 +248,34 @@ typedef struct
} jerry_context_data_manager_t;
```
## jerry_instance_alloc_t
**Summary**
Function type for allocating buffer for JerryScript instance.
**Prototype**
```c
typedef void *(*jerry_instance_alloc_t) (size_t size, void *cb_data_p);
```
- `size` - allocation size
- `cb_data_p` - pointer to user data
## jerry_instance_t
**Summary**
An opaque declaration of the JerryScript instance structure which is the header of the context space.
**Prototype**
```c
typedef struct jerry_instance_t jerry_instance_t;
```
## jerry_property_descriptor_t
**Summary**
@@ -330,20 +360,6 @@ typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_
const jerry_length_t args_count);
```
## jerry_object_free_callback_t
**Summary**
**Deprecated: Please use jerry_object_native_free_callback_t instead.**
Native free callback of an object.
**Prototype**
```c
typedef void (*jerry_object_free_callback_t) (const uintptr_t native_p);
```
## jerry_object_native_free_callback_t
**Summary**
@@ -360,7 +376,7 @@ typedef void (*jerry_object_native_free_callback_t) (void *native_p);
**Summary**
The type infomation of the native pointer.
The type information of the native pointer.
It includes the free callback that will be called when associated JavaScript object is garbage collected. It can be left NULL in case it is not needed.
Typically, one would create a `static const jerry_object_native_info_t` for
@@ -628,7 +644,7 @@ Registers an external magic string array.
```c
void
jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p,
jerry_register_magic_strings (const jerry_char_t **ex_str_items_p,
uint32_t count,
const jerry_length_t *str_lengths_p);
```
@@ -651,12 +667,12 @@ 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_ptr_t magic_string_items[] = {
(const jerry_char_ptr_t) "magicstring1",
(const jerry_char_ptr_t) "magicstring2",
(const jerry_char_ptr_t) "magicstring3"
};
uint32_t num_magic_string_items = (uint32_t) (sizeof (magic_string_items) / sizeof (jerry_char_ptr_t));
static const jerry_char_t *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
static const jerry_length_t magic_string_lengths[] = {
@@ -715,13 +731,30 @@ Performs garbage collection.
```c
void
jerry_gc (void);
jerry_gc (jerry_gc_mode_t mode);
```
- `mode` - operational mode, see [jerry_gc_mode_t](#jerry_gc_mode_t)
**Example**
[doctest]: # ()
```c
jerry_gc ();
#include "jerryscript.h"
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_value_t object_value = jerry_create_object ();
jerry_release_value (object_value);
jerry_gc (JERRY_GC_SEVERITY_LOW);
jerry_cleanup ();
}
```
**See also**
@@ -950,12 +983,12 @@ Perform JavaScript `eval`.
jerry_value_t
jerry_eval (const jerry_char_t *source_p,
size_t source_size,
bool is_strict);
uint32_t parse_opts);
```
- `source_p` - source code to evaluate, it must be a valid utf8 string.
- `source_size` - length of the source code
- `is_strict` - perform `eval` as it is called from "strict mode" code.
- `parse_opts` - any combination of [jerry_parse_opts_t](#jerry_parse_opts_t) flags.
- return value - result of eval, may be error value.
**Example**
@@ -964,7 +997,7 @@ jerry_eval (const jerry_char_t *source_p,
{
jerry_value_t ret_val = jerry_eval (str_to_eval,
strlen (str_to_eval),
false);
JERRY_PARSE_NO_OPTS);
}
```
@@ -1611,7 +1644,7 @@ jerry_value_is_undefined (const jerry_value_t value)
Returns the JavaScript type
for a given value as a [jerry_type_t](#jerry_type_t) enum value.
This is a similar operation as the 'typeof' operator
This is a similar operation to the 'typeof' operator
in the standard with an exception that the 'null'
value has its own enum value.
@@ -1677,6 +1710,125 @@ jerry_is_feature_enabled (const jerry_feature_t feature);
# Error manipulation functions
## jerry_create_abort_from_value
**Summary**
Create (api) abort from a value.
This function creates an API abort value from an API value. The second argument defines
whether the input value must be released or not. If it is set to `true`,
then a [`jerry_release_value`](#jerry_release_value) function will be called
for the first argument, so the api value won't be available after the call of
`jerry_create_abort_from_value`. The second argument should be false if both value
and created abort value are needed.
**Prototype**
```c
jerry_value_t
jerry_create_abort_from_value (jerry_value_t value, bool release);
```
- `value` - api value
- `release` - raw boolean, defines whether input value must be released
- return value - abort (api) value
**Example 1**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t abort = jerry_create_abort_from_value (value, true);
// using the 'value' variable after release is invalid.
jerry_release_value (abort);
}
```
**Example 2**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t abort = jerry_create_abort_from_value (value, false);
// both 'abort' and 'value' can be used and must be released when they are no longer needed
jerry_release_value (abort);
jerry_release_value (value);
}
```
**See also**
- [jerry_value_t](#jerry_value_t)
- [jerry_get_value_from_error](#jerry_get_value_from_error)
- [jerry_create_error_from_value](#jerry_create_error_from_value)
## jerry_create_error_from_value
**Summary**
Create (api) error from a value.
This function creates an API error value from an API value. The second argument defines
whether the input value must be released or not. If it is set to `true`,
then a [`jerry_release_value`](#jerry_release_value) function will be called
for the first argument, so the api value won't be available after the call of
`jerry_create_error_from_value`. The second argument should be false if both value
and created error value are needed.
**Prototype**
```c
jerry_value_t
jerry_create_error_from_value (jerry_value_t value, bool release);
```
- `value` - api value
- `release` - raw boolean, defines whether input value must be released
- return value - error (api) value
**Example 1**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t error = jerry_create_error_from_value (value, true);
// using the 'value' variable after release is invalid.
jerry_release_value (error);
}
```
**Example 2**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_t error = jerry_create_error_from_value (value, false);
// both 'error' and 'value' can be used and must be released when they are no longer needed
jerry_release_value (error);
jerry_release_value (value);
}
```
**See also**
- [jerry_value_t](#jerry_value_t)
- [jerry_get_value_from_error](#jerry_get_value_from_error)
- [jerry_create_abort_from_value](#jerry_create_abort_from_value
## jerry_get_error_type
**Summary**
@@ -1732,7 +1884,7 @@ whether the input error value must be released or not. If it is set to `true`,
then a [`jerry_release_value`](#jerry_release_value) function will be called
for the first argument, so the error value won't be available after the call of
`jerry_get_value_from_error`. The second argument should be false if both error
and its represented value are needed. The first argument is returned unchanged if it is not an error.
and its represented value are needed.
*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
is no longer needed.
@@ -1752,14 +1904,14 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
```c
{
jerry_value_t error;
jerry_value_t value;
... // create or acquire value
jerry_value_set_error_flag (&error);
jerry_value_t value = jerry_get_value_from_error (error, true);
jerry_value_t error = jerry_create_error_from_value (value, true);
jerry_value_t value_from_error = jerry_get_value_from_error (error, true);
// using the 'error' variable after release is invalid.
jerry_release_value (value);
jerry_release_value (value_from_error);
}
```
@@ -1767,14 +1919,14 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
```c
{
jerry_value_t error;
jerry_value_t value;
... // create or acquire value
jerry_value_set_error_flag (&error);
jerry_value_t value = jerry_get_value_from_error (error, false);
// both 'error' and 'value' can be used and must be released when they are no longer needed
jerry_value_t error = jerry_create_error_from_value (value, true);
jerry_value_t value_from_error = jerry_get_value_from_error (error, false);
// both 'error' and 'value_from_error' can be used and must be released when they are no longer needed
jerry_release_value (value);
jerry_release_value (value_from_error);
jerry_release_value (error);
}
```
@@ -1782,78 +1934,8 @@ jerry_get_value_from_error (jerry_value_t value, bool release)
**See also**
- [jerry_value_t](#jerry_value_t)
- [jerry_value_set_error_flag](#jerry_value_set_error_flag)
- [jerry_value_set_abort_flag](#jerry_value_set_abort_flag)
## jerry_value_set_error_flag
**Summary**
Set the error flag.
**Prototype**
```c
void
jerry_value_set_error_flag (jerry_value_t *value_p);
```
- `value_p` - pointer to an api value
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_set_error_flag (&value);
jerry_release_value (value);
}
```
**See also**
- [jerry_value_t](#jerry_value_t)
- [jerry_get_value_from_error](#jerry_get_value_from_error)
- [jerry_value_set_abort_flag](#jerry_value_set_abort_flag)
## jerry_value_set_abort_flag
**Summary**
Set both the error and abort flags.
**Prototype**
```c
void
jerry_value_set_abort_flag (jerry_value_t *value_p);
```
- `value_p` - pointer to an api value
**Example**
```c
{
jerry_value_t value;
... // create or acquire value
jerry_value_set_abort_flag (&value);
jerry_release_value (value);
}
```
**See also**
- [jerry_value_t](#jerry_value_t)
- [jerry_get_value_from_error](#jerry_get_value_from_error)
- [jerry_value_set_error_flag](#jerry_value_set_error_flag)
- [jerry_create_error_from_value](#jerry_create_error_from_value)
- [jerry_create_abort_from_value](#jerry_create_abort_from_value)
# Getter functions of 'jerry_value_t'
@@ -2890,7 +2972,7 @@ jerry_create_error (jerry_error_t error_type,
- [jerry_value_is_error](#jerry_value_is_error)
- [jerry_get_value_from_error](#jerry_get_value_from_error)
- [jerry_value_set_error_flag](#jerry_value_set_error_flag)
- [jerry_create_error_from_value](#jerry_create_error_from_value)
## jerry_create_error_sz
@@ -4317,106 +4399,6 @@ jerry_set_prototype (const jerry_value_t obj_val,
- [jerry_get_prototype](#jerry_get_prototype)
## jerry_get_object_native_handle
**Summary**
**Deprecated: Please use jerry_get_object_native_pointer instead.**
Get native handle, previously associated with specified object.
**Prototype**
```c
bool
jerry_get_object_native_handle (const jerry_value_t obj_val,
uintptr_t *out_handle_p);
```
- `obj_val` - object value
- `out_handle_p` - handle value (output parameter).
- return value
- true, if there is handle associated with the object
- false, otherwise
**Example**
```c
{
jerry_value_t object;
uintptr_t handle_set;
... // receive or construct object and handle_set value
jerry_set_object_native_handle (object, handle_set, NULL);
...
uintptr_t handle_get;
bool is_there_associated_handle = jerry_get_object_native_handle (object, &handle_get);
}
```
**See also**
- [jerry_create_object](#jerry_create_object)
- [jerry_set_object_native_handle](#jerry_set_object_native_handle)
- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer)
## jerry_set_object_native_handle
**Summary**
**Deprecated: Please use jerry_set_object_native_pointer instead.**
Set native handle and an optional free callback for the specified object.
*Note*: If native handle was already set for the object, its value is updated.
*Note*: If a non-NULL free callback is specified, it will be called
by the garbage collector when the object is freed. The free
callback always overwrites the previous value, so passing
a NULL value deletes the current free callback.
**Prototype**
```c
void
jerry_set_object_native_handle (const jerry_value_t obj_val,
uintptr_t handle_p,
jerry_object_free_callback_t freecb_p);
```
- `obj_val` - object value to set handle in
- `handle_p` - handle value
- `freecb_p` - pointer to "free" callback or NULL
**Example**
```c
{
jerry_value_t object;
uintptr_t handle_set;
... // receive or construct object and handle_set value
jerry_set_object_native_handle (object, handle_set, NULL);
...
uintptr_t handle_get;
bool is_there_associated_handle = jerry_get_object_native_handle (object, &handle_get);
}
```
**See also**
- [jerry_create_object](#jerry_create_object)
- [jerry_get_object_native_handle](#jerry_get_object_native_handle)
- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
## jerry_get_object_native_pointer
**Summary**
@@ -4437,7 +4419,7 @@ The pointer and the type information are previously associated with the object b
and dereferencing `out_native_pointer_p`.
*Note*: `out_native_pointer_p` and `out_native_info_p` can be NULL, and it means the
caller doesn't want to get the native_pointer or type infomation.
caller doesn't want to get the native_pointer or type information.
**Prototype**
@@ -4450,7 +4432,7 @@ jerry_get_object_native_pointer (const jerry_value_t obj_val,
- `obj_val` - object value to get native pointer from.
- `out_native_pointer_p` - native pointer (output parameter).
- `out_native_info_p` - native pointer's type infomation (output parameter).
- `out_native_info_p` - native pointer's type information (output parameter).
- return value
- true, if there is native pointer associated with the object
- false, otherwise
@@ -4547,7 +4529,7 @@ jerry_set_object_native_pointer (const jerry_value_t obj_val,
- `obj_val` - object to set native pointer in.
- `native_p` - native pointer.
- `info_p` - native pointer's type infomation or NULL. When used, this should
- `info_p` - native pointer's type information or NULL. When used, this should
be a long-lived pointer, usually a pointer to a
`static const jerry_object_native_info_t` makes most sense.
@@ -4705,7 +4687,7 @@ bool jerry_objects_foreach_by_native_info (const jerry_object_native_info_t *nat
void *user_data_p);
```
- `native_info_p` - native pointer's type infomation.
- `native_info_p` - native pointer's type information.
- return value
- `true`, if the search function terminated the traversal by returning `false`
- `false`, if the end of the list of objects was reached
@@ -4903,6 +4885,105 @@ main (void)
- [jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer)
# External context functions
## jerry_create_instance
**Summary**
Creates a JerryScript instance for external context.
**Prototype**
```c
jerry_instance_t *
jerry_create_instance (uint32_t heap_size,
jerry_instance_alloc_t alloc,
void *cb_data_p);
```
- `heap_size` - requested heap size of the JerryScript instance
- `alloc` - function for allocation
- `cb_data_p` - user data
- return value
- pointer to the newly created JerryScript instance if success
- NULL otherwise.
**Example**
[doctest]: # (test="compile")
```c
#include <stdlib.h>
#include <pthread.h>
#include "jerryscript.h"
#include "jerryscript-port.h"
/* A different Thread Local Storage variable for each jerry instance. */
__thread jerry_instance_t *tls_instance;
jerry_instance_t *
jerry_port_get_current_instance (void)
{
/* Returns the instance assigned to the thread. */
return tls_instance;
}
/* Allocate JerryScript heap for each thread. */
static void *
instance_alloc_fn (size_t size, void *cb_data)
{
(void) cb_data;
return malloc (size);
}
static void *
thread_function (void *param)
{
tls_instance = jerry_create_instance (512 * 1024,
instance_alloc_fn,
NULL);
jerry_init (JERRY_INIT_EMPTY);
/* Run the JerryScript instance (e.g.: jerry_parse & jerry_run) */
jerry_cleanup ();
/* Deallocate JerryScript instance */
free (tls_instance);
return NULL;
}
#define NUM_OF_THREADS 8
int
main (void)
{
pthread_t threads[NUM_OF_THREADS];
/* Create the threads. */
for (int i = 0; i < NUM_OF_THREADS; i++)
{
pthread_create (&threads[i], NULL, thread_function, (void *) (intptr_t) i);
}
/* Wait for the threads to complete, and release their resources. */
for (int i = 0; i < NUM_OF_THREADS; i++)
{
pthread_join (threads[i], NULL);
}
return 0;
}
```
**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)
# Snapshot functions
## jerry_generate_snapshot