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: (Any) -> Unit = 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 reads and or write of state objects in the current thread. |
| Int | |
| ObserverHandle |
registerApplyObserver(observer: (Set<Any>, Snapshot) -> Unit)Register an apply listener that is called back when snapshots are applied to the global state. |
| ObserverHandle |
registerGlobalWriteObserver(observer: (Any) -> 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. |
| MutableSnapshot |
takeMutableSnapshot(readObserver: (Any) -> Unit = null, writeObserver: (Any) -> Unit = null)Take a snapshot of the current value of all state objects that also allows the state to be changed and later atomically applied when MutableSnapshot.apply is called. |
| Snapshot |
takeSnapshot(readObserver: (Any) -> Unit = null)Take a snapshot of the current value of all state objects. |
| R |
withMutableSnapshot(block: () -> R)Take a MutableSnapshot and run block within it. |
| 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:&