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

MutableSnapshot

public class MutableSnapshot extends Snapshot

java.lang.Object
   ↳ androidx.compose.runtime.snapshots.Snapshot
     ↳ androidx.compose.runtime.snapshots.MutableSnapshot

A snapshot of the values return by mutable states and other state objects. All state object will have the same value in the snapshot as they had when the snapshot was created unless they are explicitly changed in the snapshot.

To enter a snapshot call enter. The snapshot is the current snapshot as returned by currentSnapshot until the control returns from the lambda (or until a nested enter is called. All state objects will return the values associated with this snapshot, locally in the thread, until enter returns. All other threads are unaffected.

All changes made in a MutableSnapshot are snapshot isolated from all other snapshots and their changes can only be seen globally, or by new shots, after MutableSnapshot.apply as been called.

Snapshots can be nested by calling takeNestedSnapshot or MutableSnapshot.takeNestedMutableSnapshot.

See also
takeMutableSnapshot
mutableStateOf
mutableStateListOf
mutableStateMapOf

Summary

Public methods

@NonNull SnapshotApplyResult

Apply the changes made to state objects in this snapshot to the global state, or to the parent snapshot if this is a nested mutable snapshot.

void

Dispose the snapshot.

boolean

True if any change to a state object in this snapshot will throw.

@NonNull Snapshot

The root snapshot for this snapshot.

boolean

Whether there are any pending changes in this snapshot.

void

The set of state objects that have been modified in this snapshot.

@NonNull MutableSnapshot
takeNestedMutableSnapshot(
    Function1<@NonNull ObjectUnit> readObserver,
    Function1<@NonNull ObjectUnit> writeObserver
)

Take a mutable snapshot of the state values in this snapshot.

@NonNull Snapshot
takeNestedSnapshot(Function1<@NonNull ObjectUnit> readObserver)

Take a snapshot of the state values in this snapshot.

Inherited methods

From androidx.compose.runtime.snapshots.Snapshot
final @NonNull T
<T extends Object> enter(@NonNull Function0<@NonNull T> block)

Enter the snapshot.

int

The snapshot id of the snapshot.

final Snapshot

Enter the snapshot, returning the previous Snapshot for leaving this snapshot later using unsafeLeave.

final void

Leave the snapshot, restoring the oldSnapshot before returning.

Public methods

apply

public @NonNull SnapshotApplyResult apply()

Apply the changes made to state objects in this snapshot to the global state, or to the parent snapshot if this is a nested mutable snapshot.

Once this method returns all changes made to this snapshot are atomically visible as the global state of the state object or to the parent snapshot.

While a snapshot is active (after it is created but before apply or dispose is called) requires resources to track the values in the snapshot. Once a snapshot is no longer needed it should be either applied by calling apply or disposed by calling dispose. A snapshot that has been had is apply called can also have dispose called on it. However, calling apply after calling dispose will throw an exception.

Leaving a snapshot active could cause hard to diagnose memory leaks values are maintained by state objects for unneeded snapshots. Take care to always call dispose on any snapshot.

dispose

public void dispose()

Dispose the snapshot. Neglecting to dispose a snapshot will result in difficult to diagnose memory leaks as it indirectly causes all state objects to maintain its value for the un-disposed snapshot.

getReadOnly

public boolean getReadOnly()

True if any change to a state object in this snapshot will throw.

getRoot

public @NonNull Snapshot getRoot()

The root snapshot for this snapshot. For non-nested snapshots this is always this. For nested snapshot it is the parent's root.

hasPendingChanges

public boolean hasPendingChanges()

Whether there are any pending changes in this snapshot. These changes are not visible until the snapshot is applied.

setModified

public void setModified(IdentityArraySet<@NonNull StateObject> modified)

The set of state objects that have been modified in this snapshot.

takeNestedMutableSnapshot

public @NonNull MutableSnapshot takeNestedMutableSnapshot(
    Function1<@NonNull ObjectUnit> readObserver,
    Function1<@NonNull ObjectUnit> writeObserver
)

Take a mutable snapshot of the state values in this snapshot. Entering this snapshot by calling enter allows state objects to be modified that are not visible to the this, the parent snapshot, until the apply is called.

Applying a nested snapshot, by calling apply, applies its change to, this, the parent snapshot. For a change to be visible globally, all the parent snapshots need to be applied until the root snapshot is applied to the global state.

All nested snapshots need to be disposed by calling dispose before resources associated with this snapshot can be collected. Nested active snapshots are still valid after the parent has been disposed but calling apply will fail.

takeNestedSnapshot

public @NonNull Snapshot takeNestedSnapshot(Function1<@NonNull ObjectUnit> readObserver)

Take a snapshot of the state values in this snapshot. The resulting Snapshot is read-only. All nested snapshots need to be disposed by calling dispose before resources associated with this snapshot can be collected. Nested snapshots are still valid after the parent has been disposed.