Support a user context void * pointer in jerry_context_t (#1717) (#1727)

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 #1717

JerryScript-DCO-1.0-Signed-off-by: Gabriel Schulhof gabriel.schulhof@intel.com

jerry-core/jerry.c

@@ -166,6 +166,22 @@ jerry_init (jerry_init_flag_t flags) /**< combination of Jerry flags */
 #endif /* JERRY_DEBUGGER */
 } /* jerry_init */
 
+/**
+ * Initialize Jerry engine with custom user context.
+ */
+void
+jerry_init_with_user_context (jerry_init_flag_t flags,  /**< combination of Jerry flags */
+                              jerry_user_context_init_cb init_cb, /**< callback to call to create the user context or
+                                                                    *  NULL, in which case no user context will be
+                                                                    *  created */
+                              jerry_user_context_deinit_cb deinit_cb) /**< callback to call to free the user context or
+                                                                        *  NULL if it does not need to be freed */
+{
+  jerry_init (flags);
+  JERRY_CONTEXT (user_context_p) = (init_cb ? init_cb () : NULL);
+  JERRY_CONTEXT (user_context_deinit_cb) = deinit_cb;
+} /* jerry_init_with_user_context */
+
 /**
  * Terminate Jerry engine
  */
@@ -185,8 +201,24 @@ 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_p));
+  }
 } /* jerry_cleanup */
 
+/**
+ * Retrieve user context.
+ *
+ * @return the user-provided context-specific pointer
+ */
+void *
+jerry_get_user_context (void)
+{
+  return JERRY_CONTEXT (user_context_p);
+} /* jerry_get_user_context */
+
 /**
  * Register external magic string array
  */