From 7b32fa3c8e258c13daaabe47d07cf463fec2ecc5 Mon Sep 17 00:00:00 2001
From: Juan Linietsky <reduzio@gmail.com>
Date: Mon, 30 Jul 2018 16:03:46 -0300
Subject: [PATCH] Add a tutorial about which APIs are thread safe (please
 review!)

---
 index.rst                              |  1 +
 tutorials/threads/index.rst            |  8 ++++
 tutorials/threads/thread_safe_apis.rst | 52 ++++++++++++++++++++++++++
 3 files changed, 61 insertions(+)
 create mode 100644 tutorials/threads/index.rst
 create mode 100644 tutorials/threads/thread_safe_apis.rst

diff --git a/index.rst b/index.rst
index 1d8bbf8fd..84de9d4a0 100644
--- a/index.rst
+++ b/index.rst
@@ -83,6 +83,7 @@ The main documentation for the site is organized into the following sections:
    tutorials/vr/index
    tutorials/plugins/index
    tutorials/platform/index
+   tutorials/threads/index
    tutorials/misc/index
    tutorials/debug/index
 
diff --git a/tutorials/threads/index.rst b/tutorials/threads/index.rst
new file mode 100644
index 000000000..795349036
--- /dev/null
+++ b/tutorials/threads/index.rst
@@ -0,0 +1,8 @@
+Multi-Threading
+===============
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-learn-features-threads
+
+   thread_safe_apis
diff --git a/tutorials/threads/thread_safe_apis.rst b/tutorials/threads/thread_safe_apis.rst
new file mode 100644
index 000000000..9419e36bd
--- /dev/null
+++ b/tutorials/threads/thread_safe_apis.rst
@@ -0,0 +1,52 @@
+.. _doc_thread_safe_apis:
+
+Thread Safe APIs
+=============
+
+Threads
+-------
+
+Using threads is a common way to balance processing scatter it across CPUs and cores.
+Godot supports multi threading, but not in the whole engine.
+
+Below is a list of the areas in Godot and how they can be used with threads.
+
+Global Scope
+------------
+
+:ref:`Global Scope<class_@GlobalScope>` singletons are all thread safe. Accessing servers from threads is supported (for VisualServer and Physics servers, ensure threaded or thread safe operation is enabled in the project settings!).
+
+This makes them ideal for code that creates dozens of thousands of instances in servers and controls them from threads. Of course, it requires a bit more code, as this is used directly and not within the scene tree.
+
+Scene Tree
+----------
+
+Interacting with the active scene tree is **NOT** thread safe. Make sure to use mutexes when sending data between threads. If you want to call functions from a thread, the *call_deferred* function may be used:
+
+::
+
+	# unsafe:
+        node.add_child(child_node)
+ 	# safe:
+	node.call_deferred("add_child",child_node)
+
+However, creating scene chunks (nodes in tree arrangement) outside the active tree is fine. This way, parts of a scene can be built or instantiated in a thread, then added in the main thread:
+
+::
+
+	var enemy_scene = load("res://enemy_scene.scn").instance()
+        var enemy = enemy_scene.instance()
+	enemy.add_child(weapon) #set a weapon
+	world.call_deferred("add_child",enemy)
+
+Containers
+----------
+
+In GDScript, reading and writing elements from multiple threads is ok, but anything that changes the container size (resizing, adding or removing elements) requires locking a mutex.
+
+Resources
+---------
+
+Modifying a unique resource from multiple threads is not supported, but loading them on threads or handling a reference is perfectly supported. Scenes, textures, meshes, etc. Can be loaded and manipulated on threads, then added to the active scene in the main thread.
+
+