godotengine / godotengine/godot-docs
Thread documentation missing explanation of multithreading signals
- 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.