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:

  1. 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)

  2. 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

Called when the composition process begins for composition instance.
Cmn
Unit

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

Called when RecomposeScope is no longer used in composition.
Cmn
Unit

Called when scope enters the composition.
Cmn
Unit

Called when RecomposeScope exits composition.
Cmn
Unit

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

Public functions

onBeginComposition

Cmn
Added in 1.9.0-alpha04
fun onBeginComposition(composition: ObservableComposition): Unit

Called when the composition process begins for composition instance.

onEndComposition

Cmn
Added in 1.9.0-alpha04
fun onEndComposition(composition: ObservableComposition): Unit

Called after composition process has been completed for composition.

onReadInScope

Cmn
Added in 1.9.0-alpha04
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-alpha04
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-alpha04
fun onScopeEnter(scope: RecomposeScope): Unit

Called when scope enters the composition.

onScopeExit

Cmn
Added in 1.9.0-alpha04
fun onScopeExit(scope: RecomposeScope): Unit

Called when RecomposeScope exits composition.

onScopeInvalidated

Cmn
Added in 1.9.0-alpha04
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.