Work in progress

The content of this page was not yet updated for Godot 4.2 and may be outdated. If you know how to improve this page or you can confirm that it's up to date, feel free to open a pull request.

APIs thread safe¶

Hilos¶

Los hilos (threads) se utilizan para equilibrar la potencia de procesamiento entre las CPUs y los núcleos. Godot admite el multihilo, pero no en todo el motor.

Debajo se menciona una lista de los modos en que se puede usar multithreading en las distintas partes de Godot.

Ámbito Global¶

Global Scope singletons are all thread-safe. Accessing servers from threads is supported (for RenderingServer and Physics servers, ensure threaded or thread-safe operation is enabled in the project settings!).

Esto los hace ideales para el código que crea decenas de miles de instancias en servidores y las controla desde hilos. Por supuesto, esto requiere un poco más de código, ya que se utiliza directamente y no dentro del árbol de escenas.

Árbol de escenas¶

Interactuar con el árbol de escenas activo NO es seguro para hilos. Asegúrate de utilizar mutexes al enviar datos entre hilos. Si deseas llamar funciones desde un hilo, puedes utilizar la función call_deferred:

# Unsafe:
node.add_child(child_node)
# Safe:
node.call_deferred("add_child", child_node)

Sin embargo, crear fragmentos de escena (nodos en una disposición de árbol) fuera del árbol activo está bien. De esta manera, se pueden construir o instanciar partes de una escena en un hilo y luego agregarlas en el hilo principal:

var enemy_scene = load("res://enemy_scene.scn")
var enemy = enemy_scene.instantiate()
enemy.add_child(weapon) # Set a weapon.
world.call_deferred("add_child", enemy)

Aún así, esto solo es realmente útil si tienes un solo hilo cargando datos. Intentar cargar o crear fragmentos de escena desde varios hilos puede funcionar, pero corres el riesgo de que los recursos (que solo se cargan una vez en Godot) sean modificados por los múltiples hilos, lo que puede llevar a comportamientos inesperados o fallos.

Solo utiliza más de un hilo para generar datos de escena si realmente sabes lo que estás haciendo y estás seguro de que un solo recurso no está siendo utilizado o establecido en múltiples lugares. De lo contrario, es más seguro utilizar directamente la API de los servidores (que es completamente segura para hilos) y no modificar la escena o los recursos.

Renderización¶

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 > Driver > Thread Model project setting to Multi-Threaded.

Ten en cuenta que el modelo de hilos "Multi-Threaded" tiene varios errores conocidos, por lo que puede no ser utilizable en todos los escenarios.

You should avoid calling functions involving direct interaction with the GPU on other threads, such as creating new textures or modifying and retrieving image data, these operations can lead to performance stalls because they require synchronization with the RenderingServer, as data needs to be transmitted to or updated on the GPU.

Arrays y diccionarios GDScript¶

En GDScript, leer y escribir elementos desde múltiples hilos está bien, pero cualquier cosa que cambie el tamaño del contenedor (redimensionar, agregar o eliminar elementos) requiere bloquear un mutex.

Recursos¶

Modificar un recurso único desde múltiples hilos no está soportado. Sin embargo, manipular referencias en múltiples hilos sí está soportado, por lo tanto, cargar recursos en un hilo también lo está. Escenas, texturas, mallas, etc., se pueden cargar y manipular en un hilo y luego agregar al escena activa en el hilo principal. La limitación aquí es, como se describió anteriormente, que debes tener cuidado de no cargar el mismo recurso desde múltiples hilos al mismo tiempo. Por lo tanto, lo más fácil es utilizar un solo hilo para cargar y modificar recursos, y luego utilizar el hilo principal para agregarlos.