Google is committed to advancing racial equity for Black communities. See how.

Snapshot

sealed class Snapshot
kotlin.Any
   ↳ androidx.compose.runtime.snapshots.Snapshot

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.

Snapshots can be nested by calling takeNestedSnapshot.

Summary

Public methods
open Unit

Dispose the snapshot.

T
enter(block: () -> T)

Enter the snapshot.

abstract Boolean

Whether there are any pending changes in this snapshot.

abstract Snapshot
takeNestedSnapshot(readObserver: SnapshotReadObserver? = null)

Take a snapshot of the state values in this snapshot.

Companion functions
T
global(block: () -> T)

Escape the current snapshot, if there is one.

Unit

Notify the snapshot that all objects created in this snapshot to this point should be considered initialized.

T
observe(readObserver: SnapshotReadObserver? = null, writeObserver: SnapshotWriteObserver? = null, block: () -> T)

Observe reads and or write of state objects in the current thread.

Int

() -> Unit

Register an apply listener that is called back when snapshots are applied to the global state.

() -> Unit

Register an observer of the first write to the global state of a global state object since the last call to sendApplyNotifications.

Unit

Send any pending apply notifications for state objects changed outside a snapshot.

Properties
open Int

The snapshot id of the snapshot.

abstract Boolean

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

abstract Snapshot

The root snapshot for this snapshot.

Companion properties
Snapshot

Return the thread's active snapshot.

Public methods

dispose

open fun dispose(): Unit

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.

enter

inline fun <T> enter(block: () -> T): T

Enter the snapshot. In block all state objects have the value associated with this snapshot. The value of currentSnapshot will be this snapshot until this block returns or a nested call to enter is called. When block returns, the previous current snapshot is restored if there was one.

All changes to state object inside block are isolated to this snapshot and are not visible to other snapshot or as global state. If this is a readonly snapshot, any changes to state objects will throw an IllegalStateException.

For a MutableSnapshot, changes made to a snapshot inside block can be applied atomically to the global state (or to its parent snapshot if it is a nested snapshot) by calling MutableSnapshot.apply.

hasPendingChanges

abstract fun hasPendingChanges(): Boolean

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

takeNestedSnapshot

abstract fun takeNestedSnapshot(readObserver: SnapshotReadObserver? = null): Snapshot

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.

Properties

id

open var id: Int

The snapshot id of the snapshot. This is a unique number from a monotonically increasing value for each snapshot taken.

readonly

abstract val readonly: Boolean

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

root

abstract val root: Snapshot

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

Companion functions

global

inline fun <T> global(block: () -> T): T

Escape the current snapshot, if there is one. All state objects will have the value associated with the global while the block lambda is executing.

Return
the result of block

notifyObjectsInitialized

fun notifyObjectsInitialized(): Unit

Notify the snapshot that all objects created in this snapshot to this point should be considered initialized. If any state object is are modified passed this point it will appear as modified in the snapshot and any applicable SnapshotWriteObserver will be called for the object and the object will be part of the a set of mutated objects sent to any applicable SnapshotApplyObserver.

Unless notifyObjectsInitialized is called, state objects created in a snapshot are not considered modified by the snapshot even if they are modified after construction.

Compose uses this between phases of composition to allow observing changes to state objects create in a previous phase.

observe

fun <T> observe(
    readObserver: SnapshotReadObserver? = null,
    writeObserver: SnapshotWriteObserver? = null,
    block: () -> T
): T

Observe reads and or write of state objects in the current thread.

This only affects the current snapshot (if any) and any new snapshots create from takeSnapshot and takeMutableSnapshot. It will not affect any snapshots previous created even if Snapshot.enter is called in block.

Parameters
readObserver: SnapshotReadObserver? = null called when any state object is read.
writeObserver: SnapshotWriteObserver? = null called when a state object is created or just before it is written to the first time in the snapshot or a nested mutable snapshot. This might be called several times for the same object if nested mutable snapshots are created.

openSnapshotCount

fun openSnapshotCount(): Int

registerApplyObserver

fun registerApplyObserver(observer: SnapshotApplyObserver): () -> Unit

Register an apply listener that is called back when snapshots are applied to the global state.

Return
a lambda that, when called, unregisters observer.

registerGlobalWriteObserver

fun registerGlobalWriteObserver(observer: SnapshotWriteObserver): () -> Unit

Register an observer of the first write to the global state of a global state object since the last call to sendApplyNotifications.

Composition uses this to schedule a new composition whenever a state object that was read in composition is modified.

State objects can be sent to the apply observer that have not been sent to global write observers. This happens for state objects inside MutableSnapshot that is later applied by calling MutableSnapshot.apply.

This should only be used to determine if a call to sendApplyNotifications should be scheduled to be called.

Return
a lambda that, when called, unregisters observer.

sendApplyNotifications

fun sendApplyNotifications(): Unit

Send any pending apply notifications for state objects changed outside a snapshot.

Apply notifications for state objects modified outside snapshot are deferred until method is called. This method is implicitly called whenever a non-nested MutableSnapshot is applied making its changes visible to all new, non-nested snapshots.

Composition schedules this to be called after changes to state objects are detected an observer registered with registerGlobalWriteObserver.

Companion properties

current

val current: Snapshot

Return the thread's active snapshot. If no thread snapshot is active then the current global snapshot is used.