ManagedRetainedValuesStore

A ManagedRetainedValuesStore is the default implementation of RetainedValuesStore that can be used to define custom retention periods in the composition hierarchy.

Instances of ManagedRetainedValuesStore can only be installed by LocalRetainedValuesStoreProvider in one location and composition hierarchy at a time. Repositioning a 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 disableRetainingExitedValues and enableRetainingExitedValues.

When the store is no longer needed, you must call dispose on it to ensure that any retained values are released and get calls to RetainObserver.onRetired. Failure to do so may result in memory leaks and orphaned jobs.

To create a ManagedRetainedValuesStore that is owned entirely within the composition hierarchy, you can use retainManagedRetainedValuesStore to create a ManagedRetainedValuesStore that is automatically scoped to the parent RetainedValuesStore and disposed when no longer retained.

Summary

Public constructors
Cmn

Public functions
Unit

This function will cause the store to never retain values that exit the composition hierarchy.
Cmn
Unit

Releases the store so that it will never retain exited values.
Cmn
Unit

Request that this store should retain exited values the next time that the tracked content exites the composition.
Cmn
open Any?
getExitedValueOrElse(key: Any, defaultValue: Any?)

If this store is currently retaining exited values and has a value previously created with the given key, its original record is returned and removed from the list of exited kept objects that this store is tracking.
Cmn
open Unit

Invoked to indicate that all content has finished entering the composition for the first time after the store is installed.
Cmn
open Unit

Invoked to indicate that the associated content is about to start leaving composition.
Cmn
open Unit
saveExitingValue(key: Any, value: Any?)

Invoked when a retained value is exiting composition while this store is retaining exited values.
Cmn

Public properties
Boolean

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-beta02
ManagedRetainedValuesStore()

Public functions

disableRetainingExitedValues

Cmn
Added in 1.10.0-beta02
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 ForgetfulRetainedValuesStore.

See also
enableRetainingExitedValues

dispose

Cmn
Added in 1.10.0-beta02
fun dispose(): Unit

Releases the store so that it will never retain exited values. All retained exited values are immediately retired. This should be used whenever a ManagedRetainedValuesStore is no longer used to ensure correct cleanup of its retained values.

Calling this function is equivalent to calling disableRetainingExitedValues, but prohibits future calls to enableRetainingExitedValues. If this function has already been called on a given store, subsequent calls will do nothing.

It is safe to install a disposed ManagedRetainedValuesStore in the composition hierarchy since exited values under this scope won't be retained and therefore can't leak. Installing a disposed ManagedRetainedValuesStore behaves the same as if you had installed the ForgetfulRetainedValuesStore.

Calls to 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-beta02
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.

ManagedRetainedValuesStores are initialized in the enabled state.

Throws
kotlin.IllegalStateException

if dispose has been called.
See also
disableRetainingExitedValues

getExitedValueOrElse

Cmn 
open fun getExitedValueOrElse(key: Any, defaultValue: Any?): Any?

If this store is currently retaining exited values and has a value previously created with the given key, 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: Any

The keys to resolve a retained value that has left composition
defaultValue: Any?

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 key.
Returns
Any?

A retained value for key if there is one and it hasn't already re-entered composition, otherwise defaultValue.

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 LocalRetainedValuesStoreProvider. 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 RetainObserver.onRetired for all discarded values that implement RetainObserver following the threading guarantees specified in 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 LocalRetainedValuesStoreProvider. 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 getExitedValueOrElse.

The given key are not guaranteed to be unique. To handle duplicate keys, implementors should return retained values with the same keys from getExitedValueOrElse in the opposite order they are received by saveExitingValue.

If the implementation of this store does not accept this value into its kept exited object list, it MUST call RetainObserver.onRetired if value implements RetainObserver, following the threading guarantees specified in RetainObserver's documentation.

This method is always called from the applier thread.

Public properties

isRetainingExitedValues

Cmn
Added in 1.10.0-beta02
val isRetainingExitedValues: Boolean

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