# ManagedRetainedValuesStore

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/ManagedRetainedValuesStore.kt+class:androidx.compose.runtime.retain.ManagedRetainedValuesStore) Added in [1.10.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.10.0) Common/All
- Cmn

  ```
  class ManagedRetainedValuesStore : RetainedValuesStore
  ```

*** ** * ** ***

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.

Instances of `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore` can only be installed by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/LocalRetainedValuesStoreProvider.composable#LocalRetainedValuesStoreProvider(androidx.compose.runtime.retain.RetainedValuesStore,kotlin.Function0)` in one location and composition hierarchy at a time. Repositioning a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore` is allowed within a single frame or by removing the store and adding it again in a later frame.

This store retains all exited values when the provider (and its content) are removed from the composition. Optionally, you can toggle whether this scope will retain exited values via `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#disableRetainingExitedValues()` and `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#enableRetainingExitedValues()`.

When the store is no longer needed, you must call `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#dispose()` on it to ensure that any retained values are released and get calls to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetired()`. Failure to do so may result in memory leaks and orphaned jobs.

To create a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore` that is owned entirely within the composition hierarchy, you can use `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retainManagedRetainedValuesStore.composable#retainManagedRetainedValuesStore()` to create a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore` that is automatically scoped to the parent `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` and disposed when no longer retained.

## Summary

| ### Public constructors |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#ManagedRetainedValuesStore()()` | Cmn |

| ### Public functions |
|---|---|---|
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#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/ManagedRetainedValuesStore#disableRetainingExitedValues()()` This function will cause the store to never retain values that exit the composition hierarchy. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#dispose()()` Releases the store so that it will never retain exited values. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#enableRetainingExitedValues()()` Request that this store should retain exited values the next time that the tracked content exites the composition. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#onContentEnteredComposition()()` Invoked to indicate that all content has finished entering the composition for the first time after the store is installed. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#onContentExitComposition()()` Invoked to indicate that the associated content is *about* to start leaving composition. | Cmn |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#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 properties |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#isRetainingExitedValues()` Indicates whether this store will continue to retain values in this store if they exit the composition hierarchy. | Cmn |

## Public constructors

### ManagedRetainedValuesStore

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

```
ManagedRetainedValuesStore()
```

## Public functions

### consumeExitedValueOrDefault

Cmn

```
open 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)`. |

### disableRetainingExitedValues

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

```
fun disableRetainingExitedValues(): Unit
```

This function will cause the store to never retain values that exit the composition hierarchy. If the store is currently retaining values that have exited the composition, they will be immediately disposed. If the store is already in this mode, nothing happens.

When retaining exited values is disabled, this store will behave the same as the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ForgetfulRetainedValuesStore`.

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#enableRetainingExitedValues()` |   |

### dispose

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

```
fun dispose(): Unit
```

Releases the store so that it will never retain exited values. All retained exited values are immediately `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetired()`. This should be used whenever a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore` is no longer used to ensure correct cleanup of its retained values.

Calling this function is equivalent to calling `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#disableRetainingExitedValues()`, but prohibits future calls to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#enableRetainingExitedValues()`. If this function has already been called on a given store, subsequent calls will do nothing.

It is safe to install a disposed `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore` in the composition hierarchy since exited values under this scope won't be retained and therefore can't leak. Installing a disposed `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore` behaves the same as if you had installed the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ForgetfulRetainedValuesStore`.

Calls to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetired()` for subsequently disposed values will be executed on the same thread this method is called on.

### enableRetainingExitedValues

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

```
fun enableRetainingExitedValues(): Unit
```

Request that this store should retain exited values the next time that the tracked content exites the composition. If this store is already in this mode, nothing happens.

`https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore`s are initialized in the enabled state.

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#dispose()` has been called. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/ManagedRetainedValuesStore#disableRetainingExitedValues()` |   |

### onContentEnteredComposition

Cmn

```
open 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

```
open 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

```
open 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.

## Public properties

### isRetainingExitedValues

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

```
val isRetainingExitedValues: Boolean
```

Indicates whether this store will continue to retain values in this store if they exit the composition hierarchy.