From 042d1fc4d71c123415b4fb367244be76979faacf Mon Sep 17 00:00:00 2001 From: Akos Kiss Date: Thu, 30 Aug 2018 11:38:49 +0200 Subject: [PATCH] Merge instance into context There was quite some confusion about terminology around instances and contexts. All the docs mentioned external contexts but functions and types were referring to instances, and the relation between these two concepts were not clear. This commit keeps (external) context as the only surviving concept. JerryScript-DCO-1.0-Signed-off-by: Akos Kiss akiss@inf.u-szeged.hu --- docs/02.API-REFERENCE.md | 60 +++++++------- docs/05.PORT-API.md | 41 +++++----- jerry-core/api/jerry.c | 41 +++++----- jerry-core/include/jerryscript-core.h | 10 +-- jerry-core/include/jerryscript-port.h | 8 +- jerry-core/jcontext/jcontext.h | 81 ++++++++++--------- jerry-main/main-unix.c | 14 ++-- jerry-port/default/default-external-context.c | 24 +++--- .../include/jerryscript-port-default.h | 2 +- 9 files changed, 143 insertions(+), 138 deletions(-) diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md index 5cbce80624..d4256747c1 100644 --- a/docs/02.API-REFERENCE.md +++ b/docs/02.API-REFERENCE.md @@ -238,32 +238,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 @@ -4877,26 +4877,26 @@ main (void) # External context functions -## jerry_create_instance +## jerry_create_context **Summary** -Creates a JerryScript instance for external context. +Create an external JerryScript engine context. **Prototype** ```c -jerry_instance_t * -jerry_create_instance (uint32_t heap_size, - jerry_instance_alloc_t alloc, - void *cb_data_p); +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 instance +- `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** @@ -4910,19 +4910,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); @@ -4931,15 +4931,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; } @@ -4969,9 +4969,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 diff --git a/docs/05.PORT-API.md b/docs/05.PORT-API.md index 50ab930e43..41c72a3252 100644 --- a/docs/05.PORT-API.md +++ b/docs/05.PORT-API.md @@ -112,23 +112,25 @@ bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p); double jerry_port_get_current_time (void); ``` -## External instance +## External context -Allow user to provide external buffer for jerry instance (which includes an isolated context and heap with other instances), so that user can config the heap size in runtime and run multiple JS apps simultaneously. +Allow user to provide external buffer for isolated engine contexts, so that user +can configure the heap size at runtime and run multiple JS applications +simultaneously. ```c /** - * Get the current instance which contains the current context, heap and other - * structures. Each port should provide its own implementation of this interface. + * Get the current context of the engine. Each port should provide its own + * implementation of this interface. * * Note: * This port function is called by jerry-core when * JERRY_ENABLE_EXTERNAL_CONTEXT is defined. Otherwise this function is not * used. * - * @return the pointer to the jerry instance. + * @return the pointer to the engine context. */ -struct jerry_instance_t *jerry_port_get_current_instance (void); +struct jerry_context_t *jerry_port_get_current_context (void); ``` ## Sleep @@ -233,37 +235,38 @@ double jerry_port_get_current_time (void) return ((double) tv.tv_sec) * 1000.0 + ((double) tv.tv_usec) / 1000.0; } /* jerry_port_get_current_time */ ``` -## External instance + +## External context ```c #include "jerryscript-port.h" #include "jerryscript-port-default.h" /** - * Pointer to the current instance. + * Pointer to the current context. * Note that it is a global variable, and is not a thread safe implementation. */ -static jerry_instance_t *current_instance_p = NULL; +static jerry_context_t *current_context_p = NULL; /** - * Set the current_instance_p as the passed pointer. + * Set the current_context_p as the passed pointer. */ void -jerry_port_default_set_instance (jerry_instance_t *instance_p) /**< points to the created instance */ +jerry_port_default_set_context (jerry_context_t *context_p) /**< points to the created context */ { - current_instance_p = instance_p; -} /* jerry_port_default_set_instance */ + current_context_p = context_p; +} /* jerry_port_default_set_context */ /** - * Get the current instance. + * Get the current context. * - * @return the pointer to the current instance + * @return the pointer to the current context */ -jerry_instance_t * -jerry_port_get_current_instance (void) +jerry_context_t * +jerry_port_get_current_context (void) { - return current_instance_p; -} /* jerry_port_get_current_instance */ + return current_context_p; +} /* jerry_port_get_current_context */ ``` ## Sleep diff --git a/jerry-core/api/jerry.c b/jerry-core/api/jerry.c index 0430c95a7e..58f55ca085 100644 --- a/jerry-core/api/jerry.c +++ b/jerry-core/api/jerry.c @@ -159,8 +159,9 @@ jerry_init (jerry_init_flag_t flags) /**< combination of Jerry flags */ /* This function cannot be called twice unless jerry_cleanup is called. */ JERRY_ASSERT (!(JERRY_CONTEXT (status_flags) & ECMA_STATUS_API_AVAILABLE)); - /* Zero out all members. */ - memset (&JERRY_CONTEXT (JERRY_CONTEXT_FIRST_MEMBER), 0, sizeof (jerry_context_t)); + /* Zero out all non-external members. */ + memset (&JERRY_CONTEXT (JERRY_CONTEXT_FIRST_MEMBER), 0, + sizeof (jerry_context_t) - offsetof (jerry_context_t, JERRY_CONTEXT_FIRST_MEMBER)); JERRY_CONTEXT (jerry_init_flags) = flags; @@ -2621,20 +2622,20 @@ jerry_is_valid_cesu8_string (const jerry_char_t *cesu8_buf_p, /**< CESU-8 string } /* jerry_is_valid_cesu8_string */ /** - * Create a jerry instance for external context. + * Create an external engine context. * - * @return the pointer to the instance. + * @return the pointer to the context. */ -jerry_instance_t * -jerry_create_instance (uint32_t heap_size, /**< the size of heap */ - jerry_instance_alloc_t alloc, /**< the alloc function */ - void *cb_data_p) /**< the cb_data for alloc function */ +jerry_context_t * +jerry_create_context (uint32_t heap_size, /**< the size of heap */ + jerry_context_alloc_t alloc, /**< the alloc function */ + void *cb_data_p) /**< the cb_data for alloc function */ { JERRY_UNUSED (heap_size); #ifdef JERRY_ENABLE_EXTERNAL_CONTEXT - size_t total_size = sizeof (jerry_instance_t) + JMEM_ALIGNMENT; + size_t total_size = sizeof (jerry_context_t) + JMEM_ALIGNMENT; #ifndef JERRY_SYSTEM_ALLOCATOR heap_size = JERRY_ALIGNUP (heap_size, JMEM_ALIGNMENT); @@ -2650,30 +2651,30 @@ jerry_create_instance (uint32_t heap_size, /**< the size of heap */ total_size = JERRY_ALIGNUP (total_size, JMEM_ALIGNMENT); - jerry_instance_t *instance_p = (jerry_instance_t *) alloc (total_size, cb_data_p); + jerry_context_t *context_p = (jerry_context_t *) alloc (total_size, cb_data_p); - if (instance_p == NULL) + if (context_p == NULL) { return NULL; } - memset (instance_p, 0, total_size); + memset (context_p, 0, total_size); - uintptr_t instance_ptr = ((uintptr_t) instance_p) + sizeof (jerry_instance_t); - instance_ptr = JERRY_ALIGNUP (instance_ptr, (uintptr_t) JMEM_ALIGNMENT); + uintptr_t context_ptr = ((uintptr_t) context_p) + sizeof (jerry_context_t); + context_ptr = JERRY_ALIGNUP (context_ptr, (uintptr_t) JMEM_ALIGNMENT); - uint8_t *byte_p = (uint8_t *) instance_ptr; + uint8_t *byte_p = (uint8_t *) context_ptr; #ifndef JERRY_SYSTEM_ALLOCATOR - instance_p->heap_p = (jmem_heap_t *) byte_p; - instance_p->heap_size = heap_size; + context_p->heap_p = (jmem_heap_t *) byte_p; + context_p->heap_size = heap_size; byte_p += heap_size; #endif /* !JERRY_SYSTEM_ALLOCATOR */ - JERRY_ASSERT (byte_p <= ((uint8_t *) instance_p) + total_size); + JERRY_ASSERT (byte_p <= ((uint8_t *) context_p) + total_size); JERRY_UNUSED (byte_p); - return instance_p; + return context_p; #else /* !JERRY_ENABLE_EXTERNAL_CONTEXT */ @@ -2683,7 +2684,7 @@ jerry_create_instance (uint32_t heap_size, /**< the size of heap */ return NULL; #endif /* JERRY_ENABLE_EXTERNAL_CONTEXT */ -} /* jerry_create_instance */ +} /* jerry_create_context */ /** * If JERRY_VM_EXEC_STOP is defined the callback passed to this function is diff --git a/jerry-core/include/jerryscript-core.h b/jerry-core/include/jerryscript-core.h index d59828bda8..2b17fb2fb1 100644 --- a/jerry-core/include/jerryscript-core.h +++ b/jerry-core/include/jerryscript-core.h @@ -281,9 +281,9 @@ typedef struct } jerry_context_data_manager_t; /** - * Function type for allocating buffer for JerryScript instance. + * Function type for allocating buffer for JerryScript context. */ -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); /** * Type information of a native pointer. @@ -294,9 +294,9 @@ typedef struct } jerry_object_native_info_t; /** - * An opaque declaration of the JerryScript instance structure. + * An opaque declaration of the JerryScript context structure. */ -typedef struct jerry_instance_t jerry_instance_t; +typedef struct jerry_context_t jerry_context_t; /** * General engine functions. @@ -517,7 +517,7 @@ bool jerry_is_valid_cesu8_string (const jerry_char_t *cesu8_buf_p, jerry_size_t /* * External context functions. */ -jerry_instance_t *jerry_create_instance (uint32_t heap_size, jerry_instance_alloc_t alloc, void *cb_data_p); +jerry_context_t *jerry_create_context (uint32_t heap_size, jerry_context_alloc_t alloc, void *cb_data_p); /** * Miscellaneous functions. diff --git a/jerry-core/include/jerryscript-port.h b/jerry-core/include/jerryscript-port.h index 4aae586bcb..59e4b61d29 100644 --- a/jerry-core/include/jerryscript-port.h +++ b/jerry-core/include/jerryscript-port.h @@ -147,17 +147,17 @@ bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p); double jerry_port_get_current_time (void); /** - * Get the current instance which contains the current context, heap and other - * structures. Each port should provide its own implementation of this interface. + * Get the current context of the engine. Each port should provide its own + * implementation of this interface. * * Note: * This port function is called by jerry-core when * JERRY_ENABLE_EXTERNAL_CONTEXT is defined. Otherwise this function is not * used. * - * @return the pointer to the jerry instance. + * @return the pointer to the engine context. */ -struct jerry_instance_t *jerry_port_get_current_instance (void); +struct jerry_context_t *jerry_port_get_current_context (void); /** * Makes the process sleep for a given time. diff --git a/jerry-core/jcontext/jcontext.h b/jerry-core/jcontext/jcontext.h index 6d07ffe4ad..1ab72c1ea5 100644 --- a/jerry-core/jcontext/jcontext.h +++ b/jerry-core/jcontext/jcontext.h @@ -14,7 +14,7 @@ */ /* - * Memory context for JerryScript + * Engine context for JerryScript */ #ifndef JCONTEXT_H #define JCONTEXT_H @@ -33,6 +33,22 @@ * @{ */ + #ifndef JERRY_SYSTEM_ALLOCATOR +/** + * Heap structure + * + * Memory blocks returned by the allocator must not start from the + * beginning of the heap area because offset 0 is reserved for + * JMEM_CP_NULL. This special constant is used in several places, + * e.g. it marks the end of the property chain list, so it cannot + * be eliminated from the project. Although the allocator cannot + * use the first 8 bytes of the heap, nothing prevents to use it + * for other purposes. Currently the free region start is stored + * there. + */ +typedef struct jmem_heap_t jmem_heap_t; +#endif /* !JERRY_SYSTEM_ALLOCATOR */ + /** * User context item */ @@ -46,7 +62,7 @@ typedef struct jerry_context_data_header ((uint8_t *) (item_p + 1)) /** - * First member of the jerry context + * First non-external member of the jerry context */ #define JERRY_CONTEXT_FIRST_MEMBER ecma_builtin_objects @@ -56,9 +72,17 @@ typedef struct jerry_context_data_header * The purpose of this header is storing * all global variables for Jerry */ -typedef struct +struct jerry_context_t { - /* Update JERRY_CONTEXT_FIRST_MEMBER if the first member changes */ + /* The value of external context members must be preserved across initializations and cleanups. */ +#ifdef JERRY_ENABLE_EXTERNAL_CONTEXT +#ifndef JERRY_SYSTEM_ALLOCATOR + jmem_heap_t *heap_p; /**< point to the heap aligned to JMEM_ALIGNMENT. */ + uint32_t heap_size; /**< size of the heap */ +#endif /* !JERRY_SYSTEM_ALLOCATOR */ +#endif /* JERRY_ENABLE_EXTERNAL_CONTEXT */ + + /* Update JERRY_CONTEXT_FIRST_MEMBER if the first non-external member changes */ ecma_object_t *ecma_builtin_objects[ECMA_BUILTIN_ID__COUNT]; /**< pointer to instances of built-in objects */ #ifndef CONFIG_DISABLE_REGEXP_BUILTIN const re_compiled_code_t *re_cache[RE_CACHE_SIZE]; /**< regex cache */ @@ -137,7 +161,8 @@ typedef struct /** hash table for caching the last access of properties */ ecma_lcache_hash_entry_t lcache[ECMA_LCACHE_HASH_ROWS_COUNT][ECMA_LCACHE_HASH_ROW_LENGTH]; #endif /* !CONFIG_ECMA_LCACHE_DISABLE */ -} jerry_context_t; +}; + #ifdef JERRY_ENABLE_EXTERNAL_CONTEXT @@ -145,42 +170,30 @@ typedef struct * This part is for JerryScript which uses external context. */ -#ifndef JERRY_GET_CURRENT_INSTANCE +#ifndef JERRY_GET_CURRENT_CONTEXT /** - * Default function if JERRY_GET_CURRENT_INSTANCE is not defined. + * Default function if JERRY_GET_CURRENT_CONTEXT is not defined. */ -#define JERRY_GET_CURRENT_INSTANCE() (jerry_port_get_current_instance ()) -#endif /* !JERRY_GET_CURRENT_INSTANCE */ +#define JERRY_GET_CURRENT_CONTEXT() (jerry_port_get_current_context ()) +#endif /* !JERRY_GET_CURRENT_CONTEXT */ -#define JERRY_CONTEXT(field) (JERRY_GET_CURRENT_INSTANCE ()->context.field) +#define JERRY_CONTEXT(field) (JERRY_GET_CURRENT_CONTEXT ()->field) #ifndef JERRY_SYSTEM_ALLOCATOR -#define JMEM_HEAP_SIZE (JERRY_GET_CURRENT_INSTANCE ()->heap_size) +#define JMEM_HEAP_SIZE (JERRY_CONTEXT (heap_size)) #define JMEM_HEAP_AREA_SIZE (JMEM_HEAP_SIZE - JMEM_ALIGNMENT) -typedef struct +struct jmem_heap_t { jmem_heap_free_t first; /**< first node in free region list */ uint8_t area[]; /**< heap area */ -} jmem_heap_t; - -#define JERRY_HEAP_CONTEXT(field) (JERRY_GET_CURRENT_INSTANCE ()->heap_p->field) +}; -#endif /* !JERRY_SYSTEM_ALLOCATOR */ +#define JERRY_HEAP_CONTEXT(field) (JERRY_CONTEXT (heap_p)->field) -/** - * Description of jerry instance which is the header of the context space. - */ -struct jerry_instance_t -{ - jerry_context_t context; /**< the context of the instance */ -#ifndef JERRY_SYSTEM_ALLOCATOR - jmem_heap_t *heap_p; /**< point to the heap aligned to JMEM_ALIGNMENT. */ - uint32_t heap_size; /**< size of the heap */ #endif /* !JERRY_SYSTEM_ALLOCATOR */ -}; #else /* !JERRY_ENABLE_EXTERNAL_CONTEXT */ @@ -210,23 +223,11 @@ extern jerry_context_t jerry_global_context; */ #define JMEM_HEAP_AREA_SIZE (JMEM_HEAP_SIZE - JMEM_ALIGNMENT) -/** - * Heap structure - * - * Memory blocks returned by the allocator must not start from the - * beginning of the heap area because offset 0 is reserved for - * JMEM_CP_NULL. This special constant is used in several places, - * e.g. it marks the end of the property chain list, so it cannot - * be eliminated from the project. Although the allocator cannot - * use the first 8 bytes of the heap, nothing prevents to use it - * for other purposes. Currently the free region start is stored - * there. - */ -typedef struct +struct jmem_heap_t { jmem_heap_free_t first; /**< first node in free region list */ uint8_t area[JMEM_HEAP_AREA_SIZE]; /**< heap area */ -} jmem_heap_t; +}; /** * Global heap. diff --git a/jerry-main/main-unix.c b/jerry-main/main-unix.c index 6929bb71ab..84045c36a6 100644 --- a/jerry-main/main-unix.c +++ b/jerry-main/main-unix.c @@ -401,15 +401,15 @@ check_usage (bool condition, /**< the condition that must hold */ #ifdef JERRY_ENABLE_EXTERNAL_CONTEXT /** - * The alloc function passed to jerry_create_instance + * The alloc function passed to jerry_create_context */ static void * -instance_alloc (size_t size, - void *cb_data_p) +context_alloc (size_t size, + void *cb_data_p) { (void) cb_data_p; /* unused */ return malloc (size); -} /* instance_alloc */ +} /* context_alloc */ #endif /* JERRY_ENABLE_EXTERNAL_CONTEXT */ @@ -607,8 +607,8 @@ main (int argc, #ifdef JERRY_ENABLE_EXTERNAL_CONTEXT - jerry_instance_t *instance_p = jerry_create_instance (512*1024, instance_alloc, NULL); - jerry_port_default_set_instance (instance_p); + jerry_context_t *context_p = jerry_create_context (512*1024, context_alloc, NULL); + jerry_port_default_set_context (context_p); #endif /* JERRY_ENABLE_EXTERNAL_CONTEXT */ @@ -873,7 +873,7 @@ main (int argc, jerry_cleanup (); #ifdef JERRY_ENABLE_EXTERNAL_CONTEXT - free (instance_p); + free (context_p); #endif /* JERRY_ENABLE_EXTERNAL_CONTEXT */ return ret_code; } /* main */ diff --git a/jerry-port/default/default-external-context.c b/jerry-port/default/default-external-context.c index 11c7fbab02..13ebe0eb7e 100644 --- a/jerry-port/default/default-external-context.c +++ b/jerry-port/default/default-external-context.c @@ -17,27 +17,27 @@ #include "jerryscript-port-default.h" /** - * Pointer to the current instance. + * Pointer to the current context. * Note that it is a global variable, and is not a thread safe implementation. */ -static jerry_instance_t *current_instance_p = NULL; +static jerry_context_t *current_context_p = NULL; /** - * Set the current_instance_p as the passed pointer. + * Set the current_context_p as the passed pointer. */ void -jerry_port_default_set_instance (jerry_instance_t *instance_p) /**< points to the created instance */ +jerry_port_default_set_context (jerry_context_t *context_p) /**< points to the created context */ { - current_instance_p = instance_p; -} /* jerry_port_default_set_instance */ + current_context_p = context_p; +} /* jerry_port_default_set_context */ /** - * Get the current instance. + * Get the current context. * - * @return the pointer to the current instance + * @return the pointer to the current context */ -jerry_instance_t * -jerry_port_get_current_instance (void) +jerry_context_t * +jerry_port_get_current_context (void) { - return current_instance_p; -} /* jerry_port_get_current_instance */ + return current_context_p; +} /* jerry_port_get_current_context */ diff --git a/jerry-port/default/include/jerryscript-port-default.h b/jerry-port/default/include/jerryscript-port-default.h index a2d06a4a03..c0fd1ca5ef 100644 --- a/jerry-port/default/include/jerryscript-port-default.h +++ b/jerry-port/default/include/jerryscript-port-default.h @@ -37,7 +37,7 @@ bool jerry_port_default_is_abort_on_fail (void); jerry_log_level_t jerry_port_default_get_log_level (void); void jerry_port_default_set_log_level (jerry_log_level_t level); -void jerry_port_default_set_instance (jerry_instance_t *instance_p); +void jerry_port_default_set_context (jerry_context_t *context_p); /** * @}