CompositionObserver

Interface

Common

@ExperimentalComposeRuntimeApi
public 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.

Functions

public fun onBeginComposition(composition: ObservableComposition)

Called when the composition process begins for composition instance.

public fun onScopeEnter(scope: RecomposeScope)

Called when scope enters the composition.

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

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	A `RecomposeScope` that the read occurred in.
value	A value that was recorded in `scope` and can invalidate it in the future. In most cases, `value` is a snapshot state instance.

public fun onScopeExit(scope: RecomposeScope)

Called when RecomposeScope exits composition.

public fun onEndComposition(composition: ObservableComposition)

Called after composition process has been completed for composition.

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

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	A `RecomposeScope` that is invalidated.
value	A value that invalidated composition. Can be `null` if the scope was invalidated by calling `RecomposeScope.invalidate` directly.

public fun onScopeDisposed(scope: RecomposeScope)

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