# RetainObserver

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

  ```
  interface RetainObserver
  ```

*** ** * ** ***

Objects implementing this interface are notified of their usage in `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)`.

An object is retained when its first captured as the return result of the calculation block used with `retain`. It is retired when the `retain` invocation is removed from composition and not being retained. In between being retained and retired, objects may enter and exit the composition. This occurs when the retained object is removed from composition but transiently held on to if the removed portion of the composition hierarchy is to be restored with its retained state.

When objects implementing this interface are retained or entering composition together, their `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetained()` and `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onEnteredComposition()` callbacks are dispatched in the order that they were added to the composition. When objects exit composition together, the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onExitedComposition()` callback is invoked in the opposite order that the objects appear in the composition hierarchy. There are no ordering guarantees around when or in what order the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetired()` callback may be dispatched.

Objects that implement this interface and used in the composition as the result of a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/remember.composable#remember(kotlin.Function0)` call will receive no callbacks to this interface, and are encouraged to implement `https://developer.android.com/reference/kotlin/androidx/compose/runtime/RememberObserver` either additionally or instead of `RetainObserver`.

## Summary

| ### Public functions |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onEnteredComposition()()` Called after `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetained()` or `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onExitedComposition()` to indicate that content in the composition hierarchy has successfully realized this value as the return result of a call to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)`. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onExitedComposition()()` Called after `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onEnteredComposition()` to indicate that the Composition this value was retained for is no longer referencing this object. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetained()()` Called when this object is successfully `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)`ed. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetired()()` Called to indicate that this value was not used by a composition and will not be retained further. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onUnused()()` Called when this object is returned by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)` but not successfully applied in a composition. | Cmn |

## Public functions

### onEnteredComposition

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

```
fun onEnteredComposition(): Unit
```

Called after `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetained()` or `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onExitedComposition()` to indicate that content in the composition hierarchy has successfully realized this value as the return result of a call to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)`. A composition is currently referencing this object.

This callback has the same ordering guarantees as `https://developer.android.com/reference/kotlin/androidx/compose/runtime/RememberObserver#onRemembered()`, relative both to other RetainObservers and other `https://developer.android.com/reference/kotlin/androidx/compose/runtime/RememberObserver` instances. This function can be called multiple times and will be invoked only after `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetained()` or `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onExitedComposition()`.

This callback is always invoked on the *current* applier thread. If the retained value has moved to a different composition, this may be a different thread than the one it was `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetained()` on.

### onExitedComposition

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

```
fun onExitedComposition(): Unit
```

Called after `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onEnteredComposition()` to indicate that the Composition this value was retained for is no longer referencing this object. This object will be retained until `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetired()` or `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onEnteredComposition()` is called, at which point it can either be released entirely or reused, respectively.

This callback is invoked in the opposite order as `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onEnteredComposition()` and has the same ordering guarantees as `https://developer.android.com/reference/kotlin/androidx/compose/runtime/RememberObserver#onForgotten()`, relative both to other RetainObservers and other `https://developer.android.com/reference/kotlin/androidx/compose/runtime/RememberObserver` instances.

This callback is always invoked on the current applier thread. It will match the last thread used by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onEnteredComposition()`.

### onRetained

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

```
fun onRetained(): Unit
```

Called when this object is successfully `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)`ed. This occurs when the result of a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)` call is successfully created and installed in a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` and has the same timing as `https://developer.android.com/reference/kotlin/androidx/compose/runtime/RememberObserver#onRemembered()` for the initial retention of a value.

When the composition is successful, this call will be immediately followed by a call to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onEnteredComposition()`.

If the composition is abandoned and the associated `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` is currently retaining exited values, the value will be retained and may be used in a future (successful) composition. This is the only scenario in which it is possible for a RetainObserver to experience a lifecycle of Retained -\> Retired without receiving any calls to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onEnteredComposition()`.

If the composition is unsuccessful and the associated `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` is not retaining exited values, this callback will be skipped and `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onUnused()` will be called instead.

This callback is always invoked on the applier thread.

### onRetired

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

```
fun onRetired(): Unit
```

Called to indicate that this value was not used by a composition and will not be retained further. This value will never be reused unless it's returned as a result of the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)` calculation block (and receives another call to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetained()`).

This callback can be invoked after either `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetained()`, to indicate that the value was created but the composition was abandoned (see `https://developer.android.com/reference/kotlin/androidx/compose/runtime/RememberObserver#onAbandoned()`), or after `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onExitedComposition()`. When called after `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onExitedComposition()`, this indicates that this value was previously used in composition, but the content retaining this value has been removed and will not be returned to (either because the relevant `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` was not retaining at the time of removal, or the removed content was not restored after all retained objects were restored).

Implementations of this method can be used to release resources held by the instance.

This callback does not guarantee any relative ordering among other RetainObserver instances. Similarly, because the timing of a retainment period comes with no guarantees, there could be an arbitrary delay between `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onExitedComposition()` and when this method is called --- anywhere between immediately after exiting the composition, a single frame later, or indefinitely later.

This callback may execute on any thread. By default in Compose UI, this callback always executes on the main thread. If a value is retired because it left composition and its scope is not retaining exited values, the callback will execute on the current applier thread. If a value is retired because the retaining `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainedValuesStore` was disposed while orphaned from a composition (and therefore with no designated applier thread), this callback will execute on the thread that triggered the disposal. This may be a different applier thread or the main thread.

### onUnused

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

```
fun onUnused(): Unit
```

Called when this object is returned by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)` but not successfully applied in a composition. This is analogous to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/RememberObserver#onAbandoned()`.

This method is only called when this value is returned by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/retain.composable#retain(kotlin.Function0)` and will not receive a call to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/retain/RetainObserver#onRetained()`.

This callback is always invoked on the applier thread.