public abstract class Lifecycle

Known direct subclasses
LifecycleRegistry

A Lifecycle implementation that manages multiple LifecycleObservers.

Defines an object with a lifecycle state control flow.

Commonly implemented by UI container classes (such as Activities and Fragments on Android) or custom components to expose their lifecycle to other components.

Event.ON_CREATE, Event.ON_START, Event.ON_RESUME events are dispatched after the LifecycleOwner's related method returns. Event.ON_PAUSE, Event.ON_STOP, Event.ON_DESTROY events are dispatched before the LifecycleOwner's related method 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.

See also
Lifecycle.State

for the valid lifecycle states.
Lifecycle.Event

for the transition events between states.

Summary

Nested types
public enum Lifecycle.Event extends Enum

Represents a transition event triggered by a change in the LifecycleOwner's state.
public enum Lifecycle.State extends Enum

Represents the current lifecycle state of a LifecycleOwner.

Public constructors

Public methods
abstract void

Adds a LifecycleObserver to receive LifecycleOwner state changes.
abstract @NonNull Lifecycle.State

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 list of registered observers.

Extension functions
final @NonNull LifecycleObserver

Adds a LifecycleObserver to this Lifecycle using the provided action.
final @NonNull LifecycleCoroutineScope

CoroutineScope tied to this Lifecycle.
final @NonNull Flow<@NonNull Lifecycle.Event>

Creates a Flow of Lifecycle.Events 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 to receive LifecycleOwner state changes.

Brings the given observer up to the current State of the LifecycleOwner. For example, if the LifecycleOwner is in State.STARTED, the observer receives Event.ON_CREATE and Event.ON_STARTs.

Parameters
@NonNull LifecycleObserver observer

The observer to notify.

getCurrentState

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

The current State of the Lifecycle.

getCurrentStateFlow

Added in 2.7.0
public @NonNull StateFlow<@NonNull Lifecycle.State> getCurrentStateFlow()

Returns a 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 list of registered observers.

If 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 one method that observes the currently dispatched event, and at least one of them received the event, all of them receive it, and removal occurs afterward.

Parameters
@NonNull LifecycleObserver observer

The observer to remove.

Extension functions

LifecycleKt.addObserver

public final @NonNull LifecycleObserver LifecycleKt.addObserver(
    @NonNull Lifecycle receiver,
    @NonNull Function3<@NonNull LifecycleObserver, @NonNull LifecycleOwner, @NonNull Lifecycle.Event, Unit> action
)

Adds a LifecycleObserver to this Lifecycle using the provided action.

Invokes action whenever a Lifecycle.Event occurs.

Parameters
@NonNull Function3<@NonNull LifecycleObserver, @NonNull LifecycleOwner, @NonNull Lifecycle.Event, Unit> action

The action invoked on each Lifecycle.Event, providing the LifecycleOwner and the specific Lifecycle.Event.
Returns
@NonNull LifecycleObserver

the added LifecycleObserver instance (can be used to later remove it).

LifecycleKt.getCoroutineScope

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

CoroutineScope tied to this Lifecycle.

Canceled when the Lifecycle is destroyed. Bound to Dispatchers.Main.immediate.

LifecycleKt.getEventFlow

public final @NonNull Flow<@NonNull Lifecycle.Event> LifecycleKt.getEventFlow(@NonNull Lifecycle receiver)

Creates a Flow of Lifecycle.Events 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.