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()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 |
registerApplyObserver(observer: SnapshotApplyObserver)Register an apply listener that is called back when snapshots are applied to the global state. |
| () -> Unit |
registerGlobalWriteObserver(observer: SnapshotWriteObserver)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.