Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[RfC] External context creation without callbacks #2510

Closed
wants to merge 1 commit into from
Closed

[RfC] External context creation without callbacks #2510

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 62 additions & 69 deletions docs/02.API-REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,30 @@ Enum that contains the following elements:
- JERRY_INIT_MEM_STATS_SEPARATE - dump memory statistics and reset peak values after parse
- JERRY_INIT_DEBUGGER - deprecated, an unused placeholder now

## jerry_init_t

**Summary**

JerryScript initialization data.

**Prototype**

```c
typedef struct
{
jerry_init_flag_t flags; /**< combination of engine initialization flags */

/* The following fields are unused if engine is configured to use global context or system allocator. */
void *heap_p; /**< beginning of heap memory */
uint32_t heap_size; /**< size of heap memory */
} jerry_init_t;
```

**See also**

- [jerry_init_flag_t](#jerry_init_flag_t)
- [jerry_init](#jerry_init)

## jerry_type_t

Enum that contains JerryScript API value types:
Expand Down Expand Up @@ -238,22 +262,6 @@ typedef struct
} jerry_context_data_manager_t;
```

## jerry_context_alloc_t

**Summary**

Function type for allocating buffer for JerryScript context.

**Prototype**

```c
typedef void *(*jerry_context_alloc_t) (size_t size, void *cb_data_p);
```

- `size` - allocation size
- `cb_data_p` - pointer to user data


## jerry_context_t

**Summary**
Expand Down Expand Up @@ -488,17 +496,10 @@ on JavaScript values.

```c
void
jerry_init (jerry_init_flag_t flags)
jerry_init (jerry_init_t init_data)
```

`flags` - combination of various engine configuration flags:

- `JERRY_INIT_EMPTY` - no flags, just initialize in default configuration.
- `JERRY_INIT_SHOW_OPCODES` - print compiled byte-code.
- `JERRY_INIT_SHOW_REGEXP_OPCODES` - print compiled regexp byte-code.
- `JERRY_INIT_MEM_STATS` - dump memory statistics.
- `JERRY_INIT_MEM_STATS_SEPARATE` - dump memory statistics and reset peak values after parse.
- `JERRY_INIT_DEBUGGER` - deprecated, an unused placeholder now
- `init_data` - engine initialization data

**Example**

Expand All @@ -510,7 +511,7 @@ jerry_init (jerry_init_flag_t flags)
int
main (void)
{
jerry_init (JERRY_INIT_SHOW_OPCODES | JERRY_INIT_SHOW_REGEXP_OPCODES);
jerry_init (JERRY_INIT_FLAGS (JERRY_INIT_SHOW_OPCODES | JERRY_INIT_SHOW_REGEXP_OPCODES));

// ...

Expand All @@ -520,6 +521,7 @@ main (void)

**See also**

- [jerry_init_t](#jerry_init_t)
- [jerry_cleanup](#jerry_cleanup)


Expand Down Expand Up @@ -653,7 +655,7 @@ jerry_register_magic_strings (const jerry_char_t **ex_str_items_p,
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_init (JERRY_INIT_DEFAULT);

// must be static, because 'jerry_register_magic_strings' does not copy
// the items must be sorted by size at first, then lexicographically
Expand Down Expand Up @@ -736,7 +738,7 @@ jerry_gc (jerry_gc_mode_t mode);
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_init (JERRY_INIT_DEFAULT);

jerry_value_t object_value = jerry_create_object ();
jerry_release_value (object_value);
Expand Down Expand Up @@ -768,12 +770,12 @@ The simplest way to run JavaScript.
bool
jerry_run_simple (const jerry_char_t *script_source_p,
size_t script_source_size,
jerry_init_flag_t flags);
jerry_init_t init_data);
```

- `script_source_p` - source code, it must be a valid utf8 string.
- `script_source_size` - size of source code buffer, in bytes.
- `jerry_init_flag_t` - combination of various engine configuration flags
- `init_data` - engine initialization data
- return value
- true, if run was successful
- false, otherwise
Expand All @@ -791,7 +793,7 @@ main (void)
{
const jerry_char_t *script = (const jerry_char_t *) "print ('Hello, World!');";

jerry_run_simple (script, strlen ((const char *) script), JERRY_INIT_EMPTY);
jerry_run_simple (script, strlen ((const char *) script), JERRY_INIT_DEFAULT);
}
```

Expand Down Expand Up @@ -845,7 +847,7 @@ jerry_parse (const jerry_char_t *resource_name_p, /**< resource name (usually a
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_init (JERRY_INIT_DEFAULT);

const jerry_char_t script[] = "print ('Hello, World!');";
size_t script_size = strlen ((const char *) script);
Expand Down Expand Up @@ -934,7 +936,7 @@ main (void)
size_t script_size = strlen ((const char *) script);

/* Initialize engine */
jerry_init (JERRY_INIT_EMPTY);
jerry_init (JERRY_INIT_DEFAULT);

/* Setup Global scope code */
jerry_value_t parsed_code = jerry_parse (NULL, 0, script, script_size, JERRY_PARSE_NO_OPTS);
Expand Down Expand Up @@ -1022,7 +1024,7 @@ jerry_run_all_enqueued_jobs (void)
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_init (JERRY_INIT_DEFAULT);

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);
Expand Down Expand Up @@ -4803,7 +4805,7 @@ main (void)

if (jerry_is_valid_utf8_string (script, (jerry_size_t) script_size))
{
jerry_run_simple (script, script_size, JERRY_INIT_EMPTY);
jerry_run_simple (script, script_size, JERRY_INIT_DEFAULT);
}
}
```
Expand Down Expand Up @@ -4846,7 +4848,7 @@ jerry_is_valid_cesu8_string (const jerry_char_t *cesu8_buf_p, /**< CESU-8 string
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_init (JERRY_INIT_DEFAULT);

const jerry_char_t script[] = "Hello, World!";
size_t script_size = strlen ((const char *) script);
Expand Down Expand Up @@ -4923,34 +4925,30 @@ void jerry_heap_free (void *mem_p, size_t size);

# External context functions

## jerry_create_context
## jerry_context_size

**Summary**

Create an external JerryScript engine context.
The size of an engine context, which may be used for external context
allocation.

**Prototype**

```c
jerry_context_t *
jerry_create_context (uint32_t heap_size,
jerry_context_alloc_t alloc,
void *cb_data_p);
size_t
jerry_context_size (void)
```

- `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 context if success
- NULL otherwise.
- number of bytes needed to represent a context

**Example**

[doctest]: # (test="compile")

```c
#include <stdlib.h>
#include <string.h>
#include <pthread.h>

#include "jerryscript.h"
Expand All @@ -4966,26 +4964,22 @@ jerry_port_get_current_context (void)
return tls_context;
}

/* Allocate JerryScript heap for each thread. */
static void *
context_alloc_fn (size_t size, void *cb_data)
{
(void) cb_data;
return malloc (size);
}

static void *
thread_function (void *param)
{
tls_context = jerry_create_context (512 * 1024,
context_alloc_fn,
NULL);
jerry_init (JERRY_INIT_EMPTY);
tls_context = malloc (jerry_context_size ());
memset (tls_context, 0, jerry_context_size ());

uint32_t heap_size = 512 * 1024;
void *heap_p = malloc (heap_size);

jerry_init (JERRY_INIT_DATA (JERRY_INIT_EMPTY, heap_p, heap_size));
/* Run JerryScript in the context (e.g.: jerry_parse & jerry_run) */
jerry_cleanup ();

/* Deallocate JerryScript context */
/* Deallocate JerryScript context and heap */
free (tls_context);
free (heap_p);

return NULL;
}
Expand Down Expand Up @@ -5016,7 +5010,6 @@ main (void)
**See also**

- [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)


Expand Down Expand Up @@ -5065,7 +5058,7 @@ jerry_generate_snapshot (const jerry_char_t *resource_name_p,
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_init (JERRY_INIT_DEFAULT);

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'; }) ();";
Expand Down Expand Up @@ -5145,7 +5138,7 @@ jerry_generate_function_snapshot (const jerry_char_t *resource_name_p,
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_init (JERRY_INIT_DEFAULT);

static uint32_t func_snapshot_buffer[256];
const jerry_char_t *args_p = (const jerry_char_t *) "a, b";
Expand Down Expand Up @@ -5218,7 +5211,7 @@ 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_init (JERRY_INIT_DEFAULT);

jerry_value_t generate_result;
generate_result = jerry_generate_snapshot (NULL,
Expand All @@ -5234,7 +5227,7 @@ main (void)

jerry_cleanup ();

jerry_init (JERRY_INIT_EMPTY);
jerry_init (JERRY_INIT_DEFAULT);

jerry_value_t res = jerry_exec_snapshot (global_mode_snapshot_buffer,
global_mode_snapshot_size,
Expand Down Expand Up @@ -5297,7 +5290,7 @@ 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;";

jerry_init (JERRY_INIT_EMPTY);
jerry_init (JERRY_INIT_DEFAULT);

jerry_value_t generate_result;
generate_result = jerry_generate_function_snapshot (NULL,
Expand All @@ -5315,7 +5308,7 @@ main (void)

jerry_cleanup ();

jerry_init (JERRY_INIT_EMPTY);
jerry_init (JERRY_INIT_DEFAULT);

jerry_value_t func = jerry_load_function_snapshot (snapshot_buffer,
snapshot_size,
Expand Down Expand Up @@ -5391,7 +5384,7 @@ jerry_parse_and_save_literals (const jerry_char_t *source_p,
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_init (JERRY_INIT_DEFAULT);

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' }";
Expand Down Expand Up @@ -5483,7 +5476,7 @@ vm_exec_stop_callback (void *user_p)
int
main (void)
{
jerry_init (JERRY_INIT_EMPTY);
jerry_init (JERRY_INIT_DEFAULT);

jerry_set_vm_exec_stop_callback (vm_exec_stop_callback, &countdown, 16);

Expand Down
Loading