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();
@@ -1413,6 +1417,7 @@ 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);
 
 	BIND_ENUM_CONSTANT(PRIORITY_LOW);
 	BIND_ENUM_CONSTANT(PRIORITY_NORMAL);

core/core_bind.h

@@ -453,6 +453,7 @@ class Thread : public RefCounted {
 	bool is_started() const;
 	bool is_alive() const;
 	Variant wait_to_finish();
+	static bool is_main_thread();
 
 	static void set_thread_safety_checks_enabled(bool p_enabled);
 };

core/variant/variant_utility.cpp

@@ -33,6 +33,7 @@
 #include "core/io/marshalls.h"
 #include "core/object/ref_counted.h"
 #include "core/os/os.h"
+#include "core/os/semaphore.h"
 #include "core/templates/oa_hash_map.h"
 #include "core/templates/rid.h"
 #include "core/templates/rid_owner.h"
@@ -1234,6 +1235,81 @@ bool VariantUtilityFunctions::is_same(const Variant &p_a, const Variant &p_b) {
 	return p_a.identity_compare(p_b);
 }
 
+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 VariantUtilityFunctions::thread_suspend(Signal p_resume) {
+	Semaphore semaphore;
+	Variant return_value;
+
+	p_resume.connect(Callable(memnew(CallableCustomSuspend(&semaphore, &return_value))), Object::CONNECT_ONE_SHOT);
+
+	semaphore.wait();
+
+	return return_value;
+}
+
 #ifdef DEBUG_METHODS_ENABLED
 #define VCALLR *ret = p_func(VariantCasterAndValidate<P>::cast(p_args, Is, r_error)...)
 #define VCALL p_func(VariantCasterAndValidate<P>::cast(p_args, Is, r_error)...)
@@ -1855,6 +1931,8 @@ void Variant::_register_variant_utility_functions() {
 	FUNCBINDR(rid_from_int64, sarray("base"), Variant::UTILITY_FUNC_TYPE_GENERAL);
 
 	FUNCBINDR(is_same, sarray("a", "b"), Variant::UTILITY_FUNC_TYPE_GENERAL);
+
+	FUNCBINDR(thread_suspend, sarray("on_signal"), Variant::UTILITY_FUNC_TYPE_GENERAL);
 }
 
 void Variant::_unregister_variant_utility_functions() {

core/variant/variant_utility.h

@@ -152,4 +152,5 @@ struct VariantUtilityFunctions {
 	static uint64_t rid_allocate_id();
 	static RID rid_from_int64(uint64_t p_base);
 	static bool is_same(const Variant &p_a, const Variant &p_b);
+	static Variant thread_suspend(Signal p_resume);
 };

doc/classes/@GlobalScope.xml

@@ -1390,6 +1390,13 @@
 				[/codeblock]
 			</description>
 		</method>
+		<method name="thread_suspend">
+			<return type="Variant" />
+			<param index="0" name="on_signal" type="Signal" />
+			<description>
+				Suspend the caller thread until the signal passed as argument is emitted.
+			</description>
+		</method>
 		<method name="type_convert">
 			<return type="Variant" />
 			<param index="0" name="variant" type="Variant" />

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>