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

docs/02.API-REFERENCE.md

@@ -225,8 +225,10 @@ typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_na
 
 **Summary**
 
-Initializes the JerryScript engine, making possible to run JavaScript code and perform operations on
-JavaScript values.
+Initializes the JerryScript engine, making it possible to run JavaScript code and perform operations
+on JavaScript values. See also [jerry_init_with_user_context](#jerry_init_with_user_context) if you
+wish to initialize the JerryScript engine in such a way that its context contains a custom pointer
+which you can later retrieve using [jerry_get_user_context](#jerry_get_user_context).
 
 **Prototype**
 
@@ -259,13 +261,91 @@ jerry_init (jerry_init_flag_t flags)
 **See also**
 
 - [jerry_cleanup](#jerry_cleanup)
+- [jerry_init_with_user_context](#jerry_init_with_user_context)
+
+
+## jerry_init_with_user_context
+
+**Summary**
+
+Calls [jerry_init](#jerry_init) to initialize the JerryScript engine, thereby making it possible
+to run JavaScript code and perform operations on JavaScript values. In addition to the first
+parameter this function accepts two more parameters with which it allows the caller to store a
+`void *` pointer inside the context being initialized with `jerry_init ()`. The function calls the
+callback given in its `init_cb` parameter to allocate the memory for the pointer and it stores the
+function pointer given in the `deinit_cb` parameter along with the pointer so that it may be called
+to free the stored pointer when `jerry_cleanup ()` is later called to dispose of the context.
+
+**Prototype**
+
+```c
+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);
+```
+
+`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` - enable all features required by debugging.
+
+`init_cb` - a function pointer that will be called to allocate the custom pointer.
+
+`deinit_cb` - a function pointer that will be called when the custom pointer must be freed.
+
+**Example**
+
+```c
+void *
+init_user_context (void)
+{
+  void *return_value;
+
+  /* allocate and initialize return_value */
+
+  return return_value;
+} /* init_user_context */
+
+void
+free_user_context (void *context)
+{
+
+  /* free the value allocated above */
+
+} /* free_user_context */
+
+{
+  /* init_user_context () will be called before the call below returns */
+  jerry_init_with_user_context (JERRY_INIT_SHOW_OPCODES | JERRY_INIT_SHOW_REGEXP_OPCODES,
+                                init_user_context,
+                                free_user_context);
+
+  /* ... */
+
+  /* free_user_context () will be called before the call below returns */
+  jerry_cleanup ();
+}
+```
+
+**See also**
+
+- [jerry_cleanup](#jerry_cleanup)
+- [jerry_get_user_context](#jerry_get_user_context)
 
 
 ## jerry_cleanup
 
 **Summary**
 
-Finish JavaScript engine execution, freeing memory and JavaScript values.
+Finish JavaScript engine execution, freeing memory and JavaScript values. If the context was
+initialized with `jerry_init_with_user_context ()` and a `deinit_cb` was provided, then it will
+be called to free the memory at the custom pointer which was associated with the context being
+cleaned up.
 
 *Note*: JavaScript values, received from engine, will be inaccessible after the cleanup.
 
@@ -279,6 +359,37 @@ jerry_cleanup (void);
 **See also**
 
 - [jerry_init](#jerry_init)
+- [jerry_init_with_user_context](#jerry_init_with_user_context)
+
+
+## jerry_get_user_context
+
+**Summary**
+
+Retrieve the pointer stored within the current context.
+
+**Prototype**
+
+```c
+void *
+jerry_get_user_context (void);
+```
+
+- return value: the pointer that was assigned during `jerry_init_with_user_context ()`
+
+**Example**
+
+```c
+{
+  /* ... */
+  my_context *custom_data = (my_context *) jerry_get_user_context ();
+  /* ... */
+}
+```
+
+**See also**
+- [jerry_init_with_user_context](#jerry_init_with_user_context)
+- [jerry_cleanup](#jerry_cleanup)
 
 
 ## jerry_register_magic_strings