CompositionObserver

Artifact: androidx.compose.runtime:runtime

Added in 1.6.0

Cmn

@ExperimentalComposeRuntimeApi
interface CompositionObserver

Observe RecomposeScope management inside composition.

The expected lifecycle of a RecomposeScope in composition is as follows:

// In the composition phase:
[onBeginComposition]
       ┃
[onScopeEnter] ━┓   // Composition enters a scope
                ┃
         [onReadInScope]  // Record reads inside the scope
                ┃
                ┗━ [onScopeEnter]
                    ...             // Potentially enter nested function scopes
                ┏━ [onScopeExit]
                ┃
[onScopeExit]  ━┛   // Composition leaves the scope
       ┃
[onEndComposition]

// In the apply changes phase:
[onScopeDisposed]   // Scope is discarded by composition and is no longer used.

The scopes can be invalidated at any point either by values previously reported in onReadInScope or by calling RecomposeScope.invalidate directly. In these cases, onScopeInvalidated will be called with the associated instance or null if the scope was invalidated directly.

Note that invalidation of the scope does not guarantee it will be composed. Some cases where it is not composed are:

The scope is no longer part of the composition (e.g the parent scope no longer executed the code branch the scope was a part of)
The scope is part of movable content that was moved out of the composition.

In the case of movable content, the scope will be recomposed as part of a different composition when it is moved to that composition or it might be discarded (with a corresponding onScopeDisposed call) if no other composition claims it.

Summary

Public functions
`Unit`	`onBeginComposition(composition: ObservableComposition)` Called when the composition process begins for `composition` instance.	Cmn
`Unit`	`onEndComposition(composition: ObservableComposition)` Called after composition process has been completed for `composition`.	Cmn
`Unit`	`onReadInScope(scope: RecomposeScope, value: Any)` Called when read of `value` is recorded in `scope` during composition.	Cmn
`Unit`	`onScopeDisposed(scope: RecomposeScope)` Called when `RecomposeScope` is no longer used in composition.	Cmn
`Unit`	`onScopeEnter(scope: RecomposeScope)` Called when `scope` enters the composition.	Cmn
`Unit`	`onScopeExit(scope: RecomposeScope)` Called when `RecomposeScope` exits composition.	Cmn
`Unit`	`onScopeInvalidated(scope: RecomposeScope, value: Any?)` Called when `scope` is invalidated by composition or `RecomposeScope.invalidate` call.	Cmn

Public functions

onBeginComposition

Cmn

Added in 1.9.0

fun onBeginComposition(composition: ObservableComposition): Unit

Called when the composition process begins for composition instance.

onEndComposition

Cmn

Added in 1.9.0

fun onEndComposition(composition: ObservableComposition): Unit

Called after composition process has been completed for composition.

onReadInScope

Cmn

Added in 1.9.0

fun onReadInScope(scope: RecomposeScope, value: Any): Unit

Called when read of value is recorded in scope during composition.

Reads can be recorded without re-execution of the function associated with the scope, for example when derived state invalidates the scope with the same value as before.

The instances passed to this method are only tracked between onScopeEnter and onScopeExit calls. Previously recorded instances should also be cleared when onScopeEnter is called again, to avoid keeping stale instances that are no longer tracked by composition. For example, this happens with remember { state.value }, with state recorded only during first composition.

Parameters
`scope: RecomposeScope`	A `RecomposeScope` that the read occurred in.
`value: Any`	A value that was recorded in `scope` and can invalidate it in the future. In most cases, `value` is a snapshot state instance.

onScopeDisposed

Cmn

Added in 1.9.0

fun onScopeDisposed(scope: RecomposeScope): Unit

Called when RecomposeScope is no longer used in composition. Can be called from any thread whenever composition applies changes or is disposed.

onScopeEnter

Cmn

Added in 1.9.0

fun onScopeEnter(scope: RecomposeScope): Unit

Called when scope enters the composition.

onScopeExit

Cmn

Added in 1.9.0

fun onScopeExit(scope: RecomposeScope): Unit

Called when RecomposeScope exits composition.

onScopeInvalidated

Cmn

Added in 1.9.0

fun onScopeInvalidated(scope: RecomposeScope, value: Any?): Unit

Called when scope is invalidated by composition or RecomposeScope.invalidate call.

Note that for invalidations caused by a state change, this callback is not called immediately on the state write. Usually, invalidations from state changes are recorded right before recomposition starts or during composition (e.g. if rememberUpdatedState is used). This method is always guaranteed to be called before onScopeEnter for the corresponding invalidation is executed. If the scope was invalidated by RecomposeScope.invalidate, however, this callback is executed before RecomposeScope.invalidate returns.

Parameters
`scope: RecomposeScope`	A `RecomposeScope` that is invalidated.
`value: Any?`	A value that invalidated composition. Can be `null` if the scope was invalidated by calling `RecomposeScope.invalidate` directly.