androidx.lifecycle

fun <T : Any?> liveData(
    context: CoroutineContext = EmptyCoroutineContext,
    timeoutInMs: Long = DEFAULT_TIMEOUT,
    block: suspend LiveDataScope<T>.() -> Unit
): LiveData<T>

Builds a LiveData that has values yielded from the given block that executes on a LiveDataScope.

The block starts executing when the returned LiveData becomes active. If the LiveData becomes inactive while the block is executing, it will be cancelled after timeoutInMs milliseconds unless the LiveData becomes active again before that timeout (to gracefully handle cases like Activity rotation). Any value LiveDataScope.emited from a cancelled block will be ignored.

After a cancellation, if the LiveData becomes active again, the block will be re-executed from the beginning. If you would like to continue the operations based on where it was stopped last, you can use the LiveDataScope.latestValue function to get the last LiveDataScope.emited value.

If the block completes successfully or is cancelled due to reasons other than LiveData becoming inactive, it will not be re-executed even after LiveData goes through active inactive cycle.

As a best practice, it is important for the block to cooperate in cancellation. See kotlin coroutines documentation for details https://kotlinlang.org/docs/reference/coroutines/cancellation-and-timeouts.html.

The timeoutInMs can be changed to fit different use cases better, for example increasing it will give more time to the block to complete even if LiveData is inactive. It is good for cases when block is finite (meaning it can complete successfully) and is costly to restart. Otherwise if a block is cheap to restart, decreasing the timeoutInMs value will allow to yield less values that aren't consumed by anything.

// a simple LiveData that receives value 3, 3 seconds after being observed for the first time.
val data : LiveData<Int> = liveData {
    delay(3000)
    emit(3)
}


// a LiveData that fetches a `User` object based on a `userId` and refreshes it every 30 seconds
// as long as it is observed
val userId : LiveData<String> = ...
val user = userId.switchMap { id ->
    liveData {
      while(true) {
        // note that `while(true)` is fine because the `delay(30_000)` below will cooperate in
        // cancellation if LiveData is not actively observed anymore
        val data = api.fetch(id) // errors are ignored for brevity
        emit(data)
        delay(30_000)
      }
    }
}

// A retrying data fetcher with doubling back-off
val user = liveData {
    var backOffTime = 1_000
    var succeeded = false
    while(!succeeded) {
        try {
            emit(api.fetch(id))
            succeeded = true
        } catch(ioError : IOException) {
            delay(backOffTime)
            backOffTime *= minOf(backOffTime * 2, 60_000)
        }
    }
}

// a LiveData that tries to load the `User` from local cache first and then tries to fetch
// from the server and also yields the updated value
val user = liveData {
    // dispatch loading first
    emit(LOADING(id))
    // check local storage
    val cached = cache.loadUser(id)
    if (cached != null) {
        emit(cached)
    }
    if (cached == null || cached.isStale()) {
        val fresh = api.fetch(id) // errors are ignored for brevity
        cache.save(fresh)
        emit(fresh)
    }
}

// a LiveData that immediately receives a LiveData<User> from the database and yields it as a
// source but also tries to back-fill the database from the server
val user = liveData {
    val fromDb: LiveData<User> = roomDatabase.loadUser(id)
    emitSource(fromDb)
    val updated = api.fetch(id) // errors are ignored for brevity
    // Since we are using Room here, updating the database will update the `fromDb` LiveData
    // that was obtained above. See Room's documentation for more details.
    // https://developer.android.com/training/data-storage/room/accessing-data#query-observable
    roomDatabase.insert(updated)
}

@RequiresApi(value = 26)
fun <T : Any?> liveData(
    timeout: Duration,
    context: CoroutineContext = EmptyCoroutineContext,
    block: suspend LiveDataScope<T>.() -> Unit
): LiveData<T>

Builds a LiveData that has values yielded from the given block that executes on a LiveDataScope.

The block starts executing when the returned LiveData becomes active. If the LiveData becomes inactive while the block is executing, it will be cancelled after the timeout duration unless the LiveData becomes active again before that timeout (to gracefully handle cases like Activity rotation). Any value LiveDataScope.emited from a cancelled block will be ignored.

After a cancellation, if the LiveData becomes active again, the block will be re-executed from the beginning. If you would like to continue the operations based on where it was stopped last, you can use the LiveDataScope.latestValue function to get the last LiveDataScope.emited value.

If the block completes successfully or is cancelled due to reasons other than LiveData becoming inactive, it will not be re-executed even after LiveData goes through active inactive cycle.

As a best practice, it is important for the block to cooperate in cancellation. See kotlin coroutines documentation for details https://kotlinlang.org/docs/reference/coroutines/cancellation-and-timeouts.html.

The timeout can be changed to fit different use cases better, for example increasing it will give more time to the block to complete even if LiveData is inactive. It is good for cases when block is finite (meaning it can complete successfully) and is costly to restart. Otherwise if a block is cheap to restart, decreasing the timeout value will allow to yield less values that aren't consumed by anything.

// a simple LiveData that receives value 3, 3 seconds after being observed for the first time.
val data : LiveData<Int> = liveData {
    delay(3000)
    emit(3)
}


// a LiveData that fetches a `User` object based on a `userId` and refreshes it every 30 seconds
// as long as it is observed
val userId : LiveData<String> = ...
val user = userId.switchMap { id ->
    liveData {
      while(true) {
        // note that `while(true)` is fine because the `delay(30_000)` below will cooperate in
        // cancellation if LiveData is not actively observed anymore
        val data = api.fetch(id) // errors are ignored for brevity
        emit(data)
        delay(30_000)
      }
    }
}

// A retrying data fetcher with doubling back-off
val user = liveData {
    var backOffTime = 1_000
    var succeeded = false
    while(!succeeded) {
        try {
            emit(api.fetch(id))
            succeeded = true
        } catch(ioError : IOException) {
            delay(backOffTime)
            backOffTime *= minOf(backOffTime * 2, 60_000)
        }
    }
}

// a LiveData that tries to load the `User` from local cache first and then tries to fetch
// from the server and also yields the updated value
val user = liveData {
    // dispatch loading first
    emit(LOADING(id))
    // check local storage
    val cached = cache.loadUser(id)
    if (cached != null) {
        emit(cached)
    }
    if (cached == null || cached.isStale()) {
        val fresh = api.fetch(id) // errors are ignored for brevity
        cache.save(fresh)
        emit(fresh)
    }
}

// a LiveData that immediately receives a LiveData<User> from the database and yields it as a
// source but also tries to back-fill the database from the server
val user = liveData {
    val fromDb: LiveData<User> = roomDatabase.loadUser(id)
    emitSource(fromDb)
    val updated = api.fetch(id) // errors are ignored for brevity
    // Since we are using Room here, updating the database will update the `fromDb` LiveData
    // that was obtained above. See Room's documentation for more details.
    // https://developer.android.com/training/data-storage/room/accessing-data#query-observable
    roomDatabase.insert(updated)
}

fun <T : Any?> toPublisher(lifecycle: LifecycleOwner, liveData: LiveData<T>): Publisher<T>

Adapts the given LiveData stream to a ReactiveStreams Publisher.

By using a good publisher implementation such as RxJava 2.x Flowables, most consumers will be able to let the library deal with backpressure using operators and not need to worry about ever manually calling Subscription.request.

On subscription to the publisher, the observer will attach to the given LiveData. Once Subscription.request is called on the subscription object, an observer will be connected to the data stream. Calling request(Long.MAX_VALUE) is equivalent to creating an unbounded stream with no backpressure. If request with a finite count reaches 0, the observer will buffer the latest item and emit it to the subscriber when data is again requested. Any other items emitted during the time there was no backpressure requested will be dropped.

fun <T : Any?> LiveData<T>.asFlow(): Flow<T>

Creates a Flow containing values dispatched by originating LiveData: at the start a flow collector receives the latest value held by LiveData and then observes LiveData updates.

When a collection of the returned flow starts the originating LiveData becomes active. Similarly, when a collection completes LiveData becomes inactive.

BackPressure: the returned flow is conflated. There is no mechanism to suspend an emission by LiveData due to a slow collector, so collector always gets the most recent value emitted.

fun <T : Any?> Flow<T>.asLiveData(
    context: CoroutineContext = EmptyCoroutineContext,
    timeoutInMs: Long = DEFAULT_TIMEOUT
): LiveData<T>

Creates a LiveData that has values collected from the origin Flow.

If the origin Flow is a StateFlow, then the initial value will be populated to the LiveData's value field on the main thread.

The upstream flow collection starts when the returned LiveData becomes active (LiveData.onActive). If the LiveData becomes inactive (LiveData.onInactive) while the flow has not completed, the flow collection will be cancelled after timeoutInMs milliseconds unless the LiveData becomes active again before that timeout (to gracefully handle cases like Activity rotation).

After a cancellation, if the LiveData becomes active again, the upstream flow collection will be re-executed.

If the upstream flow completes successfully or is cancelled due to reasons other than LiveData becoming inactive, it will not be re-collected even after LiveData goes through active inactive cycle.

If flow completes with an exception, then exception will be delivered to the CoroutineExceptionHandler of provided context. By default EmptyCoroutineContext is used to so an exception will be delivered to main's thread UncaughtExceptionHandler. If your flow upstream is expected to throw, you can use catch operator on upstream flow to emit a helpful error object.

The timeoutInMs can be changed to fit different use cases better, for example increasing it will give more time to flow to complete before being canceled and is good for finite flows that are costly to restart. Otherwise if a flow is cheap to restart decreasing the timeoutInMs value will allow to produce less values that aren't consumed by anything.

@RequiresApi(value = 26)
fun <T : Any?> Flow<T>.asLiveData(
    timeout: Duration,
    context: CoroutineContext = EmptyCoroutineContext
): LiveData<T>

Creates a LiveData that has values collected from the origin Flow.

The upstream flow collection starts when the returned LiveData becomes active (LiveData.onActive). If the LiveData becomes inactive (LiveData.onInactive) while the flow has not completed, the flow collection will be cancelled after timeout unless the LiveData becomes active again before that timeout (to gracefully handle cases like Activity rotation).

After a cancellation, if the LiveData becomes active again, the upstream flow collection will be re-executed.

If the upstream flow completes successfully or is cancelled due to reasons other than LiveData becoming inactive, it will not be re-collected even after LiveData goes through active inactive cycle.

If flow completes with an exception, then exception will be delivered to the CoroutineExceptionHandler of provided context. By default EmptyCoroutineContext is used to so an exception will be delivered to main's thread UncaughtExceptionHandler. If your flow upstream is expected to throw, you can use catch operator on upstream flow to emit a helpful error object.

The timeout can be changed to fit different use cases better, for example increasing it will give more time to flow to complete before being canceled and is good for finite flows that are costly to restart. Otherwise if a flow is cheap to restart decreasing the timeout value will allow to produce less values that aren't consumed by anything.

@MainThread
fun CreationExtras.createSavedStateHandle(): SavedStateHandle

Creates SavedStateHandle that can be used in your ViewModels

This function requires enableSavedStateHandles call during the component initialization. Latest versions of androidx components like ComponentActivity, Fragment, NavBackStackEntry makes this call automatically.

This CreationExtras must contain SAVED_STATE_REGISTRY_OWNER_KEY, VIEW_MODEL_STORE_OWNER_KEY and VIEW_MODEL_KEY.

@MainThread
fun <X : Any?> LiveData<X>.distinctUntilChanged(): LiveData<X>

Creates a new LiveData object does not emit a value until the source this LiveData value has been changed. The value is considered changed if equals() yields false.

@MainThread
fun <T : SavedStateRegistryOwner & ViewModelStoreOwner> T.enableSavedStateHandles(

): Unit

Enables the support of SavedStateHandle in a component.

After this method, createSavedStateHandle can be called on CreationExtras containing this SavedStateRegistryOwner / ViewModelStoreOwner.

Must be called while component is in INITIALIZED or CREATED state and before a ViewModel with SavedStateHandle is requested.

fun View.findViewTreeLifecycleOwner(): LifecycleOwner?

Retrieve the LifecycleOwner responsible for managing the given View. This may be used to scope work or heavyweight resources associated with the view that may span cycles of the view becoming detached and reattached from a window.

fun View.findViewTreeViewModelStoreOwner(): ViewModelStoreOwner?

Retrieve the ViewModelStoreOwner associated with the given View. This may be used to retain state associated with this view across configuration changes.

fun <T : Any?> Flow<T>.flowWithLifecycle(
    lifecycle: Lifecycle,
    minActiveState: Lifecycle.State = Lifecycle.State.STARTED
): Flow<T>

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.

The flow will automatically start and cancel collecting from this upstream flow as the lifecycle moves in and out of the target state.

If this upstream Flow completes emitting items, flowWithLifecycle will trigger the flow collection again when the minActiveState state is reached.

This is NOT a terminal operator. This operator is usually followed by collect, or onEach and launchIn to process the emitted values.

Note: this operator creates a hot flow that only closes when the lifecycle is destroyed or the coroutine that collects from the flow is cancelled.

class MyActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        /* ... */
            // Launches a coroutine that collects items from a flow when the Activity
            // is at least started. It will automatically cancel when the activity is stopped and
            // start collecting again whenever it's started again.
            lifecycleScope.launch {
                flow
                    .flowWithLifecycle(lifecycle, Lifecycle.State.STARTED)
                    .collect {
                        // Consume flow emissions
                     }
            }
        }
    }

flowWithLifecycle cancels the upstream Flow when lifecycle falls below minActiveState state. However, the downstream Flow will be active without receiving any emissions as long as the scope used to collect the Flow is active. As such, please take care when using this function in an operator chain, as the order of the operators matters. For example, flow1.flowWithLifecycle(lifecycle).combine(flow2) behaves differently than flow1.combine(flow2).flowWithLifecycle(lifecycle). The former continues to combine both flows even when lifecycle falls below minActiveState state whereas the combination is cancelled in the latter case.

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

Tip: If multiple flows need to be collected using flowWithLifecycle, consider using the Lifecycle.repeatOnLifecycle API to collect from all of them using a different launch per flow instead. That's more efficient and consumes less resources as no hot flows are created.

@MainThread
inline fun <VM : ViewModel> ViewModelProvider.get(): VM

Returns an existing ViewModel or creates a new one in the scope (usually, a fragment or an activity), associated with this ViewModelProvider.

@MainThread
fun <X : Any?, Y : Any?> LiveData<X>.map(transform: (X) -> Y): LiveData<Y>

Returns a LiveData mapped from this LiveData by applying transform to each value set on this LiveData.

This method is analogous to io.reactivex.Observable.map.

transform will be executed on the main thread.

Here is an example mapping a simple User struct in a LiveData to a LiveData containing their full name as a String.

val userLD : LiveData<User> = ...;
val userFullNameLD: LiveData<String> = userLD.map { user -> user.firstName + user.lastName }

@MainThread
inline fun <T : Any?> LiveData<T>.observe(
    owner: LifecycleOwner,
    crossinline onChanged: (T) -> Unit
): Observer<T>

Adds the given onChanged lambda as an observer within the lifespan of the given owner and returns a reference to observer. The events are dispatched on the main thread. If LiveData already has data set, it will be delivered to the onChanged.

The observer will only receive events if the owner is in Lifecycle.State.STARTED or Lifecycle.State.RESUMED state (active).

If the owner moves to the Lifecycle.State.DESTROYED state, the observer will automatically be removed.

When data changes while the owner is not active, it will not receive any updates. If it becomes active again, it will receive the last available data automatically.

LiveData keeps a strong reference to the observer and the owner as long as the given LifecycleOwner is not destroyed. When it is destroyed, LiveData removes references to the observer and the owner.

If the given owner is already in Lifecycle.State.DESTROYED state, LiveData ignores the call.

suspend fun Lifecycle.repeatOnLifecycle(
    state: Lifecycle.State,
    block: suspend CoroutineScope.() -> Unit
): Unit

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.

suspend fun LifecycleOwner.repeatOnLifecycle(
    state: Lifecycle.State,
    block: suspend CoroutineScope.() -> Unit
): Unit

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)
                    }
                }
            }
        }
    }

inline fun <T : Any> SavedStateHandle.saved(noinline init: () -> T): ReadWriteProperty<Any?, T>

Returns a property delegate that uses SavedStateHandle to save and restore a value of type T with fully qualified property or variable name as key and the default serializer.

@Serializable data class User(val id: Int, val name: String)
class ProfileViewModel(savedStateHandle: SavedStateHandle) : ViewModel() {
    val user by savedStateHandle.saved { User(123, "foo") }
}

inline fun <T : Any> SavedStateHandle.saved(key: String, noinline init: () -> T): ReadWriteProperty<Any?, T>

Returns a property delegate that uses SavedStateHandle to save and restore a value of type T with the default serializer.

@Serializable data class User(val id: Int, val name: String)
class ProfileViewModel(savedStateHandle: SavedStateHandle) : ViewModel() {
    val user by savedStateHandle.saved(key = "bar") { User(123, "foo") }
}

fun <T : Any> SavedStateHandle.saved(
    serializer: <Error class: unknown class><T>,
    init: () -> T
): ReadWriteProperty<Any?, T>

Returns a property delegate that uses SavedStateHandle to save and restore a value of type T with fully qualified property or variable name as key.

@Serializable data class User(val id: Int, val name: String)
class ProfileViewModel(savedStateHandle: SavedStateHandle) : ViewModel() {
    val user by savedStateHandle.saved(User::class.serializer()) { User(123, "foo") }
}

fun <T : Any> SavedStateHandle.saved(
    key: String,
    serializer: <Error class: unknown class><T>,
    init: () -> T
): ReadWriteProperty<Any?, T>

Returns a property delegate that uses SavedStateHandle to save and restore a value of type T.

@Serializable data class User(val id: Int, val name: String)
class ProfileViewModel(savedStateHandle: SavedStateHandle) : ViewModel() {
    val user by
        savedStateHandle.saved(key = "bar", serializer = User::class.serializer()) {
            User(123, "foo")
        }
}

fun View.setViewTreeLifecycleOwner(lifecycleOwner: LifecycleOwner?): Unit

Set the LifecycleOwner responsible for managing the given View. Calls to get from this view or descendants will return lifecycleOwner.

This should only be called by constructs such as activities or fragments that manage a view tree and reflect their own lifecycle through a LifecycleOwner. Callers should only set a LifecycleOwner that will be stable. The associated lifecycle should report that it is destroyed if the view tree is removed and is not guaranteed to later become reattached to a window.

fun View.setViewTreeViewModelStoreOwner(
    viewModelStoreOwner: ViewModelStoreOwner?
): Unit

Set the ViewModelStoreOwner associated with the given View. Calls to get from this view or descendants will return viewModelStoreOwner.

This should only be called by constructs such as activities or fragments that manage a view tree and retain state through a ViewModelStoreOwner. Callers should only set a ViewModelStoreOwner that will be stable. The associated ViewModelStore should be cleared if the view tree is removed and is not guaranteed to later become reattached to a window.

@MainThread
fun <X : Any?, Y : Any?> LiveData<X>.switchMap(transform: (X) -> LiveData<Y>): LiveData<Y>

Returns a LiveData mapped from the input this LiveData by applying transform to each value set on this.

The returned `LiveData` delegates to the most recent `LiveData` created by [transform] with the most recent value set to `this`, without changing the reference. In this way [transform] can change the 'backing' `LiveData` transparently to any observer registered to the `LiveData` returned by `switchMap()`.

Note that when the backing LiveData is switched, no further values from the older LiveData will be set to the output LiveData. In this way, the method is analogous to io.reactivex.Observable.switchMap.

transform will be executed on the main thread.

Here is an example class that holds a typed-in name of a user String (such as from an EditText) in a MutableLiveData and returns a LiveData containing a List of User objects for users that have that name. It populates that LiveData by requerying a repository-pattern object each time the typed name changes.

This `ViewModel` would permit the observing UI to update "live" as the user ID text changes.

class UserViewModel: AndroidViewModel {
    val nameQueryLiveData : MutableLiveData<String> = ...

    fun usersWithNameLiveData(): LiveData<List<String>> = nameQueryLiveData.switchMap {
        name -> myDataSource.usersWithNameLiveData(name)
    }

    fun setNameQuery(val name: String) {
        this.nameQueryLiveData.value = name;
    }
}

fun <T : Any?> Publisher<T>.toLiveData(): LiveData<T>

Creates an observable LiveData stream from a ReactiveStreams Publisher}.

When the LiveData becomes active, it subscribes to the emissions from the Publisher.

When the LiveData becomes inactive, the subscription is cleared. LiveData holds the last value emitted by the Publisher when the LiveData was active.

Therefore, in the case of a hot RxJava Observable, when a new LiveData Observer is added, it will automatically notify with the last value held in LiveData, which might not be the last value emitted by the Publisher.

Note that LiveData does NOT handle errors and it expects that errors are treated as states in the data that's held. In case of an error being emitted by the publisher, an error will be propagated to the main thread and the app will crash.

fun <T : Any?> LiveData<T>.toPublisher(lifecycle: LifecycleOwner): Publisher<T>

Adapts the given LiveData stream to a ReactiveStreams Publisher.

By using a good publisher implementation such as RxJava 2.x Flowables, most consumers will be able to let the library deal with backpressure using operators and not need to worry about ever manually calling Subscription.request.

On subscription to the publisher, the observer will attach to the given LiveData. Once Subscription.request is called on the subscription object, an observer will be connected to the data stream. Calling request(Long.MAX_VALUE) is equivalent to creating an unbounded stream with no backpressure. If request with a finite count reaches 0, the observer will buffer the latest item and emit it to the subscriber when data is again requested. Any other items emitted during the time there was no backpressure requested will be dropped.

suspend fun <T : Any?> LifecycleOwner.whenCreated(block: suspend CoroutineScope.() -> T): T

Runs the given block when the LifecycleOwner's Lifecycle is at least in Lifecycle.State.CREATED state.

suspend fun <T : Any?> Lifecycle.whenCreated(block: suspend CoroutineScope.() -> T): T

Runs the given block when the Lifecycle is at least in Lifecycle.State.CREATED state.

suspend fun <T : Any?> LifecycleOwner.whenResumed(block: suspend CoroutineScope.() -> T): T

Runs the given block when the LifecycleOwner's Lifecycle is at least in Lifecycle.State.RESUMED state.

suspend fun <T : Any?> Lifecycle.whenResumed(block: suspend CoroutineScope.() -> T): T

Runs the given block when the Lifecycle is at least in Lifecycle.State.RESUMED state.

suspend fun <T : Any?> LifecycleOwner.whenStarted(block: suspend CoroutineScope.() -> T): T

Runs the given block when the LifecycleOwner's Lifecycle is at least in Lifecycle.State.STARTED state.

suspend fun <T : Any?> Lifecycle.whenStarted(block: suspend CoroutineScope.() -> T): T

Runs the given block when the Lifecycle is at least in Lifecycle.State.STARTED state.

suspend fun <T : Any?> Lifecycle.whenStateAtLeast(
    minState: Lifecycle.State,
    block: suspend CoroutineScope.() -> T
): T

Runs the given block on a CoroutineDispatcher that executes the block on the main thread and suspends the execution unless the Lifecycle's state is at least minState.

If the Lifecycle moves to a lesser state while the block is running, the block will be suspended until the Lifecycle reaches to a state greater or equal to minState.

Note that this won't effect any sub coroutine if they use a different CoroutineDispatcher. However, the block will not resume execution when the sub coroutine finishes unless the Lifecycle is at least in minState.

If the Lifecycle is destroyed while the block is suspended, the block will be cancelled which will also cancel any child coroutine launched inside the block.

If you have a try finally block in your code, the finally might run after the Lifecycle moves outside the desired state. It is recommended to check the Lifecycle.getCurrentState before accessing the UI. Similarly, if you have a catch statement that might catch CancellationException, you should check the Lifecycle.getCurrentState before accessing the UI. See the sample below for more details.

// running a block of code only if lifecycle is STARTED
viewLifecycle.whenStateAtLeast(Lifecycle.State.STARTED) {
    // here, we are on the main thread and view lifecycle is guaranteed to be STARTED or RESUMED.
    // We can safely access our views.
    loadingBar.visibility = View.VISIBLE
    try {
        // we can call any suspend function
        val data = withContext(Dispatchers.IO) {
            // this will run in IO thread pool. It will keep running as long as Lifecycle
            // is not DESTROYED. If it is destroyed, this coroutine will be cancelled as well.
            // However, we CANNOT access Views here.

            // We are using withContext(Dispatchers.IO) here just for demonstration purposes.
            // Such code should live in your business logic classes and your UI should use a
            // ViewModel (or similar) to access it.
            api.getUser()
        }
        // this line will execute on the main thread and only if the lifecycle is in at least
        // STARTED state (STARTED is the parameter we've passed to whenStateAtLeast)
        // Because of this guarantee, we can safely access the UI again.
        loadingBar.visibility = View.GONE
        nameTextView.text = user.name
        lastNameTextView.text = user.lastName
    } catch(ex : UserNotFoundException) {
        // same as above, this code can safely access UI elements because it only runs if
        // view lifecycle is at least STARTED
        loadingBar.visibility = View.GONE
        showErrorDialog(ex)
    } catch(th : Throwable) {
         // Unlike the catch statement above, this catch statements it too generic and might
         // also catch the CancellationException. Before accessing UI, you should check isActive
         // or lifecycle state
         if (viewLifecycle.currentState >= Lifecycle.State.STARTED) {
             // here you can access the view because you've checked the coroutine is active
         }
    } finally {
        // in case of cancellation, this line might run even if the Lifecycle is not DESTROYED.
        // You cannot access Views here unless you check `isActive` or lifecycle state
        if (viewLifecycle.currentState >= Lifecycle.State.STARTED) {
            // safe to access views
        } else {
            // not safe to access views
        }
    }
}

suspend inline fun <R : Any?> Lifecycle.withCreated(crossinline block: () -> R): R

Run block with this Lifecycle in a Lifecycle.State of at least Lifecycle.State.CREATED and resume with the result. Throws the CancellationException if the lifecycle has reached Lifecycle.State.DESTROYED by the time of the call or before block is able to run.

suspend inline fun <R : Any?> LifecycleOwner.withCreated(crossinline block: () -> R): R

Run block with this LifecycleOwner's Lifecycle in a Lifecycle.State of at least Lifecycle.State.CREATED and resume with the result. Throws the CancellationException if the lifecycle has reached Lifecycle.State.DESTROYED by the time of the call or before block is able to run.

suspend inline fun <R : Any?> Lifecycle.withResumed(crossinline block: () -> R): R

Run block with this Lifecycle in a Lifecycle.State of at least Lifecycle.State.RESUMED and resume with the result. Throws the CancellationException if the lifecycle has reached Lifecycle.State.DESTROYED by the time of the call or before block is able to run.

suspend inline fun <R : Any?> LifecycleOwner.withResumed(crossinline block: () -> R): R

Run block with this LifecycleOwner's Lifecycle in a Lifecycle.State of at least Lifecycle.State.RESUMED and resume with the result. Throws the CancellationException if the lifecycle has reached Lifecycle.State.DESTROYED by the time of the call or before block is able to run.

suspend inline fun <R : Any?> Lifecycle.withStarted(crossinline block: () -> R): R

Run block with this Lifecycle in a Lifecycle.State of at least Lifecycle.State.STARTED and resume with the result. Throws the CancellationException if the lifecycle has reached Lifecycle.State.DESTROYED by the time of the call or before block is able to run.

suspend inline fun <R : Any?> LifecycleOwner.withStarted(crossinline block: () -> R): R

Run block with this LifecycleOwner's Lifecycle in a Lifecycle.State of at least Lifecycle.State.STARTED and resume with the result. Throws the CancellationException if the lifecycle has reached Lifecycle.State.DESTROYED by the time of the call or before block is able to run.

suspend inline fun <R : Any?> Lifecycle.withStateAtLeast(
    state: Lifecycle.State,
    crossinline block: () -> R
): R

Run block with this Lifecycle in a Lifecycle.State of at least state and resume with the result. Throws the CancellationException if the lifecycle has reached Lifecycle.State.DESTROYED by the time of the call or before block is able to run.

suspend inline fun <R : Any?> LifecycleOwner.withStateAtLeast(
    state: Lifecycle.State,
    crossinline block: () -> R
): R

Run block with this LifecycleOwner's Lifecycle in a Lifecycle.State of at least state and resume with the result. Throws the CancellationException if the lifecycle has reached Lifecycle.State.DESTROYED by the time of the call or before block is able to run.

val DEFAULT_ARGS_KEY: CreationExtras.Key<SavedState>

A key for default arguments that should be passed to SavedStateHandle if needed.

val SAVED_STATE_REGISTRY_OWNER_KEY: CreationExtras.Key<SavedStateRegistryOwner>

A key for SavedStateRegistryOwner that corresponds to ViewModelStoreOwner of a ViewModel that is being created.

val VIEW_MODEL_STORE_OWNER_KEY: CreationExtras.Key<ViewModelStoreOwner>

A key for ViewModelStoreOwner that is an owner of a ViewModel that is being created.

val AndroidViewModel.application: Application

The underlying Application inside AndroidViewModel

One common hierarchy, such as KotlinViewModel <: JavaViewModel <: AndroidViewModel, exposes private property application incorrectly. It is now fixed in K2 (Kotlin language version 2.0), but not backward compatible. This inline extension will make compilations of both pre- and post- 2.0 go well.

val Lifecycle.coroutineScope: LifecycleCoroutineScope

CoroutineScope tied to this Lifecycle.

This scope will be cancelled when the Lifecycle is destroyed.

This scope is bound to Dispatchers.Main.immediate

val Lifecycle.eventFlow: Flow<Lifecycle.Event>

Creates a Flow of Lifecycle.Events containing values dispatched by this Lifecycle.

val LifecycleOwner.lifecycleScope: LifecycleCoroutineScope

CoroutineScope tied to this LifecycleOwner's Lifecycle.

This scope will be cancelled when the Lifecycle is destroyed.

This scope is bound to Dispatchers.Main.immediate.

val ViewModel.viewModelScope: CoroutineScope

The CoroutineScope associated with this ViewModel.

The CoroutineScope.coroutineContext is configured with:

• SupervisorJob: ensures children jobs can fail independently of each other.

• MainCoroutineDispatcher.immediate: executes jobs immediately on the main (UI) thread. If the Dispatchers.Main is not available on the current platform (e.g., Linux), we fallback to an EmptyCoroutineContext.

This scope is automatically cancelled when the ViewModel is cleared, and can be replaced by using the ViewModel constructor overload that takes in a viewModelScope: CoroutineScope.

For background execution, use kotlinx.coroutines.withContext to switch to appropriate dispatchers (e.g., kotlinx.coroutines.IO).