Added missing documentation of JerryScript instances to the API reference. (#2482)

JerryScript-DCO-1.0-Signed-off-by: László Langó [email protected]

Author: LaszloLango

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

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;