# RetainedValuesStore

Artifact: [androidx.compose.runtime:runtime-retain](https://developer.android.com/jetpack/androidx/releases/compose-runtime) [View Source](https://cs.android.com/search?q=file:androidx/compose/runtime/retain/RetainedValuesStore.kt+class:androidx.compose.runtime.retain.RetainedValuesStore) Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.10.0) Common/All
- Cmn

  ```
  interface RetainedValuesStore
  ```
Known direct subclasses [ForgetfulRetainedValuesStore](https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ForgetfulRetainedValuesStore), [ManagedRetainedValuesStore](https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore)

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ForgetfulRetainedValuesStore` | The `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ForgetfulRetainedValuesStore` is an implementation of `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` that is incapable of retaining any exited values. |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore` | A `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore` is the default implementation of `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` that can be used to define custom retention periods in the composition hierarchy. |

*** ** * ** ***

A `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` acts as a storage area for objects being retained. When a retained value is in the composition, then the composition hierarchy owns the value and retains it there. `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` defines what happens to a retained value when it leaves and re-enters the compositions.

Retained objects are offered to implementations of `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` as they exit the composition. Implementations may continue to retained such exited objects until they are restored into the composition hierarchy when the removed content is recreated. Implementations define whether, how, and for how long retained values should be stored after they leave the composition.

The general pattern for retention is as follows:

1. The RetainedValuesStore receives a call to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#onContentExitComposition()` signaling that the owned content is about to be removed.

2. Transient content removal begins. The content is recomposed, removed from the hierarchy, and remembered values are forgotten. Values remembered by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)` leave the composition but are not yet released. Every value returned by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)` will be passed as an argument to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#saveExitingValue(kotlin.Any,kotlin.Any)` so that it can later be returned by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#consumeExitedValueOrDefault(kotlin.Any,kotlin.Any)`.

3. An arbitrary amount of time passes, and the store is installed in the composition hierarchy again along with its content. When a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)` call is invoked during the restoration, it calls `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#consumeExitedValueOrDefault(kotlin.Any,kotlin.Any)`. If all the input keys match a retained value, the previous result is returned and the retained value is removed from the pool of restorable objects that exited the previous composition. This step may be skipped if it becomes impossible to return to the transiently removed content while this store is retaining exited values.

4. The content finishes composing after being restored, and the entire frame completes. `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#onContentEnteredComposition()` is invoked to signal the complete consumption of all retained exited values. Any values that are retained and not currently used in a composition (and therefore not restored by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#consumeExitedValueOrDefault(kotlin.Any,kotlin.Any)`) are then immediately discarded.

A given `RetainedValuesStore` should only be used by a single `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Recomposer` at a time. It can move between recomposers (for example, when the Window is recreated), but should never be used by two Recomposers simultaneously. Implementations may or may not support being used in multiple places simultaneously. Unless otherwise specified, it's assumed that an implementation of `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` should only be installed at one location in a single composition hierarchy.

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)` |   |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/package-summary#LocalRetainedValuesStore()` |   |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore` |   |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ForgetfulRetainedValuesStore` |   |

## Summary

| ### Public functions |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#consumeExitedValueOrDefault(kotlin.Any,kotlin.Any)(key: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html, defaultValue: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?)` If this store is currently retaining exited values and has a value previously created with the given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#consumeExitedValueOrDefault(kotlin.Any,kotlin.Any)`, its original record is returned and removed from the list of exited kept objects that this store is tracking. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#onContentEnteredComposition()()` Invoked to indicate that all content has finished entering the composition for the first time after the store is installed. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#onContentExitComposition()()` Invoked to indicate that the associated content is *about* to start leaving composition. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#saveExitingValue(kotlin.Any,kotlin.Any)(key: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html, value: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?)` Invoked when a retained value is exiting composition while this store is retaining exited values. | Cmn |

## Public functions

### consumeExitedValueOrDefault

Cmn Added in [1.11.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.11.0)

```
fun consumeExitedValueOrDefault(key: Any, defaultValue: Any?): Any?
```

If this store is currently retaining exited values and has a value previously created with the given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#consumeExitedValueOrDefault(kotlin.Any,kotlin.Any)`, its original record is returned and removed from the list of exited kept objects that this store is tracking.

This method is always called from the composition thread.

| Parameters |
|---|---|
| `key: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html` | The keys to resolve a retained value that has left composition |
| `defaultValue: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?` | A value to be returned if there are no retained values that have exited composition and are being held by this RetainedValuesStore for the given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#consumeExitedValueOrDefault(kotlin.Any,kotlin.Any)`. |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?` | A retained value for `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#consumeExitedValueOrDefault(kotlin.Any,kotlin.Any)` if there is one and it hasn't already re-entered composition, otherwise `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#consumeExitedValueOrDefault(kotlin.Any,kotlin.Any)`. |

### onContentEnteredComposition

Cmn Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.10.0)

```
fun onContentEnteredComposition(): Unit
```

Invoked to indicate that all content has finished entering the composition for the first time after the store is installed. Any unconsumed retained values should be discarded at this time.

This function is called by the library when the store is installed with `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/LocalRetainedValuesStoreProvider.composable#LocalRetainedValuesStoreProvider(androidx.compose.runtime.retain.RetainedValuesStore,kotlin.Function0)`. It should not be invoked directly in production code. The default installation will always invoke this callback on the applier thread for the content's latest destination, which may differ when moved between compositions.

Implementors of this function MUST call `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetired()` for all discarded values that implement `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver` following the threading guarantees specified in `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver`'s documentation.

### onContentExitComposition

Cmn Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.10.0)

```
fun onContentExitComposition(): Unit
```

Invoked to indicate that the associated content is *about* to start leaving composition. The store should make any necessary preparations to start retaining values as they exit the composition.

This function is called by the library when the store is installed with `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/LocalRetainedValuesStoreProvider.composable#LocalRetainedValuesStoreProvider(androidx.compose.runtime.retain.RetainedValuesStore,kotlin.Function0)`. It should not be invoked directly in production code. The default installation will always invoke this callback on the applier thread that content entered composition on.

### saveExitingValue

Cmn Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.10.0)

```
fun saveExitingValue(key: Any, value: Any?): Unit
```

Invoked when a retained value is exiting composition while this store is retaining exited values. It is up to the implementation of this method to decide whether and how to store these values so that they can later be retrieved by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#consumeExitedValueOrDefault(kotlin.Any,kotlin.Any)`.

The given `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#saveExitingValue(kotlin.Any,kotlin.Any)` are not guaranteed to be unique. To handle duplicate keys, implementors should return retained values with the same keys from `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#consumeExitedValueOrDefault(kotlin.Any,kotlin.Any)` in the opposite order they are received by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#saveExitingValue(kotlin.Any,kotlin.Any)`.

If the implementation of this store does not accept this value into its kept exited object list, it MUST call `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetired()` if `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore#saveExitingValue(kotlin.Any,kotlin.Any)` implements `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver`, following the threading guarantees specified in `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver`'s documentation.

This method is always called from the applier thread.