Add some coroutines utility functions (#704)

* Add awaitDeferred

* Fix signal param name

* Implement async load

* Add an early return in case the resource is already loaded

* Improve early return

Author: chippmann

harness/tests/scripts/godot/tests/Invocation.gdj

@@ -13,10 +13,7 @@ supertypes = [
 	kotlin.Any
 ]
 signals = [
-    no_param,
-	one_param,
-	two_param,
-	signal_with_multiple_targets
+    
 ]
 properties = [
     button,
@@ -71,13 +68,10 @@ properties = [
 	stringtemplation,
 	test_string,
 	ascii_string,
-	utf8_string,
-	array
+	utf8_string
 ]
 functions = [
-    target_function_one,
-	target_function_two,
-	int_value,
+    int_value,
 	long_value,
 	float_value,
 	double_value,

harness/tests/scripts/godot/tests/coroutine/CoroutineTest.gdj

@@ -12,14 +12,19 @@ supertypes = [
 ]
 signals = [
     signal_without_parameter,
-	signal_with_parameters,
-	signal_with_many_parameters
+	signal_with_one_parameter,
+	signal_with_many_parameters,
+	run_on_main_thread_from_background_thread_finished,
+	async_load_resource_finished
 ]
 properties = [
     step
 ]
 functions = [
     start_coroutine_without_parameter,
-	start_coroutine_with_parameters,
-	start_coroutine_with_many_parameters
+	start_coroutine_with_one_parameter,
+	start_coroutine_with_many_parameters,
+	start_coroutine_undispatched,
+	run_on_main_thread_from_background_thread,
+	async_load_resource
 ]

harness/tests/scripts/godot/tests/signal/SignalTest.gdj

@@ -0,0 +1,31 @@
+// THIS FILE IS GENERATED! DO NOT EDIT OR DELETE IT. EDIT OR DELETE THE ASSOCIATED SOURCE CODE FILE INSTEAD
+// Note: You can however freely move this file inside your godot project if you want. Keep in mind however, that if you rename the originating source code file, this file will be deleted and regenerated as a new file instead of being updated! Other modifications to the source file however, will result in this file being updated.
+
+registeredName = SignalTest
+fqName = godot.tests.signal.SignalTest
+relativeSourcePath = src/main/kotlin/godot/tests/signal/SignalTest.kt
+baseType = Node
+supertypes = [
+    godot.Node,
+	godot.Object,
+	godot.core.KtObject,
+	kotlin.Any
+]
+signals = [
+    no_param_signal_delegate,
+	one_param_signal_delegate,
+	two_param_signal_delegate,
+	no_param_signal_field,
+	one_param_signal_field,
+	two_param_signal_field,
+	signal_with_multiple_targets
+]
+properties = [
+    other_script,
+	array
+]
+functions = [
+    _ready,
+	target_function_one,
+	target_function_two
+]

harness/tests/src/main/kotlin/godot/tests/coroutine/CoroutineTest.kt

@@ -2,6 +2,8 @@ package godot.tests.coroutine
 
 
 import godot.Object
+import godot.PackedScene
+import godot.ResourceLoader
 import godot.annotation.RegisterClass
 import godot.annotation.RegisterFunction
 import godot.annotation.RegisterProperty
@@ -12,6 +14,9 @@ import godot.core.signal1
 import godot.core.signal4
 import godot.coroutines.GodotCoroutine
 import godot.coroutines.await
+import godot.coroutines.awaitDeferred
+import godot.coroutines.awaitLoadAs
+import godot.global.GD
 import kotlinx.coroutines.CoroutineStart
 
 @RegisterClass
@@ -55,4 +60,52 @@ class CoroutineTest : Object() {
         signalWithoutParameter.await()
         step = 8
     }
+
+    @RegisterSignal
+    val runOnMainThreadFromBackgroundThreadFinished by signal1<Boolean>("is_test_successful")
+
+    @RegisterFunction
+    fun runOnMainThreadFromBackgroundThread() {
+        val thread = Thread.currentThread().name
+
+        GodotCoroutine {
+            val bgThread = Thread.currentThread().name
+
+            var fgThread = ""
+            awaitDeferred {
+                fgThread = Thread.currentThread().name
+            }
+
+            val bg2Thread = Thread.currentThread().name
+
+            GD.print("Thread names: ${listOf(thread, bgThread, fgThread, bg2Thread).joinToString()}")
+
+            awaitDeferred {
+                runOnMainThreadFromBackgroundThreadFinished.emit(
+                    thread != bgThread
+                        && thread != bg2Thread
+                        && bgThread != fgThread
+                        && thread == fgThread // check that the code is run on the main thread
+                )
+            }
+        }
+    }
+
+    @RegisterSignal
+    val asyncLoadResourceFinished by signal1<Boolean>("is_test_successful")
+
+    @RegisterFunction
+    fun asyncLoadResource() {
+        GodotCoroutine {
+            val resource = ResourceLoader.awaitLoadAs<PackedScene>("res://Spatial.tscn") { progress ->
+                GD.print("Resource load progress: $progress")
+            }
+
+            GD.print("Resource: $resource")
+
+            awaitDeferred {
+                asyncLoadResourceFinished.emit(resource != null)
+            }
+        }
+    }
 }

harness/tests/test/unit/test_coroutines.gd

@@ -15,15 +15,15 @@ func test_coroutine_await():
     assert_eq(test_script.step, 2, "Property should be 2 after coroutine ran and signal triggered.")
 
     test_script.start_coroutine_with_one_parameter()
-        await get_tree().create_timer(1).timeout
+    await get_tree().create_timer(1).timeout
     assert_eq(test_script.step, 3, "Property should be 3 after coroutine started but waiting.")
 
     test_script.signal_with_one_parameter.emit(4)
     await get_tree().create_timer(1).timeout
     assert_eq(test_script.step, 4, "Property should be 4 after coroutine ran.")
 
     test_script.start_coroutine_with_many_parameters()
-        await get_tree().create_timer(1).timeout
+    await get_tree().create_timer(1).timeout
     assert_eq(test_script.step, 5, "Property should be 5 after coroutine started but waiting.")
 
     test_script.signal_with_many_parameters.emit(6, 0.1, Vector2(0,0), "test")
@@ -34,4 +34,15 @@ func test_coroutine_await():
     assert_eq(test_script.step, 7, "Property should be immediately 7 when coroutine is undispatched.")
 
     test_script.signal_without_parameter.emit()
-    assert_eq(test_script.step, 8, "Property should be immediately 7 when coroutine is undispatched.")
+    await get_tree().create_timer(1).timeout
+    assert_eq(test_script.step, 8, "Property should be 8 when coroutine is resumed.")
+
+    test_script.run_on_main_thread_from_background_thread()
+    var run_on_main_thread_from_background_thread_success = await test_script.run_on_main_thread_from_background_thread_finished
+    assert_true(run_on_main_thread_from_background_thread_success, "Code should be executed on the correct threads")
+
+    test_script.async_load_resource()
+    var async_load_resource_success = await test_script.async_load_resource_finished
+    assert_true(async_load_resource_success, "Resource should be loaded")
+
+    test_script.free()

kt/godot-coroutine-library/src/main/kotlin/godot/coroutines/awaitDeferred.kt

@@ -0,0 +1,28 @@
+package godot.coroutines
+
+import godot.core.Callable
+import godot.core.asCallable
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlin.coroutines.resume
+
+
+/**
+ * Suspends the current coroutine until the given block is executed.
+ *
+ * The block will be executed at the end of the frame on the main thread.
+ *
+ * Use it to call not thread safe code from godot and wait for the execution of it.
+ *
+ * @param block the code block to execute at the end of the frame
+ */
+public suspend inline fun <R> awaitDeferred(
+    crossinline block: () -> R
+): R = suspendCancellableCoroutine { continuation ->
+    Callable(
+        {
+            if (continuation.isActive) {
+                continuation.resume(block())
+            }
+        }.asCallable()
+    ).callDeferred()
+}

kt/godot-coroutine-library/src/main/kotlin/godot/coroutines/awaitResourceLoad.kt

@@ -0,0 +1,106 @@
+package godot.coroutines
+
+import godot.Error
+import godot.Resource
+import godot.ResourceLoader
+import godot.ResourceLoader.CacheMode
+import godot.core.variantArrayOf
+import godot.global.GD
+import godot.util.RealT
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+
+
+/**
+ * Suspends the coroutine until a resource is loaded from the given path.
+ *
+ * @param path The path of the resource to be loaded.
+ * @param typeHint A hint about the type of resource being loaded.
+ * @param useSubThreads Specifies whether to use sub-threads for loading the resource.
+ * @param cacheMode The cache mode to be used while loading the resource.
+ * @param onProgress A callback function to track the progress of resource loading.
+ * @return The loaded resource, or null if there was an error.
+ */
+public suspend inline fun ResourceLoader.awaitLoad(
+    path: String,
+    typeHint: String = "",
+    useSubThreads: Boolean = false,
+    cacheMode: CacheMode = ResourceLoader.CacheMode.CACHE_MODE_REUSE,
+    crossinline onProgress: (RealT) -> Unit = {},
+): Resource? {
+    // early return in case the resource is already loaded
+    if (this.hasCached(path)) {
+        return this.load(path)
+    }
+
+    val error = this.loadThreadedRequest(
+        path = path,
+        typeHint = typeHint,
+        useSubThreads = useSubThreads,
+        cacheMode = cacheMode,
+    )
+
+    if (error != Error.OK) {
+        GD.printErr("Could not trigger resource load. Got error: $error")
+        return null
+    }
+
+    return suspendCancellableCoroutine { continuation ->
+        CoroutineScope(Dispatchers.Default).launch {
+            var success = false
+            do {
+                val progress = variantArrayOf<Any?>()
+
+                val status = awaitDeferred {
+                    this@awaitLoad.loadThreadedGetStatus(
+                        path = path,
+                        progress = progress,
+                    ).also {
+                        (progress.firstOrNull() as? RealT)?.let { onProgress(it) }
+                    }
+                }
+
+                when (status) {
+                    ResourceLoader.ThreadLoadStatus.THREAD_LOAD_LOADED -> success = true
+                    ResourceLoader.ThreadLoadStatus.THREAD_LOAD_IN_PROGRESS -> {
+                        // no op
+                    }
+
+                    ResourceLoader.ThreadLoadStatus.THREAD_LOAD_INVALID_RESOURCE,
+                    ResourceLoader.ThreadLoadStatus.THREAD_LOAD_FAILED -> continuation.resumeWithException(
+                        IllegalStateException("Failed to load resource: $status")
+                    )
+                }
+            } while (status == ResourceLoader.ThreadLoadStatus.THREAD_LOAD_IN_PROGRESS)
+
+            if (success) {
+                continuation.resume(this@awaitLoad.loadThreadedGet(path))
+            }
+        }
+    }
+}
+
+/**
+ * Suspends the coroutine until a resource is loaded from the given path.
+ *
+ * @param path The path of the resource to be loaded.
+ * @param typeHint A hint about the type of resource being loaded.
+ * @param useSubThreads Specifies whether to use sub-threads for loading the resource.
+ * @param cacheMode The cache mode to be used while loading the resource.
+ * @param onProgress A callback function to track the progress of resource loading.
+ * @return The loaded resource, or null if there was an error.
+ */
+public suspend inline fun <R> ResourceLoader.awaitLoadAs(
+    path: String,
+    typeHint: String = "",
+    useSubThreads: Boolean = false,
+    cacheMode: CacheMode = ResourceLoader.CacheMode.CACHE_MODE_REUSE,
+    crossinline onProgress: (RealT) -> Unit = {},
+): R? {
+    @Suppress("UNCHECKED_CAST")
+    return this.awaitLoad(path, typeHint, useSubThreads, cacheMode, onProgress) as? R
+}