godotengine / godotengine/godot-docs

Thread documentation missing explanation of multithreading signals

Open
#4,734 0 comments 2 reactions 0 assignees View on GitHub
area:manual enhancement
Dominant language
reStructuredText
Stars
5.7k
Forks
3.8k
Avg merge
1d 20h
Merged PRs (30d)
25

Description

**Your Godot version:**
3.2 and 4.0.dev

**Issue description:**
There is no explanation on how to use call_deferred and connect with CONNECT_DEFERRED as a means for sending responses from a thread back to the main thread.

As demonstration that the documentation is missing or lacking, there is an unanswered question here asking for this information:
https://godotengine.org/qa/67220/gdscript-emitting-signal-from-thread-back-to-the-main-thread

I was lucky to have a Godot expert in my contacts and they informed me of this usage of Object APIs for thread-safe message passing to the main thread. I would like this knowledge to be passed onto the rest of the Godot community.

**URL to the documentation page:**
There are 5 pages/sections which need updating:

1. Signal documentations makes no mention of call_deferred or CONNECT_DEFERRED or threads:
https://docs.godotengine.org/en/latest/getting_started/step_by_step/signals.html

2. "Using multiple threads" makes no mention of call_deferred or CONNECT_DEFERRED.
https://docs.godotengine.org/en/stable/tutorials/threads/using_multiple_threads.html

3. "Thread-Safe APIs" mentions call_deferred for use with scene nodes, but does not mention CONNECT_DEFERRED, nor the fact that these APIs apply to all Object types, not just Nodes. https://docs.godotengine.org/en/stable/tutorials/threads/thread_safe_apis.html

4. Object documentation with call_deferred makes no mention of the API's interaction with threads or thread-safety.
https://docs.godotengine.org/en/stable/classes/class_object.html#class-object-method-connect

5. The usage of the CONNECT_DEFRRED flag in the connect() function is undocumented there. The only docs are a single line next to the constant definition:
" Connects a signal in deferred mode. This way, signal emissions are stored in a queue, then set on idle time. "
The meaning of this sentence with regard to thread safety is not obvious. It should be stated explicitly.
https://docs.godotengine.org/en/stable/classes/class_object.html#class-object-method-connect

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.