Support external context, heap and lcache (#1778)

JerryScript should support external context, heap and lcache,
so that it can have multiple instances and runtime configurable heap
size.

Related issue: 1746

JerryScript-DCO-1.0-Signed-off-by: Zidong Jiang zidong.jiang@intel.com

docs/05.PORT-API.md

@@ -94,6 +94,24 @@ bool jerry_port_get_time_zone (jerry_time_zone_t *);
 double jerry_port_get_current_time (void);
 ```
 
+## External instance
+
+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.
+
+```c
+/**
+ * Get the current instance, which contains the current context, heap and other infomation.
+ * Each port should provide its own implementation of this interface.
+ *
+ *Note:
+ *    This port function will be called automatically by jerry-core
+ *    wnen JERRY_ENABLE_EXTERNAL_CONTEXT is defined. If not, this function will never be called.
+ *
+ * @return the pointer to the jerry instance.
+ */
+struct jerry_instance_t *jerry_port_get_current_instance (void);
+```
+
 # How to port JerryScript
 
 This section describes a basic port implementation which was created for Unix based systems.
@@ -181,3 +199,35 @@ 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
+
+```c
+#include "jerryscript-port.h"
+#include "jerryscript-port-default.h"
+
+/**
+ * Pointer to the current instance.
+ * Note that it is a global variable, and is not a thread safe implementation.
+ */
+static jerry_instance_t *current_instance_p = NULL;
+
+/**
+ * Set the current_instance_p as the passed pointer.
+ */
+void
+jerry_port_default_set_instance (jerry_instance_t *instance_p) /**< points to the created instance */
+{
+  current_instance_p = instance_p;
+} /* jerry_port_default_set_instance */
+
+/**
+ * Get the current instance.
+ *
+ * @return the pointer to the current instance
+ */
+jerry_instance_t *
+jerry_port_get_current_instance (void)
+{
+  return current_instance_p;
+} /* jerry_port_get_current_instance */
+```