RetainedEffect

@Composable
@NonRestartableComposable
fun RetainedEffect(key1: Any?, effect: RetainedEffectScope.() -> RetainedEffectResult): Unit

A side effect of composition that must run for any new unique value of key1 and must be reversed or cleaned up if key1 changes or if the RetainedEffect permanently leaves composition.

A RetainedEffect tracks the lifecycle of retained content. If the current RetainedValuesStore is retaining values because its managed content is being transiently destroyed, the RetainedEffect is kept alive. From this state, the RetainedEffect can either:

• Be retired because the RetainedValuesStore is destroyed without its content being restored

• Be retired if the RetainedValuesStore's content re-enters the composition but does not include this RetainedEffect or invokes it with different keys

• Be restored to the recreated composition hierarchy. In this case, the RetainedEffect does not execute any callbacks.

If a RetainedEffect is removed from the composition hierarchy when the RetainedValuesStore is not retaining exited values, then the scope will immediately be retired and behave like a androidx.compose.runtime.DisposableEffect. Retirement has the same timing guarantees as RetainObserver.onRetired.

A RetainedEffect's key is a value that defines the identity of the RetainedEffect. If a RetainedEffect is recomposed with different keys, a new effect will be created and the previous effect will be retired. If the current RetainedValuesStore is not retaining exited values, the retirement happens before the new effect is started. Otherwise, the prior instance of the effect will continue to be retained for possible restoration until the scope stops retaining exited values.

RetainedEffect may be used to initialize or subscribe to a key and reinitialize when a different key is provided. For example:

import androidx.compose.runtime.Composable
import androidx.compose.runtime.retain.RetainedEffect
import androidx.compose.runtime.retain.retain

@Composable
fun VideoPlayer(mediaUri: String) {
    val player = retain(mediaUri) { MediaPlayer(mediaUri) }

    // Initialize each player only once after we retain it.
    // If the uri (and therefore the player) change, we need to dispose the old player
    // and initialize the new one. Likewise, the player needs to be disposed of when
    // it stops being retained.
    RetainedEffect(player) {
        player.initialize()
        onRetire { player.close() }
    }

    // ...
}

A RetainedEffect must include a retire clause as the final statement in its effect block. If your operation does not require disposal it might be a androidx.compose.runtime.SideEffect instead, or a androidx.compose.runtime.LaunchedEffect if it launches a coroutine that should be managed by the composition.

There is guaranteed to be one call to retire for every call to effect. Both effect and retire will always be run on the composition's apply dispatcher and appliers are never run concurrent with themselves, one another, applying changes to the composition tree, or running androidx.compose.runtime.RememberObserver event callbacks.

@Composable
@NonRestartableComposable
fun RetainedEffect(vararg keys: Any?, effect: RetainedEffectScope.() -> RetainedEffectResult): Unit

A side effect of composition that must run for any new unique value of keys and must be reversed or cleaned up if keys changes or if the RetainedEffect permanently leaves composition.

A RetainedEffect tracks the lifecycle of retained content. If the current RetainedValuesStore is retaining values because its managed content is being transiently destroyed, the RetainedEffect is kept alive. From this state, the RetainedEffect can either:

• Be retired because the RetainedValuesStore is destroyed without its content being restored

• Be retired if the RetainedValuesStore's content re-enters the composition but does not include this RetainedEffect or invokes it with different keys

• Be restored to the recreated composition hierarchy. In this case, the RetainedEffect does not execute any callbacks.

If a RetainedEffect is removed from the composition hierarchy when the RetainedValuesStore is not retaining exited values, then the scope will immediately be retired and behave like a RetainedEffect. Retirement has the same timing guarantees as RetainObserver.onRetired.

A RetainedEffect's key is a value that defines the identity of the RetainedEffect. If a RetainedEffect is recomposed with different keys, a new effect will be created and the previous effect will be retired. If the current RetainedValuesStore is not retaining exited values, the retirement happens before the new effect is started. Otherwise, the prior instance of the effect will continue to be retained for possible restoration until the scope stops retaining exited values.

RetainedEffect may be used to initialize or subscribe to a key and reinitialize when a different key is provided. For example:

import androidx.compose.runtime.Composable
import androidx.compose.runtime.retain.RetainedEffect
import androidx.compose.runtime.retain.retain

@Composable
fun VideoPlayer(mediaUri: String) {
    val player = retain(mediaUri) { MediaPlayer(mediaUri) }

    // Initialize each player only once after we retain it.
    // If the uri (and therefore the player) change, we need to dispose the old player
    // and initialize the new one. Likewise, the player needs to be disposed of when
    // it stops being retained.
    RetainedEffect(player) {
        player.initialize()
        onRetire { player.close() }
    }

    // ...
}

A RetainedEffect must include a retire clause as the final statement in its effect block. If your operation does not require disposal it might be a androidx.compose.runtime.SideEffect instead, or a androidx.compose.runtime.LaunchedEffect if it launches a coroutine that should be managed by the composition.

There is guaranteed to be one call to retire for every call to effect. Both effect and retire will always be run on the composition's apply dispatcher and appliers are never run concurrent with themselves, one another, applying changes to the composition tree, or running androidx.compose.runtime.RememberObserver event callbacks.

@Composable
@NonRestartableComposable
fun RetainedEffect(key1: Any?, key2: Any?, effect: RetainedEffectScope.() -> RetainedEffectResult): Unit

A side effect of composition that must run for any new unique value of key1 or key2 and must be reversed or cleaned up if key1 or key2 changes or if the RetainedEffect permanently leaves composition.

A RetainedEffect tracks the lifecycle of retained content. If the current RetainedValuesStore is retaining values because its managed content is being transiently destroyed, the RetainedEffect is kept alive. From this state, the RetainedEffect can either:

• Be retired because the RetainedValuesStore is destroyed without its content being restored

• Be retired if the RetainedValuesStore's content re-enters the composition but does not include this RetainedEffect or invokes it with different keys

• Be restored to the recreated composition hierarchy. In this case, the RetainedEffect does not execute any callbacks.

If a RetainedEffect is removed from the composition hierarchy when the RetainedValuesStore is not retaining exited values, then the scope will immediately be retired and behave like a androidx.compose.runtime.DisposableEffect. Retirement has the same timing guarantees as RetainObserver.onRetired.

A RetainedEffect's key is a value that defines the identity of the RetainedEffect. If a RetainedEffect is recomposed with different keys, a new effect will be created and the previous effect will be retired. If the current RetainedValuesStore is not retaining exited values, the retirement happens before the new effect is started. Otherwise, the prior instance of the effect will continue to be retained for possible restoration until the scope stops retaining exited values.

RetainedEffect may be used to initialize or subscribe to a key and reinitialize when a different key is provided. For example:

import androidx.compose.runtime.Composable
import androidx.compose.runtime.retain.RetainedEffect
import androidx.compose.runtime.retain.retain

@Composable
fun VideoPlayer(mediaUri: String) {
    val player = retain(mediaUri) { MediaPlayer(mediaUri) }

    // Initialize each player only once after we retain it.
    // If the uri (and therefore the player) change, we need to dispose the old player
    // and initialize the new one. Likewise, the player needs to be disposed of when
    // it stops being retained.
    RetainedEffect(player) {
        player.initialize()
        onRetire { player.close() }
    }

    // ...
}

A RetainedEffect must include a retire clause as the final statement in its effect block. If your operation does not require disposal it might be a androidx.compose.runtime.SideEffect instead, or a androidx.compose.runtime.LaunchedEffect if it launches a coroutine that should be managed by the composition.

There is guaranteed to be one call to retire for every call to effect. Both effect and retire will always be run on the composition's apply dispatcher and appliers are never run concurrent with themselves, one another, applying changes to the composition tree, or running androidx.compose.runtime.RememberObserver event callbacks.

@Composable
@NonRestartableComposable
fun RetainedEffect(
    key1: Any?,
    key2: Any?,
    key3: Any?,
    effect: RetainedEffectScope.() -> RetainedEffectResult
): Unit

A side effect of composition that must run for any new unique value of key1, key2, or key3 and must be reversed or cleaned up if key1, key2, or key3 changes or if the RetainedEffect permanently leaves composition.

A RetainedEffect tracks the lifecycle of retained content. If the current RetainedValuesStore is retaining values because its managed content is being transiently destroyed, the RetainedEffect is kept alive. From this state, the RetainedEffect can either:

• Be retired because the RetainedValuesStore is destroyed without its content being restored

• Be retired if the RetainedValuesStore's content re-enters the composition but does not include this RetainedEffect or invokes it with different keys

• Be restored to the recreated composition hierarchy. In this case, the RetainedEffect does not execute any callbacks.

If a RetainedEffect is removed from the composition hierarchy when the RetainedValuesStore is not retaining exited values, then the scope will immediately be retired and behave like a androidx.compose.runtime.DisposableEffect. Retirement has the same timing guarantees as RetainObserver.onRetired.

A RetainedEffect's key is a value that defines the identity of the RetainedEffect. If a RetainedEffect is recomposed with different keys, a new effect will be created and the previous effect will be retired. If the current RetainedValuesStore is not retaining exited values, the retirement happens before the new effect is started. Otherwise, the prior instance of the effect will continue to be retained for possible restoration until the scope stops retaining exited values.

RetainedEffect may be used to initialize or subscribe to a key and reinitialize when a different key is provided. For example:

import androidx.compose.runtime.Composable
import androidx.compose.runtime.retain.RetainedEffect
import androidx.compose.runtime.retain.retain

@Composable
fun VideoPlayer(mediaUri: String) {
    val player = retain(mediaUri) { MediaPlayer(mediaUri) }

    // Initialize each player only once after we retain it.
    // If the uri (and therefore the player) change, we need to dispose the old player
    // and initialize the new one. Likewise, the player needs to be disposed of when
    // it stops being retained.
    RetainedEffect(player) {
        player.initialize()
        onRetire { player.close() }
    }

    // ...
}

A RetainedEffect must include a retire clause as the final statement in its effect block. If your operation does not require disposal it might be a androidx.compose.runtime.SideEffect instead, or a androidx.compose.runtime.LaunchedEffect if it launches a coroutine that should be managed by the composition.

There is guaranteed to be one call to retire for every call to effect. Both effect and retire will always be run on the composition's apply dispatcher and appliers are never run concurrent with themselves, one another, applying changes to the composition tree, or running androidx.compose.runtime.RememberObserver event callbacks.