Merge pull request #122 from arkivanov/lifecycle-owner-repeat-on-life…

…cycle Added LifecycleOwner.repeatOnLifecycle
arkivanov · Nov 18, 2023 · 5c1dde9 · 5c1dde9
2 parents 244119f + 20a0ff4
commit 5c1dde9
Show file tree

Hide file tree

Showing 4 changed files with 28 additions and 5 deletions.
diff --git a/lifecycle-coroutines/api/android/lifecycle-coroutines.api b/lifecycle-coroutines/api/android/lifecycle-coroutines.api
@@ -7,6 +7,8 @@ public final class com/arkivanov/essenty/lifecycle/coroutines/FlowWithLifecycleK
 
 public final class com/arkivanov/essenty/lifecycle/coroutines/RepeatOnLifecycleKt {
 	public static final fun repeatOnLifecycle (Lcom/arkivanov/essenty/lifecycle/Lifecycle;Lcom/arkivanov/essenty/lifecycle/Lifecycle$State;Lkotlin/coroutines/CoroutineContext;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static final fun repeatOnLifecycle (Lcom/arkivanov/essenty/lifecycle/LifecycleOwner;Lcom/arkivanov/essenty/lifecycle/Lifecycle$State;Lkotlin/coroutines/CoroutineContext;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static synthetic fun repeatOnLifecycle$default (Lcom/arkivanov/essenty/lifecycle/Lifecycle;Lcom/arkivanov/essenty/lifecycle/Lifecycle$State;Lkotlin/coroutines/CoroutineContext;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
+	public static synthetic fun repeatOnLifecycle$default (Lcom/arkivanov/essenty/lifecycle/LifecycleOwner;Lcom/arkivanov/essenty/lifecycle/Lifecycle$State;Lkotlin/coroutines/CoroutineContext;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
 }
 
diff --git a/lifecycle-coroutines/api/jvm/lifecycle-coroutines.api b/lifecycle-coroutines/api/jvm/lifecycle-coroutines.api
@@ -7,6 +7,8 @@ public final class com/arkivanov/essenty/lifecycle/coroutines/FlowWithLifecycleK
 
 public final class com/arkivanov/essenty/lifecycle/coroutines/RepeatOnLifecycleKt {
 	public static final fun repeatOnLifecycle (Lcom/arkivanov/essenty/lifecycle/Lifecycle;Lcom/arkivanov/essenty/lifecycle/Lifecycle$State;Lkotlin/coroutines/CoroutineContext;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public static final fun repeatOnLifecycle (Lcom/arkivanov/essenty/lifecycle/LifecycleOwner;Lcom/arkivanov/essenty/lifecycle/Lifecycle$State;Lkotlin/coroutines/CoroutineContext;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public static synthetic fun repeatOnLifecycle$default (Lcom/arkivanov/essenty/lifecycle/Lifecycle;Lcom/arkivanov/essenty/lifecycle/Lifecycle$State;Lkotlin/coroutines/CoroutineContext;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
+	public static synthetic fun repeatOnLifecycle$default (Lcom/arkivanov/essenty/lifecycle/LifecycleOwner;Lcom/arkivanov/essenty/lifecycle/Lifecycle$State;Lkotlin/coroutines/CoroutineContext;Lkotlin/jvm/functions/Function2;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
 }
 
diff --git a/...nes/src/commonMain/kotlin/com/arkivanov/essenty/lifecycle/coroutines/FlowWithLifecycle.kt b/...nes/src/commonMain/kotlin/com/arkivanov/essenty/lifecycle/coroutines/FlowWithLifecycle.kt
@@ -7,8 +7,12 @@ import kotlinx.coroutines.flow.callbackFlow
 import kotlin.coroutines.CoroutineContext
 
 /**
- * Start [Flow] collecting when [Lifecycle.State] is at least as [minActiveState].
- * It stopped collecting if "opposite" [Lifecycle.State] will appear.
+ * [Flow] operator that emits values from this upstream [Flow] when the [lifecycle]
+ * is at least at [minActiveState] state. The emissions will be stopped when the
+ * [lifecycle] state falls below [minActiveState] state.
+ *
+ * See the [AndroidX documentation](https://developer.android.com/reference/kotlin/androidx/lifecycle/package-summary#(kotlinx.coroutines.flow.Flow).flowWithLifecycle(androidx.lifecycle.Lifecycle,androidx.lifecycle.Lifecycle.State))
+ * for more information.
  */
 fun <T> Flow<T>.withLifecycle(
     lifecycle: Lifecycle,

diff --git a/...nes/src/commonMain/kotlin/com/arkivanov/essenty/lifecycle/coroutines/RepeatOnLifecycle.kt b/...nes/src/commonMain/kotlin/com/arkivanov/essenty/lifecycle/coroutines/RepeatOnLifecycle.kt
@@ -1,6 +1,7 @@
 package com.arkivanov.essenty.lifecycle.coroutines
 
 import com.arkivanov.essenty.lifecycle.Lifecycle
+import com.arkivanov.essenty.lifecycle.LifecycleOwner
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
@@ -14,10 +15,24 @@ import kotlin.coroutines.CoroutineContext
 import kotlin.coroutines.resume
 
 /**
- * Repeat invocation [block] every time that passed [minActiveState] appears.
- * Work of passed [block] finished when "opposite" [Lifecycle.State] will appear.
+ * Convenience method for [Lifecycle.repeatOnLifecycle].
+ */
+suspend fun LifecycleOwner.repeatOnLifecycle(
+    minActiveState: Lifecycle.State = Lifecycle.State.STARTED,
+    context: CoroutineContext = Dispatchers.Main,
+    block: suspend CoroutineScope.() -> Unit,
+) {
+    lifecycle.repeatOnLifecycle(minActiveState = minActiveState, context = context, block = block)
+}
+
+/**
+ * Runs the given [block] in a new coroutine when this [Lifecycle] is at least at [minActiveState] and suspends
+ * the execution until this [Lifecycle] is [Lifecycle.State.DESTROYED].
+ *
+ * The [block] will cancel and re-launch as the [Lifecycle] moves in and out of the [minActiveState].
  *
- * Note: This function works like a terminal operator and must be called in assembly coroutine.
+ * See the [AndroidX documentation](https://developer.android.com/reference/kotlin/androidx/lifecycle/package-summary#(androidx.lifecycle.Lifecycle).repeatOnLifecycle(androidx.lifecycle.Lifecycle.State,kotlin.coroutines.SuspendFunction1))
+ * for more information.
  */
 suspend fun Lifecycle.repeatOnLifecycle(
     minActiveState: Lifecycle.State = Lifecycle.State.STARTED,