move threads section to performance to match master branch

tutorials/performance/threads/thread_safe_apis.rst

@@ -0,0 +1,69 @@
+.. _doc_thread_safe_apis:
+
+Thread-safe APIs
+================
+
+Threads
+-------
+
+Threads are used to balance processing power across CPUs and cores.
+Godot supports multithreading, but not in the whole engine.
+
+Below is a list of ways multithreading can be used in different areas of Godot.
+
+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")
+    var enemy = enemy_scene.instance()
+    enemy.add_child(weapon) # Set a weapon.
+    world.call_deferred("add_child", enemy)
+
+Still, this is only really useful if you have **one** thread loading data.
+Attempting to load or create scene chunks from multiple threads may work, but you risk
+resources (which are only loaded once in Godot) tweaked by the multiple
+threads, resulting in unexpected behaviors or crashes.
+
+Only use more than one thread to generate scene data if you *really* know what
+you are doing and you are sure that a single resource is not being used or
+set in multiple ones. Otherwise, you are safer just using the servers API
+(which is fully thread-safe) directly and not touching scene or resources.
+
+Rendering
+---------
+
+Instancing nodes that render anything in 2D or 3D (such as Sprite) is *not* thread-safe by default.
+To make rendering thread-safe, set the **Rendering > Threads > Thread Model** project setting to **Multi-Threaded**.
+
+Note that the Multi-Threaded thread model has several known bugs, so it may not be usable
+in all scenarios.
+
+GDScript arrays, dictionaries
+-----------------------------
+
+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. However handling references on multiple threads is supported, hence loading resources on a thread is as well - scenes, textures, meshes, etc - can be loaded and manipulated on a thread and then added to the active scene on the main thread. The limitation here is as described above, one must be careful not to load the same resource from multiple threads at once, therefore it is easiest to use **one** thread for loading and modifying resources, and then the main thread for adding them.

tutorials/performance/threads/using_multiple_threads.rst

@@ -0,0 +1,185 @@
+.. _doc_using_multiple_threads:
+
+Using multiple threads
+======================
+
+Threads
+-------
+
+Threads allow simultaneous execution of code. It allows off-loading work
+from the main thread.
+
+Godot supports threads and provides many handy functions to use them.
+
+.. note:: If using other languages (C#, C++), it may be easier to use the
+          threading classes they support.
+
+.. warning::
+
+    Before using a built-in class in a thread, read :ref:`doc_thread_safe_apis`
+    first to check whether it can be safely used in a thread.
+
+Creating a Thread
+-----------------
+
+Creating a thread is very simple, just use the following code:
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    var thread
+
+    # The thread will start here.
+    func _ready():
+        thread = Thread.new()
+        # Third argument is optional userdata, it can be any variable.
+        thread.start(self, "_thread_function", "Wafflecopter")
+
+
+    # Run here and exit.
+    # The argument is the userdata passed from start().
+    # If no argument was passed, this one still needs to
+    # be here and it will be null.
+    func _thread_function(userdata):
+        # Print the userdata ("Wafflecopter")
+        print("I'm a thread! Userdata is: ", userdata)
+
+    # Thread must be disposed (or "joined"), for portability.
+    func _exit_tree():
+        thread.wait_to_finish()
+
+Your function will, then, run in a separate thread until it returns.
+Even if the function has returned already, the thread must collect it, so call
+:ref:`Thread.wait_to_finish()<class_Thread_method_wait_to_finish>`, which will
+wait until the thread is done (if not done yet), then properly dispose of it.
+
+Mutexes
+-------
+
+Accessing objects or data from multiple threads is not always supported (if you
+do it, it will cause unexpected behaviors or crashes). Read the
+:ref:`doc_thread_safe_apis` documentation to understand which engine APIs
+support multiple thread access.
+
+When processing your own data or calling your own functions, as a rule, try to
+avoid accessing the same data directly from different threads. You may run into
+synchronization problems, as the data is not always updated between CPU cores
+when modified. Always use a :ref:`Mutex<class_Mutex>` when accessing
+a piece of data from different threads.
+
+When calling :ref:`Mutex.lock()<class_Mutex_method_lock>`, a thread ensures that
+all other threads will be blocked (put on suspended state) if they try to *lock*
+the same mutex. When the mutex is unlocked by calling
+:ref:`Mutex.unlock()<class_Mutex_method_unlock>`, the other threads will be
+allowed to proceed with the lock (but only one at a time).
+
+Here is an example of using a Mutex:
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    var counter = 0
+    var mutex
+    var thread
+
+
+    # The thread will start here.
+    func _ready():
+        mutex = Mutex.new()
+        thread = Thread.new()
+        thread.start(self, "_thread_function")
+
+        # Increase value, protect it with Mutex.
+        mutex.lock()
+        counter += 1
+        mutex.unlock()
+
+
+    # Increment the value from the thread, too.
+    func _thread_function(userdata):
+        mutex.lock()
+        counter += 1
+        mutex.unlock()
+
+
+    # Thread must be disposed (or "joined"), for portability.
+    func _exit_tree():
+        thread.wait_to_finish()
+        print("Counter is: ", counter) # Should be 2.
+
+Semaphores
+----------
+
+Sometimes you want your thread to work *"on demand"*. In other words, tell it
+when to work and let it suspend when it isn't doing anything.
+For this, :ref:`Semaphores<class_Semaphore>` are used. The function
+:ref:`Semaphore.wait()<class_Semaphore_method_wait>` is used in the thread to
+suspend it until some data arrives.
+
+The main thread, instead, uses
+:ref:`Semaphore.post()<class_Semaphore_method_post>` to signal that data is
+ready to be processed:
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    var counter = 0
+    var mutex
+    var semaphore
+    var thread
+    var exit_thread = false
+
+
+    # The thread will start here.
+    func _ready():
+        mutex = Mutex.new()
+        semaphore = Semaphore.new()
+        exit_thread = false
+
+        thread = Thread.new()
+        thread.start(self, "_thread_function")
+
+
+    func _thread_function(userdata):
+        while true:
+            semaphore.wait() # Wait until posted.
+
+            mutex.lock()
+            var should_exit = exit_thread # Protect with Mutex.
+            mutex.unlock()
+
+            if should_exit:
+                break
+
+            mutex.lock()
+            counter += 1 # Increment counter, protect with Mutex.
+            mutex.unlock()
+
+
+    func increment_counter():
+        semaphore.post() # Make the thread process.
+
+
+    func get_counter():
+        mutex.lock()
+        # Copy counter, protect with Mutex.
+        var counter_value = counter
+        mutex.unlock()
+        return counter_value
+
+
+    # Thread must be disposed (or "joined"), for portability.
+    func _exit_tree():
+        # Set exit condition to true.
+        mutex.lock()
+        exit_thread = true # Protect with Mutex.
+        mutex.unlock()
+
+        # Unblock by posting.
+        semaphore.post()
+
+        # Wait until it exits.
+        thread.wait_to_finish()
+
+        # Print the counter.
+        print("Counter is: ", counter)