From df1893042d16b3cee5e5db01797ee0c269022796 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=A1szl=C3=B3=20Lang=C3=B3?=
 <llango.u-szeged@partner.samsung.com>
Date: Thu, 30 Aug 2018 09:25:11 +0200
Subject: [PATCH] Added missing documentation of JerryScript instances to the
 API reference. (#2482)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

JerryScript-DCO-1.0-Signed-off-by: László Langó llango.u-szeged@partner.samsung.com
---
 docs/02.API-REFERENCE.md              | 127 ++++++++++++++++++++++++++
 jerry-core/include/jerryscript-core.h |   2 +-
 2 files changed, 128 insertions(+), 1 deletion(-)

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index 6b2a83d53..ee99c90d4 100644
--- a/docs/02.API-REFERENCE.md
+++ b/docs/02.API-REFERENCE.md
@@ -250,6 +250,34 @@ typedef struct
 } jerry_context_data_manager_t;
 ```
 
+## jerry_instance_alloc_t
+
+**Summary**
+
+Function type for allocating buffer for JerryScript instance.
+
+**Prototype**
+
+```c
+typedef void *(*jerry_instance_alloc_t) (size_t size, void *cb_data_p);
+```
+
+- `size` - allocation size
+- `cb_data_p` - pointer to user data
+
+
+## jerry_instance_t
+
+**Summary**
+
+An opaque declaration of the JerryScript instance structure which is the header of the context space.
+
+**Prototype**
+
+```c
+typedef struct jerry_instance_t jerry_instance_t;
+```
+
 ## jerry_property_descriptor_t
 
 **Summary**
@@ -4859,6 +4887,105 @@ main (void)
 - [jerry_substring_to_char_buffer](#jerry_substring_to_char_buffer)
 
 
+# External context functions
+
+## jerry_create_instance
+
+**Summary**
+
+Creates a JerryScript instance for external context.
+
+**Prototype**
+
+```c
+jerry_instance_t *
+jerry_create_instance (uint32_t heap_size,
+                       jerry_instance_alloc_t alloc,
+                       void *cb_data_p);
+```
+
+- `heap_size` - requested heap size of the JerryScript instance
+- `alloc` - function for allocation
+- `cb_data_p` - user data
+- return value
+  - pointer to the newly created JerryScript instance if success
+  - NULL otherwise.
+
+**Example**
+
+[doctest]: # (test="compile")
+
+```c
+#include <stdlib.h>
+#include <pthread.h>
+
+#include "jerryscript.h"
+#include "jerryscript-port.h"
+
+/* A different Thread Local Storage variable for each jerry instance. */
+__thread jerry_instance_t *tls_instance;
+
+jerry_instance_t *
+jerry_port_get_current_instance (void)
+{
+  /* Returns the instance assigned to the thread. */
+  return tls_instance;
+}
+
+/* Allocate JerryScript heap for each thread. */
+static void *
+instance_alloc_fn (size_t size, void *cb_data)
+{
+  (void) cb_data;
+  return malloc (size);
+}
+
+static void *
+thread_function (void *param)
+{
+  tls_instance = jerry_create_instance (512 * 1024,
+                                        instance_alloc_fn,
+                                        NULL);
+  jerry_init (JERRY_INIT_EMPTY);
+  /* Run the JerryScript instance (e.g.: jerry_parse & jerry_run) */
+  jerry_cleanup ();
+
+  /* Deallocate JerryScript instance */
+  free (tls_instance);
+
+  return NULL;
+}
+
+#define NUM_OF_THREADS 8
+
+int
+main (void)
+{
+  pthread_t threads[NUM_OF_THREADS];
+
+  /* Create the threads. */
+  for (int i = 0; i < NUM_OF_THREADS; i++)
+  {
+    pthread_create (&threads[i], NULL, thread_function, (void *) (intptr_t) i);
+  }
+
+  /* Wait for the threads to complete, and release their resources. */
+  for (int i = 0; i < NUM_OF_THREADS; i++)
+  {
+    pthread_join (threads[i], NULL);
+  }
+
+  return 0;
+}
+```
+
+**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)
+
+
 # Snapshot functions
 
 ## jerry_generate_snapshot
diff --git a/jerry-core/include/jerryscript-core.h b/jerry-core/include/jerryscript-core.h
index c4951f542..b41108a4a 100644
--- a/jerry-core/include/jerryscript-core.h
+++ b/jerry-core/include/jerryscript-core.h
@@ -299,7 +299,7 @@ typedef struct
 } jerry_object_native_info_t;
 
 /**
- * A forward declaration of the JerryScript instance structure.
+ * An opaque declaration of the JerryScript instance structure.
  */
 typedef struct jerry_instance_t jerry_instance_t;