{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

SnapshotStateObserver

public final class SnapshotStateObserver


Helper class to efficiently observe snapshot state reads. See observeReads for more details.

NOTE: This class is not thread-safe, so implementations should not reuse observer between different threads to avoid race conditions.

Summary

Public constructors

SnapshotStateObserver(
    @NonNull Function1<@NonNull Function0<Unit>, Unit> onChangedExecutor
)

Public methods

final void

Remove all observations.

final void

Clears all state read observations for a given scope.

final void
clearIf(@NonNull Function1<@NonNull Object, @NonNull Boolean> predicate)

Remove observations using predicate to identify scopes to be removed.

final void
@TestOnly
notifyChanges(
    @NonNull Set<@NonNull Object> changes,
    @NonNull Snapshot snapshot
)

This method is only used for testing.

final void
<T extends Object> observeReads(
    @NonNull T scope,
    @NonNull Function1<@NonNull T, Unit> onValueChangedForScope,
    @NonNull Function0<Unit> block
)

Executes block, observing state object reads during its execution.

final void

Starts watching for state commits.

final void

Stops watching for state commits.

final void
withNoObservations(@NonNull Function0<Unit> block)

This method is deprecated. Replace with Snapshot.withoutReadObservation()

Public constructors

SnapshotStateObserver

public SnapshotStateObserver(
    @NonNull Function1<@NonNull Function0<Unit>, Unit> onChangedExecutor
)

Public methods

clear

public final void clear()

Remove all observations.

clear

public final void clear(@NonNull Object scope)

Clears all state read observations for a given scope. This clears values for all onValueChangedForScope callbacks passed in observeReads.

clearIf

public final void clearIf(@NonNull Function1<@NonNull Object, @NonNull Boolean> predicate)

Remove observations using predicate to identify scopes to be removed. This is used when a scope is no longer in the hierarchy and should not receive any callbacks.

notifyChanges

@TestOnly
public final void notifyChanges(
    @NonNull Set<@NonNull Object> changes,
    @NonNull Snapshot snapshot
)

This method is only used for testing. It notifies that changes have been made on snapshot.

observeReads

public final void <T extends Object> observeReads(
    @NonNull T scope,
    @NonNull Function1<@NonNull T, Unit> onValueChangedForScope,
    @NonNull Function0<Unit> block
)

Executes block, observing state object reads during its execution.

The scope and onValueChangedForScope are associated with any values that are read so that when those values change, onValueChangedForScope will be called with the scope parameter.

Observation can be paused with Snapshot.withoutReadObservation.

Parameters
@NonNull T scope

value associated with the observed scope.

@NonNull Function1<@NonNull T, Unit> onValueChangedForScope

is called with the scope when value read within block has been changed. For repeated observations, it is more performant to pass the same instance of the callback, as observedScopeMaps grows with each new callback instance.

@NonNull Function0<Unit> block

to observe reads within.

start

public final void start()

Starts watching for state commits.

stop

public final void stop()

Stops watching for state commits.

withNoObservations

public final void withNoObservations(@NonNull Function0<Unit> block)

Stops observing state object reads while executing block. State object reads may be restarted by calling observeReads inside block.