[Gradle][Minor] Add Property.awaitFinalValueOrThrow util function

KT-60159

libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/KotlinPluginLifecycle.kt

@@ -190,6 +190,16 @@ internal suspend fun <T : Any> Property<T>.awaitFinalValue(): T? {
     return orNull
 }
 
+/**
+ * Will suspend until [Stage.FinaliseDsl], finalise the value using [Property.finalizeValue] and return the
+ * final value or throw if value wasn't set.
+ */
+internal suspend fun <T : Any> Property<T>.awaitFinalValueOrThrow(): T {
+    Stage.AfterFinaliseDsl.await()
+    finalizeValue()
+    return orNull ?: throw IllegalLifecycleException("Property has no value available: ${currentKotlinPluginLifecycle()}")
+}
+
 /**
  * See also [withRestrictedStages]
  *

libraries/tools/kotlin-gradle-plugin/src/functionalTest/kotlin/org/jetbrains/kotlin/gradle/unitTests/LifecycleAwaitFinalPropertyValueTest.kt

@@ -8,11 +8,8 @@
 package org.jetbrains.kotlin.gradle.unitTests
 
 import org.jetbrains.kotlin.gradle.plugin.*
-import org.jetbrains.kotlin.gradle.plugin.KotlinPluginLifecycle
+import org.jetbrains.kotlin.gradle.plugin.KotlinPluginLifecycle.IllegalLifecycleException
 import org.jetbrains.kotlin.gradle.plugin.KotlinPluginLifecycle.Stage.*
-import org.jetbrains.kotlin.gradle.plugin.awaitFinalValue
-import org.jetbrains.kotlin.gradle.plugin.currentKotlinPluginLifecycle
-import org.jetbrains.kotlin.gradle.plugin.launchInStage
 import org.jetbrains.kotlin.gradle.util.buildProjectWithMPP
 import org.jetbrains.kotlin.gradle.util.runLifecycleAwareTest
 import org.jetbrains.kotlin.gradle.utils.newProperty
@@ -57,6 +54,43 @@ class LifecycleAwaitFinalPropertyValueTest {
         }
     }
 
+    @Test
+    fun `test - getting value is an idempotent operation`() = project.runLifecycleAwareTest {
+        val property = project.newProperty<Int>()
+        property.set(1)
+
+        launch {
+            assertEquals(1, property.awaitFinalValue())
+            assertEquals(1, property.awaitFinalValue())
+        }
+    }
+
+    @Test
+    fun `test - awaitFinalValueOrThrow - throws when no value set`() = project.runLifecycleAwareTest {
+        val property = project.newProperty<Int>()
+        launch {
+            assertFailsWith<IllegalLifecycleException> { property.awaitFinalValueOrThrow() }
+        }
+    }
+
+    @Test
+    fun `test - awaitFinalValueOrThrow - returns when convention value is set`() = project.runLifecycleAwareTest {
+        val property = project.newProperty<Int>()
+        property.convention(1)
+        launch {
+            assertEquals(1, property.awaitFinalValueOrThrow())
+        }
+    }
+
+    @Test
+    fun `test - awaitFinalValueOrThrow - returns when value is set`() = project.runLifecycleAwareTest {
+        val property = project.newProperty<Int>()
+        property.set(1)
+        launch {
+            assertEquals(1, property.awaitFinalValueOrThrow())
+        }
+    }
+
     @Test
     fun `test - creating a property - after finaliseDsl stage already passed`() = project.runLifecycleAwareTest {
         launchInStage(KotlinPluginLifecycle.Stage.last) {