RepeatOnLifecycleKt

Added in 2.4.0

public final class RepeatOnLifecycleKt

Summary

Public methods
static final void
repeatOnLifecycle(
    @NonNull Lifecycle receiver,
    @NonNull Lifecycle.State state,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull CoroutineScope, Unit> block
)

Runs the given block in a new coroutine when this Lifecycle is at least at state and suspends the execution until this Lifecycle is Lifecycle.State.DESTROYED.
static final void
repeatOnLifecycle(
    @NonNull LifecycleOwner receiver,
    @NonNull Lifecycle.State state,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull CoroutineScope, Unit> block
)

LifecycleOwner's extension function for Lifecycle.repeatOnLifecycle to allow an easier call to the API from LifecycleOwners such as Activities and Fragments.

Public methods

repeatOnLifecycle

public static final void repeatOnLifecycle(
    @NonNull Lifecycle receiver,
    @NonNull Lifecycle.State state,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull CoroutineScope, Unit> block
)

Runs the given block in a new coroutine when this Lifecycle is at least at state 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 target state.

class MyActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        /* ... */
            // Runs the block of code in a coroutine when the lifecycle is at least STARTED.
            // The coroutine will be cancelled when the ON_STOP event happens and will
            // restart executing if the lifecycle receives the ON_START event again.
            lifecycleScope.launch {
                lifecycle.repeatOnLifecycle(Lifecycle.State.STARTED) {
                    uiStateFlow.collect { uiState ->
                        updateUi(uiState)
                    }
                }
            }
        }
    }

The best practice is to call this function when the lifecycle is initialized. For example, onCreate in an Activity, or onViewCreated in a Fragment. Otherwise, multiple repeating coroutines doing the same could be created and be executed at the same time.

Repeated invocations of block will run serially, that is they will always wait for the previous invocation to fully finish before re-starting execution as the state moves in and out of the required state.

Warning: Lifecycle.State.INITIALIZED is not allowed in this API. Passing it as a parameter will throw an IllegalArgumentException.

Parameters
@NonNull Lifecycle.State state

Lifecycle.State in which block runs in a new coroutine. That coroutine will cancel if the lifecycle falls below that state, and will restart if it's in that state again.
@ExtensionFunctionType @NonNull SuspendFunction1<@NonNull CoroutineScope, Unit> block

The block to run when the lifecycle is at least in state state.

repeatOnLifecycle

public static final void repeatOnLifecycle(
    @NonNull LifecycleOwner receiver,
    @NonNull Lifecycle.State state,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull CoroutineScope, Unit> block
)

LifecycleOwner's extension function for Lifecycle.repeatOnLifecycle to allow an easier call to the API from LifecycleOwners such as Activities and Fragments.

class MyActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        /* ... */
            // Runs the block of code in a coroutine when the lifecycle is at least STARTED.
            // The coroutine will be cancelled when the ON_STOP event happens and will
            // restart executing if the lifecycle receives the ON_START event again.
            lifecycleScope.launch {
                repeatOnLifecycle(Lifecycle.State.STARTED) {
                    uiStateFlow.collect { uiState ->
                        updateUi(uiState)
                    }
                }
            }
        }
    }
See also
repeatOnLifecycle