Recomposer

public class Recomposer(effectCoroutineContext: CoroutineContext) : CompositionContext()

The scheduler for performing recomposition and applying updates to one or more Compositions.

Properties

changeCount

public var changeCount: Long = 0L

This is a running count of the number of times the recomposer awoke and applied changes to one or more composers. This count is unaffected if the composer awakes and recomposed but composition did not produce changes to apply.

effectCoroutineContext

override val effectCoroutineContext: CoroutineContext =
        effectCoroutineContext + broadcastFrameClock + effectJob

The effectCoroutineContext is derived from the parameter of the same name.

state

@Deprecated("Replaced by currentState as a StateFlow", ReplaceWith("currentState"))
    public val state: Flow<State>

The current State of this Recomposer. See each State value for its meaning.

currentState

public val currentState: StateFlow<State>

The current State of this Recomposer, available synchronously.

hasPendingWork

public val hasPendingWork: Boolean

true if this Recomposer has any pending work scheduled, regardless of whether or not it is currently running.

composition

override val composition: Composition?

Functions

asRecomposerInfo

public fun asRecomposerInfo(): RecomposerInfo

Obtain a read-only RecomposerInfo for this Recomposer.

runRecomposeAndApplyChanges

public suspend fun runRecomposeAndApplyChanges(): Unit

Await the invalidation of any associated Composers, recompose them, and apply their changes to their associated Compositions if recomposition is successful.

While runRecomposeAndApplyChanges is running, awaitIdle will suspend until there are no more invalid composers awaiting recomposition.

This method will not return unless the Recomposer is closed and all effects in managed compositions complete. Unhandled failure exceptions from child coroutines will be thrown by this method.

cancel

public fun cancel()

Permanently shut down this Recomposer for future use. currentState will immediately reflect State.ShuttingDown (or a lower state) before this call returns. All ongoing recompositions will stop, new composer invalidations with this Recomposer at the root will no longer occur, and any LaunchedEffects currently running in compositions managed by this Recomposer will be cancelled. Any rememberCoroutineScope scopes from compositions managed by this Recomposer will also be cancelled. See join to await the completion of all of these outstanding tasks.

close

public fun close()

Close this Recomposer. Once all effects launched by managed compositions complete, any active call to runRecomposeAndApplyChanges will return normally and this Recomposer will be State.ShutDown. See join to await the completion of all of these outstanding tasks.

join

public suspend fun join()

Await the completion of a cancel operation.

reportPausedScope

override fun reportPausedScope(scope: RecomposeScopeImpl)

awaitIdle

public suspend fun awaitIdle()

Suspends until the currently pending recomposition frame is complete. Any recomposition for this recomposer triggered by actions before this call begins will be complete and applied (if recomposition was successful) when this call returns.

If runRecomposeAndApplyChanges is not currently running the Recomposer is considered idle and this method will not suspend.

pauseCompositionFrameClock

public fun pauseCompositionFrameClock()

Pause broadcasting the frame clock while recomposing. This effectively pauses animations, or any other use of the withFrameNanos, while the frame clock is paused.

pauseCompositionFrameClock should be called when the recomposer is not being displayed for some reason such as not being the current activity in Android, for example.

Calls to pauseCompositionFrameClock are thread-safe and idempotent (calling it when the frame clock is already paused is a no-op).

resumeCompositionFrameClock

public fun resumeCompositionFrameClock()

Resume broadcasting the frame clock after is has been paused. Pending calls to withFrameNanos will start receiving frame clock broadcasts at the beginning of the frame and a frame will be requested if there are pending calls to withFrameNanos if a frame has not already been scheduled.

Calls to resumeCompositionFrameClock are thread-safe and idempotent (calling it when the frame clock is running is a no-op).

movableContentStateResolve

override fun movableContentStateResolve(
        reference: MovableContentStateReference
    ): MovableContentState?

Members

State

public enum class State {
        /**
         * [cancel] was called on the [Recomposer] and all cleanup work has completed. The
         * [Recomposer] is no longer available for use.
         */
        ShutDown,

        /**
         * [cancel] was called on the [Recomposer] and it is no longer available for use. Cleanup
         * work has not yet been fully completed and composition effect coroutines may still be
         * running.
         */
        ShuttingDown,

        /**
         * The [Recomposer] is not tracking invalidations for known composers and it will not
         * recompose them in response to changes. Call [runRecomposeAndApplyChanges] to await and
         * perform work. This is the initial state of a newly constructed [Recomposer].
         */
        Inactive,

        /**
         * The [Recomposer] is [Inactive] but at least one effect associated with a managed
         * composition is awaiting a frame. This frame will not be produced until the [Recomposer]
         * is [running][runRecomposeAndApplyChanges].
         */
        InactivePendingWork,

        /**
         * The [Recomposer] is tracking composition and snapshot invalidations but there is
         * currently no work to do.
         */
        Idle,

        /**
         * The [Recomposer] has been notified of pending work it must perform and is either actively
         * performing it or awaiting the appropriate opportunity to perform it. This work may
         * include invalidated composers that must be recomposed, snapshot state changes that must
         * be presented to known composers to check for invalidated compositions, or coroutines
         * awaiting a frame using the Recomposer's [MonotonicFrameClock].
         */
        PendingWork,
    }

Valid operational states of a Recomposer.

Members

ShutDown

ShutDown

cancel was called on the Recomposer and all cleanup work has completed. The Recomposer is no longer available for use.

ShuttingDown

ShuttingDown

cancel was called on the Recomposer and it is no longer available for use. Cleanup work has not yet been fully completed and composition effect coroutines may still be running.

Inactive

Inactive

The Recomposer is not tracking invalidations for known composers and it will not recompose them in response to changes. Call runRecomposeAndApplyChanges to await and perform work. This is the initial state of a newly constructed Recomposer.

InactivePendingWork

InactivePendingWork

The Recomposer is Inactive but at least one effect associated with a managed composition is awaiting a frame. This frame will not be produced until the Recomposer is running.

Idle

Idle

The Recomposer is tracking composition and snapshot invalidations but there is currently no work to do.

PendingWork

PendingWork

The Recomposer has been notified of pending work it must perform and is either actively performing it or awaiting the appropriate opportunity to perform it. This work may include invalidated composers that must be recomposed, snapshot state changes that must be presented to known composers to check for invalidated compositions, or coroutines awaiting a frame using the Recomposer's MonotonicFrameClock.

Companion

public companion object

hack: the companion object is thread local in Kotlin/Native to avoid freezing _runningRecomposers with the current memory model. As a side effect, recomposers are now forced to be single threaded in Kotlin/Native targets.

This annotation WILL BE REMOVED with the new memory model of Kotlin/Native.

Properties

runningRecomposers

public val runningRecomposers: StateFlow<Set<RecomposerInfo>>

An observable Set of RecomposerInfos for currently running Recomposers. Emitted sets are immutable.