Support a user context void * pointer in jerry_context_t (jerryscript…

…-project#1717)

This modification makes it possible to initialize a context in such a
way that a `void *` pointer is stored inside the context and is made
available via a new `jerry_get_user_context()` API.

The pointer is initialized via a new `jerry_init_with_user_context()`
API, which calls the existing `jerry_init()`, after which it sets the
value of the new `user_context` element in the `jerry_context_t`
structure using the context allocation callback provided as the second
parameter to the new `jerry_init_with_user_context()` API. The location
of the cleanup function responsible for deallocating the pointer created
by the context allocation callback is provided as the third parameter.
This location is stored in the context along with the pointer itself.

When a context is discarded via `jerry_cleanup()`, the user context
cleanup function is called to dispose of the pointer stored within the
context.

The semantics behind the API are such that it is now possible to choose
for each context an agent which manages arbitrary user data keyed to the
given context. The agent must be chosen at context instantiation time
and cannot be changed afterwards, remaining in effect for the lifetime
of the context.

Fixes jerryscript-project#1717

JerryScript-DCO-1.0-Signed-off-by: Zidong Jiang [email protected]

jerry-core/jcontext/jcontext.h

@@ -103,6 +103,8 @@ typedef struct
   uint8_t valgrind_freya_mempool_request; /**< Tells whether a pool manager
                                            *   allocator request is in progress */
 #endif /* JERRY_VALGRIND_FREYA */
+  void *user_context;
+  jerry_user_context_deinit_cb user_context_deinit_cb;
 } jerry_context_t;
 
 /**

jerry-core/jerry.c

@@ -166,6 +166,18 @@ jerry_init (jerry_init_flag_t flags) /**< combination of Jerry flags */
 #endif /* JERRY_DEBUGGER */
 } /* jerry_init */
 
+/**
+ * Jerry engine initialization with custom user context
+ */
+void
+jerry_init_with_user_context (jerry_init_flag_t flags, jerry_user_context_init_cb init_cb,
+                              jerry_user_context_deinit_cb deinit_cb)
+{
+  jerry_init (flags);
+  JERRY_CONTEXT (user_context) = (init_cb ? init_cb () : NULL);
+  JERRY_CONTEXT (user_context_deinit_cb) = deinit_cb;
+} /* jerry_init_with_user_context */
+
 /**
  * Terminate Jerry engine
  */
@@ -185,8 +197,22 @@ jerry_cleanup (void)
 
   jmem_finalize ();
   jerry_make_api_unavailable ();
+
+  if (JERRY_CONTEXT (user_context_deinit_cb))
+  {
+    JERRY_CONTEXT (user_context_deinit_cb) (JERRY_CONTEXT (user_context));
+  }
 } /* jerry_cleanup */
 
+/**
+ * Retrieve user context
+ */
+void *
+jerry_get_user_context (void)
+{
+  return JERRY_CONTEXT (user_context);
+} /* jerry_get_user_context */
+
 /**
  * Register external magic string array
  */

jerry-core/jerryscript.h

@@ -177,6 +177,16 @@ typedef void (*jerry_object_native_free_callback_t) (void *native_p);
 typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_name,
                                                  const jerry_value_t property_value,
                                                  void *user_data_p);
+/**
+ * Function type for user context allocation
+ */
+typedef void *(*jerry_user_context_init_cb) (void);
+
+/**
+ * Function type for user context deallocation
+ */
+typedef void (*jerry_user_context_deinit_cb) (void *user_context);
+
 /**
  * Type information of a native pointer.
  */
@@ -189,11 +199,14 @@ typedef struct
  * General engine functions
  */
 void jerry_init (jerry_init_flag_t flags);
+void jerry_init_with_user_context (jerry_init_flag_t flags, jerry_user_context_init_cb init_cb,
+                                   jerry_user_context_deinit_cb deinit_cb);
 void jerry_cleanup (void);
 void jerry_register_magic_strings (const jerry_char_ptr_t *ex_str_items_p, uint32_t count,
                                    const jerry_length_t *str_lengths_p);
 void jerry_get_memory_limits (size_t *out_data_bss_brk_limit_p, size_t *out_stack_limit_p);
 void jerry_gc (void);
+void *jerry_get_user_context (void);
 
 /**
  * Parser and executor functions

tests/unit/test-user-context.c

@@ -0,0 +1,51 @@
+/* Copyright JS Foundation and other contributors, http://js.foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "config.h"
+#include "jerryscript.h"
+#include "test-common.h"
+
+static const char *identifying_string = "identifying string";
+static bool user_context_new_was_called = false;
+static bool user_context_free_was_called = false;
+
+static void *user_context_new (void)
+{
+  user_context_new_was_called = true;
+  return (void *) identifying_string;
+} /* user_context_new */
+
+static void user_context_free (void *user_context)
+{
+  user_context_free_was_called = true;
+  TEST_ASSERT (((const char *) user_context) == identifying_string);
+} /* user_context_free */
+
+int
+main (void)
+{
+  TEST_INIT ();
+
+  jerry_init_with_user_context (JERRY_INIT_EMPTY, user_context_new, user_context_free);
+
+  TEST_ASSERT ((((const char *)(jerry_get_user_context ()))) == identifying_string);
+
+  jerry_cleanup ();
+
+  TEST_ASSERT (user_context_new_was_called);
+  TEST_ASSERT (user_context_free_was_called);
+
+  return 0;
+} /* main */