public abstract class Lifecycle

Known direct subclasses
LifecycleRegistry

An implementation of Lifecycle that can handle multiple observers.


Defines an object that has an Android Lifecycle. Fragment and FragmentActivity classes implement LifecycleOwner interface which has the LifecycleOwner.getLifecycle method to access the Lifecycle. You can also implement LifecycleOwner in your own classes.

Event.ON_CREATE, Event.ON_START, Event.ON_RESUME events in this class are dispatched after the LifecycleOwner's related method returns. Event.ON_PAUSE, Event.ON_STOP, Event.ON_DESTROY events in this class are dispatched before the LifecycleOwner's related method is called. For instance, Event.ON_START will be dispatched after onStart returns, Event.ON_STOP will be dispatched before onStop is called. This gives you certain guarantees on which state the owner is in.

To observe lifecycle events call .addObserver passing an object that implements either DefaultLifecycleObserver or LifecycleEventObserver.

Summary

Nested types

public enum Lifecycle.Event extends Enum
public enum Lifecycle.State extends Enum

Lifecycle states.

Public constructors

Public methods

abstract void

Adds a LifecycleObserver that will be notified when the LifecycleOwner changes state.

abstract @NonNull Lifecycle.State

Returns the current state of the Lifecycle.

@NonNull StateFlow<@NonNull Lifecycle.State>

Returns a StateFlow where the StateFlow.value represents the current State of this Lifecycle.

abstract void

Removes the given observer from the observers list.

Extension functions

final @NonNull LifecycleCoroutineScope

CoroutineScope tied to this Lifecycle.

final @NonNull Flow<@NonNull Lifecycle.Event>

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

final @NonNull R
<R extends Object> WithLifecycleStateKt.withCreated(
    @NonNull Lifecycle receiver,
    @NonNull Function0<@NonNull R> block
)

Run block with this Lifecycle in a Lifecycle.State of at least Lifecycle.State.CREATED and resume with the result.

final @NonNull R
<R extends Object> WithLifecycleStateKt.withResumed(
    @NonNull Lifecycle receiver,
    @NonNull Function0<@NonNull R> block
)

Run block with this Lifecycle in a Lifecycle.State of at least Lifecycle.State.RESUMED and resume with the result.

final @NonNull R
<R extends Object> WithLifecycleStateKt.withStarted(
    @NonNull Lifecycle receiver,
    @NonNull Function0<@NonNull R> block
)

Run block with this Lifecycle in a Lifecycle.State of at least Lifecycle.State.STARTED and resume with the result.

final @NonNull R
<R extends Object> WithLifecycleStateKt.withStateAtLeast(
    @NonNull Lifecycle receiver,
    @NonNull Lifecycle.State state,
    @NonNull Function0<@NonNull R> block
)

Run block with this Lifecycle in a Lifecycle.State of at least state and resume with the result.

Public constructors

Lifecycle

Added in 2.0.0
public Lifecycle()

Public methods

addObserver

Added in 2.0.0
@MainThread
public abstract void addObserver(@NonNull LifecycleObserver observer)

Adds a LifecycleObserver that will be notified when the LifecycleOwner changes state.

The given observer will be brought to the current state of the LifecycleOwner. For example, if the LifecycleOwner is in State.STARTED state, the given observer will receive Event.ON_CREATE, Event.ON_START events.

Parameters
@NonNull LifecycleObserver observer

The observer to notify.

getCurrentState

Added in 2.0.0
@MainThread
public abstract @NonNull Lifecycle.State getCurrentState()

Returns the current state of the Lifecycle.

Returns
@NonNull Lifecycle.State

The current state of the Lifecycle.

getCurrentStateFlow

Added in 2.7.0
public @NonNull StateFlow<@NonNull Lifecycle.StategetCurrentStateFlow()

Returns a StateFlow where the StateFlow.value represents the current State of this Lifecycle.

Returns
@NonNull StateFlow<@NonNull Lifecycle.State>

StateFlow where the StateFlow.value represents the current State of this Lifecycle.

removeObserver

Added in 2.0.0
@MainThread
public abstract void removeObserver(@NonNull LifecycleObserver observer)

Removes the given observer from the observers list.

If this method is called while a state change is being dispatched,

  • If the given observer has not yet received that event, it will not receive it.

  • If the given observer has more than 1 method that observes the currently dispatched event and at least one of them received the event, all of them will receive the event and the removal will happen afterwards.

Parameters
@NonNull LifecycleObserver observer

The observer to be removed.

Extension functions

LifecycleKt.getCoroutineScope

public final @NonNull LifecycleCoroutineScope LifecycleKt.getCoroutineScope(@NonNull Lifecycle receiver)

CoroutineScope tied to this Lifecycle.

This scope will be cancelled when the Lifecycle is destroyed.

This scope is bound to Dispatchers.Main.immediate

LifecycleKt.getEventFlow

public final @NonNull Flow<@NonNull Lifecycle.EventLifecycleKt.getEventFlow(@NonNull Lifecycle receiver)

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

WithLifecycleStateKt.withCreated

public final @NonNull R <R extends Object> WithLifecycleStateKt.withCreated(
    @NonNull Lifecycle receiver,
    @NonNull Function0<@NonNull R> block
)

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.

WithLifecycleStateKt.withResumed

public final @NonNull R <R extends Object> WithLifecycleStateKt.withResumed(
    @NonNull Lifecycle receiver,
    @NonNull Function0<@NonNull R> block
)

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.

WithLifecycleStateKt.withStarted

public final @NonNull R <R extends Object> WithLifecycleStateKt.withStarted(
    @NonNull Lifecycle receiver,
    @NonNull Function0<@NonNull R> block
)

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.

WithLifecycleStateKt.withStateAtLeast

public final @NonNull R <R extends Object> WithLifecycleStateKt.withStateAtLeast(
    @NonNull Lifecycle receiver,
    @NonNull Lifecycle.State state,
    @NonNull Function0<@NonNull R> block
)

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.