Add ability to suspend threads until a signal is called

For GDScript users that run code on threads, it often happens they want to `await` until something happens,
the continue the thread execution.

Unfortunately, signals will most likely execute on the main thread, hence this means that the code being run on
the thread will continue running on the main thread by default.

It has been discussed whether await should be smart about this and simply suspend the
thread if running on one. The problem with this is, that users may also be willing to
emit the signal that will resume from the thread itself and, at the time of awaiting,
there is **no way for the interpreter to know on which thread the function will be resumed**.

Additionally, suspending the thread is a very different operation than awaiting. Awaiting saves the local
function stack and returns immediately, while suspending stops the whole thread until another resumes it.
Mixing and matching both seems, ultimately, undesired as they are not the same.

To solve this, a new utility function is added by this pull request, which
suspends a thread until a signal is emitted (no matter in which other thread).

It works like this.

```GDScript
	# Suspends a thread until a button is pressed.
	Thread.suspend( button.pressed )
```

If code must do this and can run on both the main thread or a dedicated thread,
it can do as follows:

```GDScript
	# Suspends a thread until a button is pressed.
	if (Thread.is_main_thread()):
		await button.pressed
	else:
		Thread.suspend( button.pressed )
```

For this, the `Thread.is_main_thread()` function (already existing in the internal Thread object)
has been exposed to the engine API.

**Q**: Are you sure this can't be done with await transparently?
**A**: No, please read again. There is no way for await to know beforehand how the function will be resumed. Only the user knows.

**Q**: Does it not make more sense to have an `await_thread` or something where the user will pass the argument?
**A**: I think its better to have a dedicated utility function for this. Not only the intention is more explicit, but additionally, as this makes it non exclusive to GDScript. It can be used from other languages that use the engine.

Author: reduz

core/core_bind.cpp

@@ -1391,6 +1391,10 @@ bool Thread::is_alive() const {
 	return running.is_set();
 }
 
+bool Thread::is_main_thread() {
+	return ::Thread::is_main_thread();
+}
+
 Variant Thread::wait_to_finish() {
 	ERR_FAIL_COND_V_MSG(!is_started(), Variant(), "Thread must have been started to wait for its completion.");
 	thread.wait_to_finish();
@@ -1405,6 +1409,87 @@ void Thread::set_thread_safety_checks_enabled(bool p_enabled) {
 	set_current_thread_safe_for_nodes(!p_enabled);
 }
 
+class CallableCustomSuspend : public CallableCustom {
+	Semaphore *semaphore = nullptr;
+	Variant *return_value = nullptr;
+
+	// Never really going to execute since disconnection is automatic.
+	static bool _equal_func(const CallableCustom *p_a, const CallableCustom *p_b) {
+		const CallableCustomSuspend *A = static_cast<const CallableCustomSuspend *>(p_a);
+		const CallableCustomSuspend *B = static_cast<const CallableCustomSuspend *>(p_b);
+
+		return A->semaphore == B->semaphore;
+	}
+
+	// Never really going to execute since disconnection is automatic.
+	static bool _less_func(const CallableCustom *p_a, const CallableCustom *p_b) {
+		const CallableCustomSuspend *A = static_cast<const CallableCustomSuspend *>(p_a);
+		const CallableCustomSuspend *B = static_cast<const CallableCustomSuspend *>(p_b);
+
+		return A->semaphore < B->semaphore;
+	}
+
+public:
+	//for every type that inherits, these must always be the same for this type
+	virtual uint32_t hash() const override {
+		return size_t(semaphore);
+	}
+
+	virtual String get_as_text() const override {
+		return "SemaphoreCallable";
+	}
+
+	virtual CompareEqualFunc get_compare_equal_func() const override {
+		return _equal_func;
+	}
+
+	virtual CompareLessFunc get_compare_less_func() const override {
+		return _less_func;
+	}
+
+	virtual ObjectID get_object() const override {
+		return ObjectID();
+	}
+
+	virtual void call(const Variant **p_arguments, int p_argcount, Variant &r_return_value, Callable::CallError &r_call_error) const override {
+		semaphore->post();
+		if (p_argcount == 1) { // If passed one argument, will be returned.
+			if (return_value) {
+				*return_value = *p_arguments[0];
+			}
+		} else if (p_argcount > 1) {
+			r_call_error.error = Callable::CallError::CALL_ERROR_TOO_MANY_ARGUMENTS;
+			r_call_error.argument = p_argcount;
+			r_call_error.expected = 1;
+			return;
+		}
+
+		r_call_error.error = Callable::CallError::CALL_OK;
+	}
+
+	CallableCustomSuspend(Semaphore *p_semaphore, Variant *r_return_value) {
+		semaphore = p_semaphore;
+		return_value = r_return_value;
+	}
+};
+
+Variant Thread::suspend(Signal p_resume_signal, bool p_connect_on_main_thread) {
+	Semaphore semaphore;
+	Variant return_value;
+
+	Callable callable(memnew(CallableCustomSuspend(&semaphore, &return_value)));
+	if (p_connect_on_main_thread) {
+		ObjectID obj_id = p_resume_signal.get_object_id();
+		MessageQueue::get_singleton()->push_call(obj_id, SNAME("connect"), p_resume_signal.get_name(), callable, CONNECT_ONE_SHOT);
+	} else {
+		p_resume_signal.connect(callable, Object::CONNECT_ONE_SHOT);
+	}
+
+	semaphore.wait();
+
+	return return_value;
+}
+
 void Thread::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("start", "callable", "priority"), &Thread::start, DEFVAL(PRIORITY_NORMAL));
 	ClassDB::bind_method(D_METHOD("get_id"), &Thread::get_id);
@@ -1413,6 +1498,8 @@ void Thread::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("wait_to_finish"), &Thread::wait_to_finish);
 
 	ClassDB::bind_static_method("Thread", D_METHOD("set_thread_safety_checks_enabled", "enabled"), &Thread::set_thread_safety_checks_enabled);
+	ClassDB::bind_static_method("Thread", D_METHOD("is_main_thread"), &Thread::is_main_thread);
+	ClassDB::bind_static_method("Thread", D_METHOD("suspend", "resume_signal", "connect_on_main_thread"), &Thread::suspend, DEFVAL(true));
 
 	BIND_ENUM_CONSTANT(PRIORITY_LOW);
 	BIND_ENUM_CONSTANT(PRIORITY_NORMAL);

core/core_bind.h

@@ -453,6 +453,8 @@ class Thread : public RefCounted {
 	bool is_started() const;
 	bool is_alive() const;
 	Variant wait_to_finish();
+	static bool is_main_thread();
+	static Variant suspend(Signal p_resume_signal, bool p_connect_on_main_thread = true);
 
 	static void set_thread_safety_checks_enabled(bool p_enabled);
 };

doc/classes/ProjectSettings.xml

@@ -3211,6 +3211,8 @@
 			- 8×8 = rgb(255, 255, 0) - #ffff00 - Not supported on most hardware
 			[/codeblock]
 		</member>
+		<member name="threading/warnings/warn_on_cross_thread_await" type="bool" setter="" getter="" default="true">
+		</member>
 		<member name="threading/worker_pool/low_priority_thread_ratio" type="float" setter="" getter="" default="0.3">
 			The ratio of [WorkerThreadPool]'s threads that will be reserved for low-priority tasks. For example, if 10 threads are available and this value is set to [code]0.3[/code], 3 of the worker threads will be reserved for low-priority tasks. The actual value won't exceed the number of CPU cores minus one, and if possible, at least one worker thread will be dedicated to low-priority tasks.
 		</member>

doc/classes/Thread.xml

@@ -30,6 +30,12 @@
 				To check if a [Thread] is joinable, use [method is_started].
 			</description>
 		</method>
+		<method name="is_main_thread" qualifiers="static">
+			<return type="bool" />
+			<description>
+				Returns [code]true[/code] if the function is called from the main thread of the engine. This is the thread that runs game code by default.
+			</description>
+		</method>
 		<method name="is_started" qualifiers="const">
 			<return type="bool" />
 			<description>
@@ -60,6 +66,14 @@
 				Returns [constant OK] on success, or [constant ERR_CANT_CREATE] on failure.
 			</description>
 		</method>
+		<method name="suspend" qualifiers="static">
+			<return type="Variant" />
+			<param index="0" name="resume_signal" type="Signal" />
+			<param index="1" name="connect_on_main_thread" type="bool" default="true" />
+			<description>
+				Suspend a thread until the signal provided in the [param resume_signal] argument is emitted. As connecting signals between threads is often discouraged (or blocked by thread guards), the [param connect_on_main_thread] is provided to perform the connection to the signal on the main thread. As a note, if you intend to await on a script function instead of a signal, use the following syntax instead: [code] Thread.suspend( function().completed ) [/code].
+			</description>
+		</method>
 		<method name="wait_to_finish">
 			<return type="Variant" />
 			<description>

modules/gdscript/gdscript_function.cpp

@@ -187,7 +187,18 @@ bool GDScriptFunctionState::is_valid(bool p_extended_check) const {
 	return true;
 }
 
+bool GDScriptFunctionState::warn_on_cross_thread_await = true;
+
+void GDScriptFunctionState::set_warn_on_cross_thread_await(bool p_enable) {
+	warn_on_cross_thread_await = p_enable;
+}
+
 Variant GDScriptFunctionState::resume(const Variant &p_arg) {
+#ifdef DEBUG_ENABLED
+	if (warn_on_cross_thread_await && await_id != Thread::get_caller_id()) {
+		WARN_PRINT("Function " + function->get_name() + " was resumed on a different thread than it was awaited. If you really intend to do this, Use Thread.suspend() for cross thread suspension or disable the 'warn_on_cross_thread_await' warning on project settings.");
+	}
+#endif
 	ERR_FAIL_NULL_V(function, Variant());
 	{
 		MutexLock lock(GDScriptLanguage::singleton->mutex);

modules/gdscript/gdscript_function.h

@@ -608,10 +608,15 @@ class GDScriptFunctionState : public RefCounted {
 	SelfList<GDScriptFunctionState> scripts_list;
 	SelfList<GDScriptFunctionState> instances_list;
 
+	static bool warn_on_cross_thread_await;
+	Thread::ID await_id = Thread::UNASSIGNED_ID;
+
 protected:
 	static void _bind_methods();
 
 public:
+	static void set_warn_on_cross_thread_await(bool p_enable);
+
 	bool is_valid(bool p_extended_check = false) const;
 	Variant resume(const Variant &p_arg = Variant());
 

modules/gdscript/gdscript_vm.cpp

@@ -2542,6 +2542,8 @@ Variant GDScriptFunction::call(GDScriptInstance *p_instance, const Variant **p_a
 					gdfs->state.ip = ip + 2;
 					gdfs->state.line = line;
 					gdfs->state.script = _script;
+					gdfs->await_id = Thread::get_caller_id();
+
 					{
 						MutexLock lock(GDScriptLanguage::get_singleton()->mutex);
 						_script->pending_func_states.add(&gdfs->scripts_list);

modules/gdscript/register_types.cpp

@@ -49,6 +49,7 @@
 #include "tests/test_gdscript.h"
 #endif
 
+#include "core/config/project_settings.h"
 #include "core/io/file_access.h"
 #include "core/io/resource_loader.h"
 
@@ -153,6 +154,8 @@ void initialize_gdscript_module(ModuleInitializationLevel p_level) {
 		gdscript_cache = memnew(GDScriptCache);
 
 		GDScriptUtilityFunctions::register_functions();
+
+		GDScriptFunctionState::set_warn_on_cross_thread_await(GLOBAL_DEF("threading/warnings/warn_on_cross_thread_await", true));
 	}
 
 #ifdef TOOLS_ENABLED